0
# Standard Compression
1

2
Standard compression algorithms with consistent API patterns. All modules support compression levels and provide both functional and streaming interfaces.
3

4
## Imports
5

6
```python { .api }
7
from cramjam import gzip, zlib, deflate, bzip2, zstd, brotli
8
```
9

10
## Common API Pattern
11

12
All standard compression modules follow the same interface:
13

14
```python { .api }
15
# Basic compression/decompression
16
def compress(data: BufferProtocol, level: Optional[int] = None, output_len: Optional[int] = None) -> Buffer
17
def decompress(data: BufferProtocol, output_len: Optional[int] = None) -> Buffer
18

19
# Direct buffer operations  
20
def compress_into(input: BufferProtocol, output: BufferProtocol, level: Optional[int] = None) -> int
21
def decompress_into(input: BufferProtocol, output: BufferProtocol) -> int
22

23
# Streaming classes
24
class Compressor:
25
    def __init__(self, level: Optional[int] = None) -> None
26
    def compress(self, input: bytes) -> int
27
    def flush(self) -> Buffer
28
    def finish(self) -> Buffer
29

30
class Decompressor:
31
    def decompress(self, data: bytes) -> Buffer
32
```
33

34
## Gzip Module
35

36
Standard gzip compression with default level 6.
37

38
### Basic Operations
39

40
```python { .api }
41
import cramjam
42

43
def compress(data: BufferProtocol, level: Optional[int] = None, output_len: Optional[int] = None) -> Buffer:
44
    """Gzip compression.
45
    
46
    Args:
47
        data: Input data to compress
48
        level: Compression level (default: 6)  
49
        output_len: Optional expected output length
50
        
51
    Returns:
52
        Buffer: Compressed data
53
    """
54

55
def decompress(data: BufferProtocol, output_len: Optional[int] = None) -> Buffer:
56
    """Gzip decompression.
57
    
58
    Args:
59
        data: Compressed data to decompress
60
        output_len: Optional expected output length
61
        
62
    Returns:
63
        Buffer: Decompressed data  
64
    """
65
```
66

67
### Direct Buffer Operations
68

69
```python { .api }
70
def compress_into(input: BufferProtocol, output: BufferProtocol, level: Optional[int] = None) -> int:
71
    """Compress directly into output buffer.
72
    
73
    Args:
74
        input: Data to compress
75
        output: Pre-allocated output buffer
76
        level: Compression level (optional)
77
        
78
    Returns:
79
        int: Number of bytes written
80
    """
81

82
def decompress_into(input: BufferProtocol, output: BufferProtocol) -> int:
83
    """Decompress directly into output buffer.
84
    
85
    Args:
86
        input: Compressed data
87
        output: Pre-allocated output buffer
88
        
89
    Returns:
90
        int: Number of bytes written
91
    """
92
```
93

94
### Streaming Classes
95

96
```python { .api }
97
class Compressor:
98
    """Gzip streaming compressor."""
99
    
100
    def __init__(self, level: Optional[int] = None) -> None:
101
        """Initialize compressor with optional level."""
102
    
103
    def compress(self, input: bytes) -> int:
104
        """Add data to compression stream."""
105
        
106
    def flush(self) -> Buffer:
107
        """Flush and return current compressed stream."""
108
        
109
    def finish(self) -> Buffer:
110
        """Finish compression and return final stream."""
111

112
class Decompressor:
113
    """Gzip streaming decompressor."""
114
    
115
    def decompress(self, data: bytes) -> Buffer:
116
        """Decompress data chunk."""
117
```
118

119
### Usage Examples
120

121
```python { .api }
122
import cramjam
123

124
# Basic compression with custom level
125
data = b"Hello World!" * 1000
126
compressed = cramjam.gzip.compress(data, level=9)  # Maximum compression
127
decompressed = cramjam.gzip.decompress(compressed)
128

129
# Memory-efficient compression
130
output_buffer = cramjam.Buffer()
131
bytes_written = cramjam.gzip.compress_into(data, output_buffer, level=1)  # Fast compression
132

133
# Streaming compression for large data
134
compressor = cramjam.gzip.Compressor(level=6)
135
compressor.compress(b"First chunk")
136
compressor.compress(b"Second chunk") 
137
final_data = compressor.finish()
138
```
139

140
## Zlib Module  
141

142
Zlib compression with default level 6.
143

144
### API Functions
145

146
```python { .api }
147
def compress(data: BufferProtocol, level: Optional[int] = None, output_len: Optional[int] = None) -> Buffer:
148
    """Zlib compression."""
149

150
def decompress(data: BufferProtocol, output_len: Optional[int] = None) -> Buffer:
151
    """Zlib decompression."""
152

153
def compress_into(input: BufferProtocol, output: BufferProtocol, level: Optional[int] = None) -> int:
154
    """Compress directly into output buffer."""
155

156
def decompress_into(input: BufferProtocol, output: BufferProtocol) -> int:
157
    """Decompress directly into output buffer."""
158

159
class Compressor:
160
    def __init__(self, level: Optional[int] = None) -> None: ...
161

162
class Decompressor: ...
163
```
164

165
### Usage Example
166

167
```python { .api }
168
import cramjam
169

170
# Zlib is similar to gzip but without file headers
171
data = b"Zlib compression data"
172
compressed = cramjam.zlib.compress(data, level=5)
173
decompressed = cramjam.zlib.decompress(compressed)
174
```
175

176
## Deflate Module
177

178
Raw deflate compression with default level 6.
179

180
### API Functions
181

182
```python { .api }
183
def compress(data: BufferProtocol, level: Optional[int] = None, output_len: Optional[int] = None) -> Buffer:
184
    """Deflate compression."""
185

186
def decompress(data: BufferProtocol, output_len: Optional[int] = None) -> Buffer:
187
    """Deflate decompression."""
188

189
def compress_into(input: BufferProtocol, output: BufferProtocol, level: Optional[int] = None) -> int:
190
    """Compress directly into output buffer."""
191

192
def decompress_into(input: BufferProtocol, output: BufferProtocol) -> int:
193
    """Decompress directly into output buffer."""
194
```
195

196
### Enhanced Streaming Classes
197

198
```python { .api }
199
class Compressor:
200
    """Deflate compressor with enhanced streaming support."""
201
    
202
    def __init__(self, level: Optional[int] = None) -> None: ...
203
    
204
    def compress(self, input: BufferProtocol) -> int:
205
        """Compress input and return bytes written to stream."""
206
        
207
    def flush(self) -> Buffer:
208
        """Flush and return current compressed stream."""
209
        
210
    def finish(self) -> Buffer:
211
        """Finish compression and return final stream."""
212

213
class Decompressor:
214
    """Deflate decompressor with streaming support."""
215
    
216
    def decompress(self, input: BufferProtocol) -> Buffer:
217
        """Decompress data chunk."""
218
        
219
    def flush(self) -> Buffer:
220
        """Flush decompressor state."""
221
        
222
    def finish(self) -> Buffer:
223
        """Finish decompression."""
224
```
225

226
### Usage Example
227

228
```python { .api }
229
import cramjam
230

231
# Raw deflate - no headers or checksums
232
data = b"Raw deflate data"
233
compressed = cramjam.deflate.compress(data)
234
decompressed = cramjam.deflate.decompress(compressed)
235

236
# Streaming with enhanced control
237
compressor = cramjam.deflate.Compressor(level=3)
238
compressor.compress(b"Chunk 1")
239
intermediate = compressor.flush()  # Get partial result
240
compressor.compress(b"Chunk 2")
241
final = compressor.finish()
242
```
243

244
## Bzip2 Module
245

246
Bzip2 compression with default level 6.
247

248
### API Functions
249

250
```python { .api }
251
def compress(data: BufferProtocol, level: Optional[int] = None, output_len: Optional[int] = None) -> Buffer:
252
    """Bzip2 compression."""
253

254
def decompress(data: BufferProtocol, output_len: Optional[int] = None) -> Buffer:
255
    """Bzip2 decompression."""
256

257
def compress_into(input: BufferProtocol, output: BufferProtocol, level: Optional[int] = None) -> int:
258
    """Compress directly into output buffer."""
259

260
def decompress_into(input: BufferProtocol, output: BufferProtocol) -> int:
261
    """Decompress directly into output buffer."""
262

263
class Compressor:
264
    def __init__(self, level: Optional[int] = None) -> None: ...
265

266
class Decompressor: ...
267
```
268

269
### Usage Example
270

271
```python { .api }
272
import cramjam
273

274
# Bzip2 provides good compression ratio
275
data = b"Bzip2 test data" * 100
276
compressed = cramjam.bzip2.compress(data, level=9)  # Best compression
277
decompressed = cramjam.bzip2.decompress(compressed)
278
```
279

280
## ZSTD Module  
281

282
Modern Zstandard compression with default level 6.
283

284
### API Functions
285

286
```python { .api }
287
def compress(data: BufferProtocol, level: Optional[int] = None, output_len: Optional[int] = None) -> Buffer:
288
    """Zstd compression."""
289

290
def decompress(data: BufferProtocol, output_len: Optional[int] = None) -> Buffer:
291
    """Zstd decompression."""
292

293
def compress_into(input: BufferProtocol, output: BufferProtocol, level: Optional[int] = None) -> int:
294
    """Compress directly into output buffer."""
295

296
def decompress_into(input: BufferProtocol, output: BufferProtocol) -> int:
297
    """Decompress directly into output buffer."""
298

299
class Compressor:
300
    def __init__(self, level: Optional[int] = None) -> None: ...
301

302
class Decompressor: ...
303
```
304

305
### Usage Example
306

307
```python { .api }
308
import cramjam
309

310
# ZSTD offers excellent speed/compression balance
311
data = b"Modern compression with ZSTD" * 500
312
compressed = cramjam.zstd.compress(data, level=3)  # Fast, good compression
313
decompressed = cramjam.zstd.decompress(compressed)
314

315
# Streaming for large datasets  
316
compressor = cramjam.zstd.Compressor(level=10)  # Slower but better compression
317
for chunk in large_data_chunks:
318
    compressor.compress(chunk)
319
result = compressor.finish()
320
```
321

322
## Brotli Module
323

324
Web-optimized Brotli compression with default level 11.
325

326
### API Functions
327

328
```python { .api }
329
def compress(data: BufferProtocol, level: Optional[int] = None, output_len: Optional[int] = None) -> Buffer:
330
    """Brotli compression.
331
    
332
    Args:
333
        data: Input data to compress
334
        level: Compression level (default: 11)
335
        output_len: Optional expected output length
336
    """
337

338
def decompress(data: BufferProtocol, output_len: Optional[int] = None) -> Buffer:
339
    """Brotli decompression."""
340

341
def compress_into(input: BufferProtocol, output: BufferProtocol, level: Optional[int] = None) -> int:
342
    """Compress directly into output buffer."""
343

344
def decompress_into(input: BufferProtocol, output: BufferProtocol) -> int:
345
    """Decompress directly into output buffer."""
346
```
347

348
### Enhanced Streaming Classes
349

350
```python { .api }
351
class Compressor:
352
    """Brotli compressor with streaming support."""
353
    
354
    def __init__(self, level: Optional[int] = None) -> None: ...
355
    
356
    def compress(self, input: BufferProtocol) -> int:
357
        """Compress input and return bytes written to stream."""
358
        
359
    def flush(self) -> Buffer:
360
        """Flush and return current compressed stream."""
361
        
362
    def finish(self) -> Buffer:
363
        """Finish compression and return final stream."""
364

365
class Decompressor:
366
    """Brotli decompressor with streaming support."""
367
    
368
    def decompress(self, input: BufferProtocol) -> Buffer:
369
        """Decompress data chunk."""
370
        
371
    def flush(self) -> Buffer:
372
        """Flush decompressor state."""
373
        
374
    def finish(self) -> Buffer:
375
        """Finish decompression."""
376
```
377

378
### Usage Example
379

380
```python { .api }
381
import cramjam
382

383
# Brotli is optimized for web content
384
web_content = b"<html><body>Web page content</body></html>" * 100
385
compressed = cramjam.brotli.compress(web_content, level=6)  # Balanced speed/size
386
decompressed = cramjam.brotli.decompress(compressed)
387

388
# Streaming for web responses
389
compressor = cramjam.brotli.Compressor(level=4)  # Fast for real-time
390
compressor.compress(b"HTTP response chunk 1")
391
partial = compressor.flush()
392
compressor.compress(b"HTTP response chunk 2")  
393
final = compressor.finish()
394
```
395

396
## Compression Level Guidelines
397

398
### Level Recommendations by Algorithm
399

400
- **Gzip/Zlib/Deflate**: 1 (fast) to 9 (best), default 6
401
- **Bzip2**: 1 (fast) to 9 (best), default 6  
402
- **ZSTD**: 1 (fast) to 22 (best), default 6
403
- **Brotli**: 0 (fast) to 11 (best), default 11
404

405
### Performance vs Compression Trade-offs
406

407
```python { .api }
408
import cramjam
409
import time
410

411
data = b"Performance test data" * 10000
412

413
# Fast compression (level 1)
414
start = time.time()
415
fast_compressed = cramjam.zstd.compress(data, level=1)
416
fast_time = time.time() - start
417

418
# Balanced compression (level 6) 
419
start = time.time()
420
balanced_compressed = cramjam.zstd.compress(data, level=6)
421
balanced_time = time.time() - start
422

423
# Best compression (level 15)
424
start = time.time() 
425
best_compressed = cramjam.zstd.compress(data, level=15)
426
best_time = time.time() - start
427

428
print(f"Fast: {len(fast_compressed)} bytes in {fast_time:.3f}s")
429
print(f"Balanced: {len(balanced_compressed)} bytes in {balanced_time:.3f}s") 
430
print(f"Best: {len(best_compressed)} bytes in {best_time:.3f}s")
431
```
432

433
## Algorithm Selection Guide
434

435
### When to Use Each Algorithm
436

437
- **Gzip**: Standard web/file compression, broad compatibility
438
- **Zlib**: Library data compression, checksums important  
439
- **Deflate**: Raw compression without headers/checksums
440
- **Bzip2**: High compression ratio, CPU time available
441
- **ZSTD**: Modern balance of speed/compression, large datasets
442
- **Brotli**: Web content, text compression, HTTP responses
443

444
### Compatibility Considerations
445

446
```python { .api }
447
import cramjam
448

449
# For maximum compatibility
450
standard_data = cramjam.gzip.compress(data)  # Widely supported
451

452
# For modern applications
453
efficient_data = cramjam.zstd.compress(data)  # Best performance
454

455
# For web applications  
456
web_data = cramjam.brotli.compress(data)  # Optimized for HTTP
457

458
# For archival storage
459
archive_data = cramjam.bzip2.compress(data, level=9)  # Maximum compression
460
```