frozenlist

frozenlist provides FrozenList, a collections.abc.MutableSequence implementation that behaves like an ordinary Python list until .freeze() is called, after which any further mutation raises RuntimeError. It ships as part of the aio-libs project and is used internally by aiohttp and its ecosystem to lock down configuration and header collections once application setup has finished, preventing accidental mutation of shared state deep in a request-handling call stack.

The package includes two interchangeable implementations: a pure-Python reference version and a Cython/C++ extension compiled for CPython and free-threaded builds, selected automatically at import time (or forced to the pure-Python path via the FROZENLIST_NO_EXTENSIONS environment variable). Both expose the exact same interface, including hashing once frozen, so FrozenList instances can be used as dict keys or set members after being locked.

What You Get

• A FrozenList class implementing the complete collections.abc.MutableSequence interface (indexing, slicing, insert, append, extend, reverse, pop, etc.)
• A .freeze() method and .frozen property that toggle and expose the list’s mutability state at runtime
• Hashability once frozen, so a locked FrozenList can be used as a dict key or set member
• A high-performance Cython/C++ extension backend with an atomic frozen flag for free-threaded (no-GIL) Python builds, plus a pure-Python fallback selectable via FROZENLIST_NO_EXTENSIONS
• Correct __copy__ and __deepcopy__ behavior that preserves the frozen state of the copy

Common Use Cases

• Freezing a collection of HTTP headers or middleware after an aiohttp application finishes setup, so later code cannot silently mutate it
• Building a list incrementally during configuration/init and then locking it before handing it to concurrent request handlers
• Using a completed, frozen list as a hashable key in a cache or lookup dict
• Any general Python code that wants list semantics during a build-up phase and immutability guarantees afterward

Under The Hood

Architecture frozenlist ships two parallel implementations of the same public interface behind a single import: a pure-Python FrozenList in frozenlist/__init__.py and a Cython/C++ extension in frozenlist/_frozenlist.pyx, with the extension transparently substituted for the Python class at import time unless FROZENLIST_NO_EXTENSIONS is set. Both implementations register with collections.abc.MutableSequence and route every mutating method (__setitem__, __delitem__, insert, append, extend, remove, clear, pop, reverse, __iadd__) through a shared frozen-state guard that raises RuntimeError once .freeze() has been called, so behavior stays identical regardless of which backend is active; the C extension additionally uses atomic<bool> for its frozen flag rather than a plain attribute, making state checks safe under free-threaded (no-GIL) CPython.

Tech Stack The project targets Python 3.10+ and compiles its extension module from Cython source (_frozenlist.pyx, language = c++) via an in-tree PEP 517 build backend (packaging/pep517_backend) layered on setuptools >= 67; wheels are built and tested across platforms with cibuildwheel configured to use uv as its installer/build frontend for fast, reproducible environment provisioning. Code quality tooling includes ruff for import sorting and pyupgrade-style modernization, mypy for static typing, pytest for tests, and towncrier for changelog generation from per-PR news fragments.

Code Quality A single tests/test_frozenlist.py file exercises both backends through a shared FrozenListMixin test base, verifying full MutableSequence protocol conformance, freeze/hash semantics, __class_getitem__ generic subscripting, and both shallow and deep copy behavior with frozen-state preservation and circular-reference handling. CI runs this suite across the supported CPython version matrix plus PyPy, with mypy and ruff enforced via pre-commit hooks and coverage tracked through Codecov, giving the project a typed, tested, and continuously linted baseline for a codebase this small.

What Makes It Unique frozenlist isn’t conceptually novel — freezable/immutable list wrappers are a well-known pattern — but its dual pure-Python/Cython implementation, switchable at runtime via an environment variable, and its use of an atomic frozen flag specifically to stay correct under free-threaded Python builds, are deliberate, forward-looking engineering choices for what is otherwise a narrowly scoped utility that exists mainly to give the aiohttp ecosystem a safe way to lock down shared collections after setup.