Install & Compatibility
Where this runs
tested against v5.2.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.174s · 32.6MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.1s · import 0.160s · 33MB
31MB installed
● package 31MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
RangeMap
✓ from jaraco.collections import RangeMap
FrozenDict
✓ from jaraco.collections import FrozenDict
FoldedCaseKeyedDict
✓ from jaraco.collections import FoldedCaseKeyedDict
Projection
✓ from jaraco.collections import Projection
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
Debug
Known issues
breakingThe `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.fixMigrate away from `DictFilter`. Consider using dictionary comprehensions or other standard Python filtering patterns.
affects: >=5.0.0
gotchaWhen 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.fixIf 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)`).
affects: All versions
gotchaThe `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.fixCarefully 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. affects: All versions
gotchaFor 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.fixEnsure 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.
affects: Older versions, particularly when mixed with modern Python/packaging tools.
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'jaraco.collections'
The `jaraco.collections` library is not installed in the current Python environment or the environment is not correctly activated.
fixInstall the library using pip: `pip install jaraco-collections` or ensure your virtual environment is activated.
TypeError: 'FrozenDict' object does not support item assignment
The `FrozenDict` class, a core component of `jaraco.collections`, is designed to be immutable, meaning its contents cannot be changed after creation.
fixDo not attempt to modify a `FrozenDict` after it has been created. If modification is needed, convert it to a standard `dict` first: `mutable_dict = dict(frozen_dict)`.
AttributeError: 'FrozenDict' object has no attribute 'update'
Like item assignment, methods that would modify a dictionary, such as `update()`, are not supported by the immutable `FrozenDict`.
fixIf you need to combine or update a `FrozenDict`, create a new dictionary with the desired changes, potentially by merging with other dictionaries: `new_frozen_dict = FrozenDict({**frozen_dict, **updates})` or `new_dict = dict(frozen_dict); new_dict.update(updates)`. AttributeError: module 'jaraco.collections' has no attribute 'DictFilter'
The `DictFilter` class was removed in version 5.0.0 of `jaraco.collections`.
fixUsers upgrading from pre-5.0.0 versions should refactor their code to use alternative filtering mechanisms, such as dictionary comprehensions or other standard Python filtering patterns.
Upgrade
Version history
5.2.1latest on PyPI · released Jun 21, 2025
Audit
Dependencies
pythonrequiredRequired Python version.