0
# Block Format
1
2
Block format compression provides low-level access to LZ4 block compression without container format overhead. This interface offers direct control over compression parameters and supports advanced features like dictionaries.
3
4
## Capabilities
5
6
### Core Compression Functions
7
8
Direct block compression and decompression without frame format overhead.
9
10
```python { .api }
11
def compress(data, **kwargs) -> bytes:
12
"""
13
Compress data as LZ4 block without container format.
14
15
Args:
16
data (bytes-like): Data to compress
17
mode (str, optional): Compression mode ('default', 'fast', 'high_compression')
18
acceleration (int, optional): Acceleration factor for fast mode (default: 1)
19
compression_level (int, optional): Level for high_compression mode (1-12, default: 9)
20
store_size (bool, optional): Store uncompressed size in output (default: True)
21
return_bytearray (bool, optional): Return bytearray instead of bytes (default: False)
22
dict (bytes, optional): Compression dictionary for improved ratio
23
24
Returns:
25
bytes: Compressed block data
26
"""
27
28
def decompress(data, **kwargs) -> bytes:
29
"""
30
Decompress LZ4 block format data.
31
32
Args:
33
data (bytes-like): Compressed block data
34
uncompressed_size (int, optional): Maximum output size hint (required if store_size=False was used)
35
return_bytearray (bool, optional): Return bytearray instead of bytes (default: False)
36
dict (bytes, optional): Decompression dictionary matching compression dictionary
37
38
Returns:
39
bytes: Decompressed data
40
"""
41
```
42
43
### Exception Handling
44
45
Exception class for LZ4 block operations.
46
47
```python { .api }
48
class LZ4BlockError(Exception):
49
"""Exception raised when LZ4 library operations fail."""
50
```
51
52
## Compression Modes
53
54
### Default Mode
55
56
Standard compression balancing speed and compression ratio.
57
58
```python
59
import lz4.block
60
61
data = b"Hello, World!" * 1000
62
compressed = lz4.block.compress(data, mode='default')
63
decompressed = lz4.block.decompress(compressed)
64
```
65
66
### Fast Mode
67
68
Optimized for compression speed with configurable acceleration.
69
70
```python
71
import lz4.block
72
73
# Faster compression with acceleration
74
compressed = lz4.block.compress(
75
data,
76
mode='fast',
77
acceleration=4 # Higher values = faster but less compression
78
)
79
decompressed = lz4.block.decompress(compressed)
80
```
81
82
### High Compression Mode
83
84
Prioritizes compression ratio over speed with configurable levels.
85
86
```python
87
import lz4.block
88
89
# Maximum compression
90
compressed = lz4.block.compress(
91
data,
92
mode='high_compression',
93
compression_level=12 # 1-12, higher = better compression
94
)
95
decompressed = lz4.block.decompress(compressed)
96
```
97
98
## Advanced Features
99
100
### Dictionary Compression
101
102
Using dictionaries for improved compression of similar data.
103
104
```python
105
import lz4.block
106
107
# Train dictionary on representative data
108
dictionary = b"common prefix data that appears frequently"
109
110
# Compress with dictionary
111
data = b"common prefix data with unique suffix"
112
compressed = lz4.block.compress(data, dict=dictionary)
113
114
# Decompress with same dictionary
115
decompressed = lz4.block.decompress(compressed, dict=dictionary)
116
```
117
118
### Size Management
119
120
Control over size storage and output buffer management.
121
122
```python
123
import lz4.block
124
125
# Compress without storing size (requires manual size tracking)
126
compressed = lz4.block.compress(data, store_size=False)
127
128
# Decompress with explicit size (required when store_size=False)
129
decompressed = lz4.block.decompress(
130
compressed,
131
uncompressed_size=len(original_data)
132
)
133
134
# Use bytearray for reduced memory copying
135
compressed = lz4.block.compress(data, return_bytearray=True)
136
decompressed = lz4.block.decompress(compressed, return_bytearray=True)
137
```
138
139
## Usage Examples
140
141
### Basic Block Compression
142
143
```python
144
import lz4.block
145
146
# Simple compression
147
data = b"Hello, World!" * 1000
148
compressed = lz4.block.compress(data)
149
decompressed = lz4.block.decompress(compressed)
150
151
print(f"Original size: {len(data)}")
152
print(f"Compressed size: {len(compressed)}")
153
print(f"Compression ratio: {len(data) / len(compressed):.2f}")
154
```
155
156
### Performance Optimization
157
158
```python
159
import lz4.block
160
161
# Fast compression for real-time applications
162
def fast_compress(data):
163
return lz4.block.compress(
164
data,
165
mode='fast',
166
acceleration=8,
167
return_bytearray=True
168
)
169
170
# High compression for storage
171
def archive_compress(data, dictionary=None):
172
return lz4.block.compress(
173
data,
174
mode='high_compression',
175
compression_level=12,
176
dict=dictionary
177
)
178
```
179
180
### Error Handling
181
182
```python
183
import lz4.block
184
185
try:
186
# Attempt compression
187
compressed = lz4.block.compress(data)
188
decompressed = lz4.block.decompress(compressed)
189
190
except lz4.block.LZ4BlockError as e:
191
print(f"LZ4 operation failed: {e}")
192
# Handle compression/decompression failure
193
except Exception as e:
194
print(f"Unexpected error: {e}")
195
```
196
197
### Memory-Efficient Processing
198
199
```python
200
import lz4.block
201
202
def process_large_data(data_chunks):
203
"""Process large data in chunks to minimize memory usage."""
204
compressed_chunks = []
205
206
for chunk in data_chunks:
207
try:
208
# Use bytearray to reduce copying
209
compressed = lz4.block.compress(
210
chunk,
211
mode='fast',
212
return_bytearray=True
213
)
214
compressed_chunks.append(compressed)
215
216
except lz4.block.LZ4BlockError:
217
# Handle compression failure
218
compressed_chunks.append(chunk) # Store uncompressed
219
220
return compressed_chunks
221
```