0
# py7zr
1

2
A comprehensive pure Python implementation of the 7-zip archive format, supporting compression, decompression, encryption, and decryption operations without requiring external C/C++ dependencies. py7zr provides both a library interface and command-line tools for working with 7z archives, supporting multiple compression algorithms and encryption methods.
3

4
## Package Information
5

6
- **Package Name**: py7zr
7
- **Language**: Python  
8
- **Installation**: `pip install py7zr`
9
- **Minimum Python Version**: 3.9
10

11
## Core Imports
12

13
```python
14
import py7zr
15
```
16

17
Common imports for archive operations:
18

19
```python
20
from py7zr import SevenZipFile, is_7zfile, pack_7zarchive, unpack_7zarchive
21
```
22

23
Exception classes:
24

25
```python
26
from py7zr import Bad7zFile, PasswordRequired, DecompressionError, UnsupportedCompressionMethodError
27
```
28

29
Filter and compression constants:
30

31
```python
32
from py7zr import FILTER_LZMA2, FILTER_ZSTD, FILTER_CRYPTO_AES256_SHA256
33
```
34

35
## Basic Usage
36

37
### Extracting Archives
38

39
```python
40
import py7zr
41

42
# Extract entire archive
43
with py7zr.SevenZipFile('archive.7z', mode='r') as archive:
44
    archive.extractall(path='/tmp/extracted')
45

46
# Extract specific files
47
with py7zr.SevenZipFile('archive.7z', mode='r') as archive:
48
    archive.extract(['file1.txt', 'folder/file2.txt'], path='/tmp/extracted')
49

50
# Extract password-protected archive
51
with py7zr.SevenZipFile('encrypted.7z', mode='r', password='secret') as archive:
52
    archive.extractall()
53
```
54

55
### Creating Archives
56

57
```python
58
import py7zr
59

60
# Create archive from directory
61
with py7zr.SevenZipFile('new_archive.7z', mode='w') as archive:
62
    archive.writeall('/path/to/source_directory', 'archived_name')
63

64
# Create encrypted archive
65
with py7zr.SevenZipFile('encrypted.7z', mode='w', password='secret') as archive:
66
    archive.writeall('/path/to/source_directory')
67

68
# Create archive with custom compression
69
filters = [{"id": py7zr.FILTER_ZSTD}]
70
with py7zr.SevenZipFile('compressed.7z', mode='w', filters=filters) as archive:
71
    archive.writeall('/path/to/source_directory')
72
```
73

74
### Utility Functions
75

76
```python
77
import py7zr
78

79
# Check if file is valid 7z archive
80
if py7zr.is_7zfile('file.7z'):
81
    print("Valid 7z archive")
82

83
# Use with shutil interface
84
py7zr.pack_7zarchive('output', '/path/to/source')
85
py7zr.unpack_7zarchive('archive.7z', '/path/to/destination')
86
```
87

88
## Architecture
89

90
py7zr is built around several key components:
91

92
- **SevenZipFile**: Primary interface for reading and writing 7z archives with context manager support
93
- **Archive Information Classes**: Metadata containers (ArchiveInfo, FileInfo) for archive and file details
94
- **I/O Abstraction Layer**: Pluggable I/O system supporting memory, file, and custom backends
95
- **Callback System**: Progress reporting and event handling during operations
96
- **Filter Chain**: Configurable compression and encryption pipeline supporting LZMA, LZMA2, Bzip2, Deflate, ZStandard, Brotli, PPMd, and 7zAES encryption
97
- **CLI Tools**: Command-line interface for common archive operations
98

99
## Capabilities
100

101
### Core Archive Operations
102

103
Primary archive manipulation functionality including reading, writing, extracting, and testing 7z archives. Supports password protection, selective extraction, and various compression algorithms.
104

105
```python { .api }
106
class SevenZipFile:
107
    def __init__(self, file, mode="r", *, filters=None, dereference=False, 
108
                 password=None, header_encryption=False, blocksize=None, mp=False): ...
109
    def extractall(self, path=None, members=None, pwd=None, callback=None): ...
110
    def extract(self, member, path=None, pwd=None): ...
111
    def writeall(self, path, arcname=None): ...
112
    def write(self, file, arcname=None): ...
113
    def test(): ...
114
```
115

116
[Core Archive Operations](./core-operations.md)
117

118
### Command Line Interface
119

120
Command-line tools for working with 7z archives including create, extract, list, test, and info operations. Supports all major archive operations with password protection and multi-volume archives.
121

122
```python { .api }
123
def main(): ...  # CLI entry point
124
# Commands: c (create), x (extract), l (list), t (test), i (info)
125
```
126

127
[Command Line Interface](./cli.md)
128

129
### I/O System and Callbacks
130

131
Flexible I/O abstraction supporting file, memory, and custom backends with progress reporting through callback interfaces. Enables custom extraction destinations and progress monitoring.
132

133
```python { .api }
134
class Py7zIO:
135
    def write(self, s): ...
136
    def read(self, size=None): ...
137
    def seek(self, offset, whence=0): ...
138

139
class Callback:
140
    def report_start(self, processing_file_path, processing_bytes): ...
141
    def report_update(self, decompressed_bytes): ...
142
```
143

144
[I/O System and Callbacks](./io-callbacks.md)
145

146
### Exception Handling
147

148
Comprehensive error handling with specific exception types for different failure modes including invalid archives, compression errors, and missing passwords.
149

150
```python { .api }
151
class Bad7zFile(Exception): ...
152
class DecompressionError(Exception): ...
153
class PasswordRequired(Exception): ...
154
class UnsupportedCompressionMethodError(Exception): ...
155
```
156

157
[Exception Handling](./exceptions.md)
158

159
## Compression Algorithms and Filters
160

161
py7zr supports multiple compression algorithms and filters:
162

163
**Compression Methods**:
164
- LZMA2 (default), LZMA
165
- Bzip2, Deflate
166
- ZStandard, Brotli, PPMd
167
- Copy (no compression)
168

169
**Filters**:
170
- Delta filter
171
- BCJ filters (x86, ARM, SPARC, PowerPC, IA64, ARM Thumb)
172

173
**Encryption**:
174
- 7zAES with SHA256
175

176
## Constants and Presets
177

178
```python { .api }
179
# Filter constants
180
FILTER_LZMA2: int
181
FILTER_LZMA: int
182
FILTER_BZIP2: int
183
FILTER_DEFLATE: int
184
FILTER_ZSTD: int
185
FILTER_BROTLI: int
186
FILTER_PPMD: int
187
FILTER_CRYPTO_AES256_SHA256: int
188
FILTER_DELTA: int
189
FILTER_X86: int
190
FILTER_ARM: int
191

192
# Checksum constants
193
CHECK_SHA256: int
194
CHECK_CRC64: int
195
CHECK_CRC32: int
196
CHECK_NONE: int
197

198
# Compression presets
199
PRESET_DEFAULT: int
200
PRESET_EXTREME: int
201
```
202

203
## Utility Functions
204

205
```python { .api }
206
def is_7zfile(file) -> bool:
207
    """
208
    Check if file is a valid 7z archive.
209
    
210
    Parameters:
211
    - file: str or file-like object, path to file or file object to check
212
    
213
    Returns:
214
    bool: True if file is valid 7z archive
215
    """
216

217
def pack_7zarchive(base_name, base_dir, owner=None, group=None, 
218
                   dry_run=None, logger=None) -> str:
219
    """
220
    Create 7z archive for shutil integration.
221
    
222
    Parameters:
223
    - base_name: str, base name for archive (without .7z extension)
224
    - base_dir: str, directory to archive
225
    - owner: unused (for shutil compatibility)
226
    - group: unused (for shutil compatibility) 
227
    - dry_run: unused (for shutil compatibility)
228
    - logger: unused (for shutil compatibility)
229
    
230
    Returns:
231
    str: path to created archive file
232
    """
233

234
def unpack_7zarchive(archive, path, extra=None):
235
    """
236
    Extract 7z archive for shutil integration.
237
    
238
    Parameters:
239
    - archive: str, path to archive file
240
    - path: str, extraction destination directory
241
    - extra: unused (for shutil compatibility)
242
    
243
    Returns:
244
    None
245
    
246
    Raises:
247
    shutil.ReadError: if archive is not valid 7z file
248
    """
249
```