0
# frozendict
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: frozendict
7
- **Language**: Python
8
- **Installation**: `pip install frozendict`
9

10
## Core Imports
11

12
```python
13
from frozendict import frozendict
14
```
15

16
With additional features:
17

18
```python
19
from frozendict import frozendict, deepfreeze, FrozendictJsonEncoder
20
```
21

22
Full feature import:
23

24
```python
25
from frozendict import (
26
    frozendict, 
27
    deepfreeze, 
28
    register, 
29
    unregister,
30
    FrozendictJsonEncoder,
31
    c_ext,
32
    __version__
33
)
34
```
35

36
Submodule access:
37

38
```python
39
import frozendict.monkeypatch
40
import frozendict.cool
41
```
42

43
## Basic Usage
44

45
```python
46
from frozendict import frozendict
47

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

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

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

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

64
# Remove items
65
smaller = data.delete('city')
66
print('city' in smaller)  # False
67
print('city' in data)     # True (original unchanged)
68

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

73
# Use as dictionary keys
74
cache = {data: "cached_result"}
75
```
76

77
## Architecture
78

79
frozendict provides both pure Python and C extension implementations:
80

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

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

88
## Capabilities
89

90
### Core Immutable Dictionary
91

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

94
```python { .api }
95
class frozendict(dict):
96
    def __init__(*args, **kwargs): ...
97
    def __hash__(self): ...
98
    def set(self, key, val): ...
99
    def delete(self, key): ...
100
    def setdefault(self, key, default=None): ...
101
    @classmethod
102
    def fromkeys(cls, *args, **kwargs): ...
103
```
104

105
[Core Dictionary Operations](./core-dictionary.md)
106

107
### Deep Freezing
108

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

111
```python { .api }
112
def deepfreeze(o, custom_converters=None, custom_inverse_converters=None): ...
113
def register(to_convert, converter, *, inverse=False): ...
114
def unregister(type, inverse=False): ...
115
def getFreezeConversionMap(): ...
116
def getFreezeConversionInverseMap(): ...
117
```
118

119
[Deep Freezing System](./deep-freezing.md)
120

121
### JSON Integration
122

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

125
```python { .api }
126
class FrozendictJsonEncoder(JSONEncoder):
127
    def default(self, obj): ...
128

129
def patchOrUnpatchJson(*, patch, warn=True): ...
130
def patchOrUnpatchOrjson(*, patch, warn=True): ...
131
def patchOrUnpatchAll(*, patch, warn=True, raise_orjson=False): ...
132
```
133

134
[JSON Integration](./json-integration.md)
135

136
## Module Information
137

138
### Version and Implementation Detection
139

140
```python { .api }
141
c_ext: bool  # True if C extension is used, False for pure Python
142
__version__: str  # Package version string
143
```
144

145
### Exception Classes
146

147
```python { .api }
148
class FreezeError(Exception): ...
149
class FreezeWarning(Warning): ...
150
class MonkeypatchWarning(Warning): ...
151
```
152

153
### Deprecated
154

155
```python { .api }
156
FrozenOrderedDict = frozendict  # Deprecated alias, to be removed in future versions
157
```