jaraco-collections

Warnings

• breaking 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.
  Fix: Migrate away from `DictFilter`. Consider using dictionary comprehensions or other standard Python filtering patterns.
• gotcha 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.
  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)`).
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• pip install jaraco-collections Install latest version

Imports

• RangeMap

  from jaraco.collections import RangeMap

• FrozenDict

  from jaraco.collections import FrozenDict

• FoldedCaseKeyedDict

  from jaraco.collections import FoldedCaseKeyedDict

• Projection

  from jaraco.collections import Projection

Quickstart

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.

from jaraco.collections import RangeMap

# Create a RangeMap to associate values with key ranges
price_tiers = RangeMap({(0, 50): 'economy', (51, 100): 'standard', (101, float('inf')): 'premium'})

# Retrieve values based on a key within a range
print(f"Price 30 is in the {price_tiers[30]} tier")
print(f"Price 75 is in the {price_tiers[75]} tier")
print(f"Price 120 is in the {price_tiers[120]} tier")

# Example of FrozenDict (immutable dictionary)
from jaraco.collections import FrozenDict
f_dict = FrozenDict({'a': 1, 'b': 2})
print(f"Frozen dict: {f_dict}")
# f_dict['c'] = 3 # This would raise a TypeError