{"id":4967,"library":"jaraco-collections","title":"jaraco-collections","description":"jaraco.collections provides a suite of collection objects and utilities that complement Python's standard library `collections` module. It offers specialized data structures like `RangeMap`, `FrozenDict`, and `FoldedCaseKeyedDict`. The library is actively maintained, with its current version being 5.2.1, and releases occurring regularly.","status":"active","version":"5.2.1","language":"en","source_language":"en","source_url":"https://github.com/jaraco/jaraco.collections","tags":["collections","data-structures","utilities","dict-extensions","immutable-collections"],"install":[{"cmd":"pip install jaraco-collections","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required Python version.","package":"python","optional":false}],"imports":[{"symbol":"RangeMap","correct":"from jaraco.collections import RangeMap"},{"symbol":"FrozenDict","correct":"from jaraco.collections import FrozenDict"},{"symbol":"FoldedCaseKeyedDict","correct":"from jaraco.collections import FoldedCaseKeyedDict"},{"symbol":"Projection","correct":"from jaraco.collections import Projection"}],"quickstart":{"code":"from jaraco.collections import RangeMap\n\n# Create a RangeMap to associate values with key ranges\nprice_tiers = RangeMap({(0, 50): 'economy', (51, 100): 'standard', (101, float('inf')): 'premium'})\n\n# Retrieve values based on a key within a range\nprint(f\"Price 30 is in the {price_tiers[30]} tier\")\nprint(f\"Price 75 is in the {price_tiers[75]} tier\")\nprint(f\"Price 120 is in the {price_tiers[120]} tier\")\n\n# Example of FrozenDict (immutable dictionary)\nfrom jaraco.collections import FrozenDict\nf_dict = FrozenDict({'a': 1, 'b': 2})\nprint(f\"Frozen dict: {f_dict}\")\n# f_dict['c'] = 3 # This would raise a TypeError","lang":"python","description":"This quickstart demonstrates the use of `RangeMap` to map numerical ranges to specific values, and `FrozenDict` for an immutable dictionary. `RangeMap` is particularly useful for tiered pricing, scoring, or categorization based on continuous ranges."},"warnings":[{"fix":"Migrate away from `DictFilter`. Consider using dictionary comprehensions or other standard Python filtering patterns.","message":"The `DictFilter` class was removed in version 5.0.0. Users upgrading from pre-5.0.0 versions should refactor their code to use alternative filtering mechanisms.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"If an immutable or independent `Projection` is needed, create a deep copy of the original dictionary before creating the `Projection`, or convert the `Projection` to a new dictionary explicitly (e.g., `dict(my_projection)`).","message":"When using `Projection`, it maintains a reference to the original dictionary. Modifying the original dictionary after creating a `Projection` will also affect the `Projection`'s view.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Carefully define your `RangeMap` keys. For example, to cover all values from zero, you might start with `(0, upper_bound)` or use `float('-inf')` for truly open-ended lower bounds if using explicit tuples for ranges.","message":"The `RangeMap` implementation is inherently designed to be 'open-ended on one side' when defining ranges implicitly by sorted keys. Ensure your key definitions account for this behavior, especially at the boundaries.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure all `jaraco.*` packages in your environment are up-to-date and installed using modern `pip` or equivalent, especially when working with Python 3.9+. Consider upgrading all `jaraco.*` dependencies simultaneously.","message":"For users of multiple `jaraco.*` namespace packages (e.g., `jaraco.collections`, `jaraco.text`), significant changes in Python's namespace package handling (from `pkg_resources` to `pkgutil` to native namespace packages) can lead to import errors if not all `jaraco.*` packages are migrated or installed consistently.","severity":"gotcha","affected_versions":"Older versions, particularly when mixed with modern Python/packaging tools."}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}