frozenlist

frozenlist is a specialized data structure that acts as a mutable list until you explicitly freeze it, after which it becomes immutable. The C extension implementation provides excellent runtime performance with minimal memory overhead compared to tuple conversion approaches. In production, I've primarily encountered it as a dependency of aiohttp where it's used for headers and other structures that need to be built up then locked.

The API is straightforward - standard list operations work until you call .freeze(), after which mutation attempts raise FrozenListError. The C implementation means negligible performance impact in hot paths. Memory usage is comparable to regular lists, and the freeze operation is O(1). Error messages are clear when you attempt mutations on frozen instances.

One quirk: you can't unfreeze a list, so plan your data flow accordingly. There's also no configuration to speak of - it does one thing and does it well. For most applications, you won't use this directly; it'll be pulled in as a transitive dependency. If you do need it directly, documentation is sparse but the API surface is small enough that reading the type stubs tells you everything.

FrozenList is a straightforward library that does one thing well: provides a list that can be frozen to become immutable. It's primarily used as a dependency in aiohttp and yarl, where preventing accidental mutation of shared state is critical. The API is dead simple - you work with it like a regular list until you call `.freeze()`, after which it becomes read-only.

From a security perspective, this is refreshingly minimal. There's no network code, no input parsing complexity, and no cryptographic operations to misconfigure. The C extension implementation is lean and has had few CVEs historically. Error handling is predictable - trying to modify a frozen list raises a clear RuntimeError with no information leakage. The library follows secure-by-default principles by making the immutability contract explicit and enforceable at runtime.

The main limitation is its narrow scope. You're essentially getting immutability enforcement for list-like objects, nothing more. It won't prevent deep mutations of contained objects, so you still need to think about whether nested structures need protection.

frozenlist is a C-accelerated data structure that gives you a mutable list that can be frozen into an immutable state. In production, it's a foundational piece used heavily by aiohttp for internal request/response headers. The implementation is lean and performant - the C extension provides excellent memory efficiency compared to pure Python alternatives.

Day-to-day usage is straightforward: create a FrozenList, manipulate it like a normal list, call freeze() when done, and it becomes immutable. The API is minimal by design - it implements MutableSequence when unfrozen and behaves like a tuple after freezing. Error handling is predictable: attempting mutations after freezing raises a clear RuntimeError. No logging hooks or complex configuration because it's a primitive data structure, not application infrastructure.

The main operational consideration is that this is a building block, not a feature-rich library. It does one thing well: provide an efficient freeze-once list. Performance under load is solid due to the C implementation, though the pure Python fallback exists for compatibility. Breaking changes between versions are rare since the API surface is intentionally tiny.