or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

core-dictionary.mddeep-freezing.mdindex.mdjson-integration.md
tile.json

tessl/pypi-frozendict

A simple immutable dictionary implementation with hashing support and performance optimizations

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/frozendict@2.4.x

To install, run

npx @tessl/cli install tessl/pypi-frozendict@2.4.0

index.mddocs/

frozendict

A simple immutable dictionary implementation for Python that maintains the same API as the built-in dict type while guaranteeing immutability. It offers fast operations (often faster than dict), supports hashing when all values are hashable, includes pickle/unpickle functionality, and provides additional methods for creating new frozendict instances.

Package Information

  • Package Name: frozendict
  • Language: Python
  • Installation: pip install frozendict

Core Imports

from frozendict import frozendict

With additional features:

from frozendict import frozendict, deepfreeze, FrozendictJsonEncoder

Full feature import:

from frozendict import (
    frozendict, 
    deepfreeze, 
    register, 
    unregister,
    FrozendictJsonEncoder,
    c_ext,
    __version__
)

Submodule access:

import frozendict.monkeypatch
import frozendict.cool

Basic Usage

from frozendict import frozendict

# Create a frozendict from a regular dict
data = frozendict({'name': 'Alice', 'age': 30, 'city': 'New York'})

# Access values like a regular dict
print(data['name'])  # Alice
print(data.get('age', 0))  # 30

# frozendict is immutable - these would raise AttributeError:
# data['name'] = 'Bob'  # AttributeError: 'frozendict' object is read-only
# del data['age']       # AttributeError: 'frozendict' object is read-only

# Create new frozendict instances with modifications
updated = data.set('age', 31)
print(updated['age'])  # 31
print(data['age'])     # 30 (original unchanged)

# Remove items
smaller = data.delete('city')
print('city' in smaller)  # False
print('city' in data)     # True (original unchanged)

# frozendict is hashable (if all values are hashable)
my_set = {data, updated}
print(len(my_set))  # 2

# Use as dictionary keys
cache = {data: "cached_result"}

Architecture

frozendict provides both pure Python and C extension implementations:

  • frozendict: The main immutable dictionary class with dict-compatible API
  • Deep Freezing: Recursive immutability with custom type converters
  • Monkeypatch System: Automatic integration with JSON serialization libraries
  • Performance: Optimized C extension when available, pure Python fallback

The library automatically registers frozendict with collections.abc.Mapping and applies JSON serialization patches on import.

Capabilities

Core Immutable Dictionary

The main frozendict class providing an immutable dictionary with dict-compatible API, hashing support, and methods for creating modified copies.

class frozendict(dict):
    def __init__(*args, **kwargs): ...
    def __hash__(self): ...
    def set(self, key, val): ...
    def delete(self, key): ...
    def setdefault(self, key, default=None): ...
    @classmethod
    def fromkeys(cls, *args, **kwargs): ...

Core Dictionary Operations

Deep Freezing

Recursive immutability system that converts objects and all nested objects to their immutable counterparts, with support for custom type converters.

def deepfreeze(o, custom_converters=None, custom_inverse_converters=None): ...
def register(to_convert, converter, *, inverse=False): ...
def unregister(type, inverse=False): ...
def getFreezeConversionMap(): ...
def getFreezeConversionInverseMap(): ...

Deep Freezing System

JSON Integration

Automatic JSON serialization support and monkeypatch utilities for seamless integration with JSON libraries.

class FrozendictJsonEncoder(JSONEncoder):
    def default(self, obj): ...

def patchOrUnpatchJson(*, patch, warn=True): ...
def patchOrUnpatchOrjson(*, patch, warn=True): ...
def patchOrUnpatchAll(*, patch, warn=True, raise_orjson=False): ...

JSON Integration

Module Information

Version and Implementation Detection

c_ext: bool  # True if C extension is used, False for pure Python
__version__: str  # Package version string

Exception Classes

class FreezeError(Exception): ...
class FreezeWarning(Warning): ...
class MonkeypatchWarning(Warning): ...

Deprecated

FrozenOrderedDict = frozendict  # Deprecated alias, to be removed in future versions