0
# CRC32C
1

2
A Python package implementing the CRC32C checksum algorithm in hardware and software. It automatically chooses between hardware-accelerated implementations (using Intel SSE 4.2 CRC32C instructions on x86 CPUs, and crc32* instructions on ARMv8 CPUs) and optimized software fallbacks when hardware support is unavailable.
3

4
## Package Information
5

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

10
## Core Imports
11

12
```python
13
import crc32c
14
```
15

16
## Basic Usage
17

18
```python
19
import crc32c
20

21
# Basic checksum calculation
22
checksum = crc32c.crc32c(b'hello world')
23
print(checksum)  # 3381945770
24

25
# Incremental checksum calculation
26
crc = crc32c.crc32c(b'hello')
27
final_crc = crc32c.crc32c(b' world', value=crc)
28
print(final_crc)  # 3381945770
29

30
# Using hash object interface
31
hasher = crc32c.CRC32CHash()
32
hasher.update(b'hello')
33
hasher.update(b' world')
34
print(hasher.checksum)  # 3381945770
35
print(hasher.digest())   # b'\xc9\x94e\xaa'
36
print(hasher.hexdigest())  # c99465aa
37
```
38

39
## Capabilities
40

41
### CRC32C Function
42

43
Calculate CRC32C checksum incrementally with configurable GIL release behavior.
44

45
```python { .api }
46
def crc32c(data, value=0, gil_release_mode=-1):
47
    """
48
    Calculate CRC32C checksum incrementally.
49
    
50
    Parameters:
51
    - data: Buffer (bytes-like object) to checksum
52
    - value: int, initial checksum value (default: 0)
53
    - gil_release_mode: int, GIL release behavior:
54
        * Negative: Only release GIL when data >= 32KiB (default: -1)
55
        * 0: Never release the GIL
56
        * Positive: Always release the GIL
57
    
58
    Returns:
59
    int: The calculated CRC32C checksum
60
    """
61
```
62

63
### CRC32 Function (Deprecated)
64

65
Legacy function name for CRC32C calculation. Use `crc32c` instead as this will be removed in future versions.
66

67
```python { .api }
68
def crc32(data, value=0, gil_release_mode=-1):
69
    """
70
    Calculate CRC32C checksum incrementally (deprecated).
71
    
72
    Deprecated: Use crc32c instead. Will be removed in future versions.
73
    
74
    Parameters:
75
    - data: Buffer (bytes-like object) to checksum
76
    - value: int, initial checksum value (default: 0)  
77
    - gil_release_mode: int, GIL release behavior (same as crc32c)
78
    
79
    Returns:
80
    int: The calculated CRC32C checksum
81
    """
82
```
83

84
### Hash Object Interface
85

86
Object-oriented interface modeled after Python's hashlib for CRC32C computation.
87

88
```python { .api }
89
class CRC32CHash:
90
    """
91
    Hash object class for CRC32C computation following hashlib interface.
92
    """
93
    
94
    def __init__(self, data=b"", gil_release_mode=-1):
95
        """
96
        Initialize hash object with optional initial data.
97
        
98
        Parameters:
99
        - data: bytes-like object, initial data to hash (default: empty bytes)
100
        - gil_release_mode: int, GIL release behavior for checksum calculations (default: -1)
101
        """
102
    
103
    def update(self, data):
104
        """
105
        Update hash object with bytes-like object.
106
        
107
        Parameters:
108
        - data: bytes-like object to add to hash
109
        
110
        Returns:
111
        None
112
        """
113
    
114
    def digest(self):
115
        """
116
        Return digest as bytes object.
117
        
118
        Returns:
119
        bytes: 4-byte big-endian digest
120
        """
121
    
122
    def hexdigest(self):
123
        """
124
        Return digest as hexadecimal string.
125
        
126
        Returns:
127
        str: Hexadecimal representation of digest
128
        """
129
    
130
    def copy(self):
131
        """
132
        Return copy of hash object.
133
        
134
        Returns:
135
        CRC32CHash: Copy of current hash object state
136
        """
137
    
138
    @property
139
    def digest_size(self):
140
        """
141
        Size of resulting hash in bytes.
142
        
143
        Returns:
144
        int: Always 4 for CRC32C
145
        """
146
    
147
    @property
148
    def block_size(self):
149
        """
150
        Internal block size of hash algorithm in bytes.
151
        
152
        Returns:
153
        int: Always 1 for CRC32C
154
        """
155
    
156
    @property
157
    def name(self):
158
        """
159
        Canonical name of hash algorithm.
160
        
161
        Returns:
162
        str: Always "crc32c"
163
        """
164
    
165
    @property
166
    def checksum(self):
167
        """
168
        Current checksum value (non-standard hashlib extension).
169
        
170
        Returns:
171
        int: Current checksum as integer
172
        """
173
```
174

175
### Module Constants
176

177
Runtime information about implementation and platform characteristics.
178

179
```python { .api }
180
hardware_based: bool
181
"""
182
Indicates whether hardware-based implementation is in use.
183
True if using hardware acceleration, False if using software fallback.
184
"""
185

186
big_endian: int
187
"""
188
Indicates platform endianness.
189
1 if platform is big-endian, 0 if little-endian.
190
"""
191
```
192

193
### Benchmarking Utilities
194

195
Performance testing functionality available as a submodule.
196

197
```python { .api }
198
import crc32c.benchmark
199

200
def run(size, iterations):
201
    """
202
    Run benchmark with specified parameters.
203
    
204
    Parameters:
205
    - size: int, amount of bytes to checksum
206
    - iterations: int, number of iterations to run
207
    
208
    Returns:
209
    tuple[float, int]: (duration_seconds, total_evaluations)
210
    """
211

212
def main():
213
    """
214
    Command-line benchmark interface with argument parsing.
215
    
216
    Returns:
217
    None
218
    """
219
```
220

221
The benchmark module can be executed directly:
222
```bash
223
python -m crc32c.benchmark --size 104857600 --iterations 10
224
```
225

226
## Environment Variables
227

228
Package behavior can be controlled via environment variables:
229

230
### CRC32C_SW_MODE
231

232
Controls software implementation preference:
233
- `auto`: Use software fallback if no hardware support (default behavior, will be discontinued)
234
- `force`: Force software implementation regardless of hardware support  
235
- `none`: Raise RuntimeError if no hardware support found
236
- unset: Use software fallback if no hardware support
237

238
### CRC32C_SKIP_HW_PROBE
239

240
For testing purposes:
241
- `1`: Skip hardware capability detection
242
- unset: Normal hardware detection
243

244
## Types
245

246
```python { .api }
247
from typing import Union
248
from typing_extensions import Buffer
249

250
Buffer = Union[bytes, bytearray, memoryview, ...]
251
"""
252
Type alias for bytes-like objects that support the buffer protocol.
253
Includes bytes, bytearray, memoryview, and other objects implementing __buffer__.
254
"""
255
```
256

257
## Error Handling
258

259
```python { .api }
260
class RuntimeError(Exception):
261
    """
262
    Raised when no hardware support is available and CRC32C_SW_MODE is set to "none".
263
    """
264

265
class RuntimeWarning(Warning):
266
    """
267
    Warning issued when no hardware support is available and CRC32C_SW_MODE is set to "none".
268
    """
269

270
class DeprecationWarning(Warning):
271
    """
272
    Warning issued when using the deprecated crc32 function.
273
    """
274
```
275

276
## Platform Support
277

278
- **Hardware Acceleration**:
279
  - Intel x86/x64 with SSE 4.2 CRC32C instructions
280
  - ARMv8 with crc32* instructions
281
- **Software Fallback**: Intel slice-by-8 algorithm on all platforms
282
- **Threading**: Configurable GIL release modes for optimal multi-threading performance
283
- **Binary Wheels**: Available for major platforms/architectures via PyPI