0
# Simple Compression Operations
1

2
Basic compression and decompression functions for quick one-shot operations and file handling, providing a simple interface for common compression tasks without requiring detailed knowledge of compression parameters.
3

4
## Capabilities
5

6
### One-Shot Compression
7

8
Compresses data in a single operation using default or specified compression level.
9

10
```python { .api }
11
def compress(data: bytes, level: int = 3) -> bytes:
12
    """
13
    Compress source data using the zstd compression format.
14

15
    This performs one-shot compression using basic/default compression
16
    settings.
17

18
    Parameters:
19
    - data: bytes-like object containing data to compress
20
    - level: int, compression level (1-22, default 3)
21

22
    Returns:
23
    bytes: Compressed data
24
    """
25
```
26

27
**Usage Example:**
28

29
```python
30
import zstandard as zstd
31

32
original = b"Hello, World! This is some data to compress."
33
compressed = zstd.compress(original, level=5)
34
print(f"Original: {len(original)} bytes, Compressed: {len(compressed)} bytes")
35
```
36

37
### One-Shot Decompression
38

39
Decompresses zstd-compressed data in a single operation.
40

41
```python { .api }
42
def decompress(data: bytes, max_output_size: int = 0) -> bytes:
43
    """
44
    Decompress a zstd frame into its original data.
45

46
    This performs one-shot decompression using basic/default compression
47
    settings.
48

49
    Parameters:
50
    - data: bytes-like object containing compressed data
51
    - max_output_size: int, maximum expected output size (0 for no limit)
52

53
    Returns:
54
    bytes: Decompressed data
55
    """
56
```
57

58
**Usage Example:**
59

60
```python
61
import zstandard as zstd
62

63
# Assuming 'compressed' contains zstd-compressed data
64
decompressed = zstd.decompress(compressed)
65
print(f"Decompressed: {decompressed}")
66

67
# With size limit for safety
68
decompressed = zstd.decompress(compressed, max_output_size=1024*1024)  # 1MB limit
69
```
70

71
### File-Like Interface
72

73
Opens files with automatic zstd compression/decompression, supporting both binary and text modes.
74

75
```python { .api }
76
def open(
77
    filename: Union[bytes, str, os.PathLike, BinaryIO],
78
    mode: str = "rb",
79
    cctx: Optional[ZstdCompressor] = None,
80
    dctx: Optional[ZstdDecompressor] = None,
81
    encoding: Optional[str] = None,
82
    errors: Optional[str] = None,
83
    newline: Optional[str] = None,
84
    closefd: bool = True
85
):
86
    """
87
    Create a file object with zstd (de)compression.
88

89
    The object returned from this function will be a
90
    ZstdDecompressionReader if opened for reading in binary mode,
91
    a ZstdCompressionWriter if opened for writing in binary mode,
92
    or an io.TextIOWrapper if opened for reading or writing in text mode.
93

94
    Parameters:
95
    - filename: Union[bytes, str, os.PathLike, BinaryIO], file path or file-like object
96
    - mode: str, file open mode ('rb', 'wb', 'rt', 'wt', etc.)
97
    - cctx: Optional[ZstdCompressor], compressor instance for compression
98
    - dctx: Optional[ZstdDecompressor], decompressor instance for decompression
99
    - encoding: Optional[str], text encoding for text mode
100
    - errors: Optional[str], error handling mode for text mode
101
    - newline: Optional[str], newline handling for text mode
102
    - closefd: bool, whether to close file descriptor when done (default: True)
103

104
    Returns:
105
    File-like object with compression/decompression
106
    """
107
```
108

109
**Usage Examples:**
110

111
```python
112
import zstandard as zstd
113

114
# Write compressed data to file
115
with zstd.open('data.zst', 'wb') as f:
116
    f.write(b"This data will be compressed automatically")
117
    f.write(b"Multiple writes are supported")
118

119
# Read compressed data from file  
120
with zstd.open('data.zst', 'rb') as f:
121
    data = f.read()
122
    print(f"Read: {data}")
123

124
# Text mode with encoding
125
with zstd.open('text.zst', 'wt', encoding='utf-8') as f:
126
    f.write("This is text that will be compressed")
127
    f.write("Unicode characters: 🚀 ñ ü")
128

129
with zstd.open('text.zst', 'rt', encoding='utf-8') as f:
130
    text = f.read()
131
    print(f"Text: {text}")
132

133
# Using custom compressor/decompressor
134
compressor = zstd.ZstdCompressor(level=10)
135
with zstd.open('high-compression.zst', 'wb', cctx=compressor) as f:
136
    f.write(b"This will be compressed at level 10")
137
```
138

139
### File Mode Support
140

141
The `open()` function supports various file modes:
142

143
- **Binary modes**: `'rb'`, `'wb'`, `'ab'`, `'xb'`
144
- **Text modes**: `'rt'`, `'wt'`, `'at'`, `'xt'`
145
- **Mode modifiers**: Standard Python file mode modifiers are supported
146

147
## Performance Notes
148

149
- One-shot functions create new compressor/decompressor contexts for each call
150
- For multiple operations, use `ZstdCompressor` and `ZstdDecompressor` objects for better performance
151
- The file interface handles buffering automatically for optimal performance
152
- Text mode adds encoding/decoding overhead compared to binary mode