0
# LZ4
1
2
LZ4 Bindings for Python providing high-performance lossless data compression with both frame format and block format specifications. This library delivers a drop-in alternative to Python's standard library compression modules (zlib, gzip, bzip2, LZMA) with a compatible API that includes context managers and file handler support.
3
4
## Package Information
5
6
- **Package Name**: lz4
7
- **Language**: Python
8
- **Installation**: `pip install lz4`
9
10
## Core Imports
11
12
```python
13
import lz4
14
```
15
16
For frame format compression (recommended):
17
18
```python
19
import lz4.frame
20
```
21
22
For block format compression (low-level):
23
24
```python
25
import lz4.block
26
```
27
28
For experimental stream format:
29
30
```python
31
import lz4.stream
32
```
33
34
## Basic Usage
35
36
```python
37
import lz4.frame
38
39
# Simple compression and decompression
40
data = b"Hello, World!" * 1000
41
compressed = lz4.frame.compress(data)
42
decompressed = lz4.frame.decompress(compressed)
43
44
# File handling with context manager
45
with lz4.frame.open('data.lz4', 'wb') as f:
46
f.write(b"Large amounts of data...")
47
48
with lz4.frame.open('data.lz4', 'rb') as f:
49
content = f.read()
50
```
51
52
## Architecture
53
54
The lz4 package provides three compression approaches:
55
56
- **Frame Format**: Production-ready container format with metadata, checksums, and interoperability guarantees
57
- **Block Format**: Low-level compression of individual data blocks without container overhead
58
- **Stream Format**: Experimental streaming compression with double-buffer strategy (unmaintained)
59
60
All operations are thread-safe with GIL-releasing implementations optimized for performance. The library follows Python's standard compression module patterns for compatibility.
61
62
## Capabilities
63
64
### Version Information
65
66
Access to package and library version information.
67
68
```python { .api }
69
lz4.__version__: str
70
lz4.VERSION: str
71
def lz4.library_version_number() -> int: ...
72
def lz4.library_version_string() -> str: ...
73
```
74
75
### Frame Format Compression
76
77
Production-ready compression using the LZ4 frame format with full interoperability, metadata support, and extensive configuration options. This is the recommended interface for most use cases.
78
79
```python { .api }
80
def lz4.frame.compress(data, **kwargs) -> bytes: ...
81
def lz4.frame.decompress(data, **kwargs) -> bytes: ...
82
def lz4.frame.open(filename, mode, **kwargs) -> LZ4FrameFile: ...
83
84
class lz4.frame.LZ4FrameCompressor: ...
85
class lz4.frame.LZ4FrameDecompressor: ...
86
class lz4.frame.LZ4FrameFile: ...
87
```
88
89
[Frame Format](./frame-format.md)
90
91
### Block Format Compression
92
93
Low-level block compression without container format overhead. Provides direct access to LZ4 block compression with support for dictionaries and flexible compression modes.
94
95
```python { .api }
96
def lz4.block.compress(data, **kwargs) -> bytes: ...
97
def lz4.block.decompress(data, **kwargs) -> bytes: ...
98
99
class lz4.block.LZ4BlockError(Exception): ...
100
```
101
102
[Block Format](./block-format.md)
103
104
### Stream Format Compression
105
106
Experimental streaming compression interface with double-buffer strategy. Warning: This module is unmaintained and not included in distributed wheels.
107
108
```python { .api }
109
class lz4.stream.LZ4StreamCompressor: ...
110
class lz4.stream.LZ4StreamDecompressor: ...
111
112
class lz4.stream.LZ4StreamError(Exception): ...
113
```
114
115
[Stream Format](./stream-format.md)