0
# Core Archive Operations
1

2
Primary archive manipulation functionality for reading, writing, extracting, and testing 7z archives. The SevenZipFile class provides the main interface with support for password protection, selective extraction, compression configuration, and various archive modes.
3

4
## Capabilities
5

6
### SevenZipFile Class
7

8
Main class for interacting with 7z archives, supporting both reading and writing operations with context manager protocol.
9

10
```python { .api }
11
class SevenZipFile:
12
    def __init__(self, file, mode="r", *, filters=None, dereference=False, 
13
                 password=None, header_encryption=False, blocksize=None, mp=False):
14
        """
15
        Open a 7z archive file.
16

17
        Parameters:
18
        - file: str or file-like object, path to archive or file object
19
        - mode: str, open mode ('r', 'w', 'x', 'a')
20
        - filters: list, compression filter configuration  
21
        - dereference: bool, follow symbolic links when archiving
22
        - password: str, password for encrypted archives
23
        - header_encryption: bool, encrypt archive headers
24
        - blocksize: int, compression block size
25
        - mp: bool, enable multiprocessing (experimental)
26
        """
27
```
28

29
**Supported Modes**:
30
- `'r'`: Read mode for extracting archives
31
- `'w'`: Write mode for creating new archives  
32
- `'x'`: Exclusive create mode (fails if file exists)
33
- `'a'`: Append mode for adding files to existing archives
34

35
### Reading and Extraction Operations
36

37
Extract files from 7z archives with support for selective extraction, password protection, and custom output paths.
38

39
```python { .api }
40
def extractall(self, path=None, *, callback=None, factory=None):
41
    """
42
    Extract all members from the archive.
43

44
    Parameters:
45
    - path: str, directory to extract to (default: current directory)
46
    - callback: ExtractCallback, progress reporting callback
47
    - factory: WriterFactory, custom I/O factory for extraction
48

49
    Returns:
50
    None
51
    """
52

53
def extract(self, path=None, targets=None, recursive=False, *, callback=None, factory=None):
54
    """
55
    Extract specific members from the archive.
56

57
    Parameters:
58
    - path: str, directory to extract to (default: current directory) 
59
    - targets: Collection[str], specific member names to extract
60
    - recursive: bool, recursively extract directory contents
61
    - callback: ExtractCallback, progress reporting callback
62
    - factory: WriterFactory, custom I/O factory for extraction
63

64
    Returns:
65
    None
66
    """
67

68
def getnames(self) -> list:
69
    """
70
    Get list of member names in the archive.
71

72
    Returns:
73
    List of member filenames as strings
74
    """
75

76
def namelist(self) -> list:
77
    """
78
    Alias for getnames().
79

80
    Returns:
81
    List of member filenames as strings  
82
    """
83

84
def getinfo(self, name) -> 'FileInfo':
85
    """
86
    Get FileInfo object for a specific member.
87

88
    Parameters:
89
    - name: str, member name
90

91
    Returns:
92
    FileInfo object with member metadata
93
    """
94

95
def list(self) -> list:
96
    """
97
    Get list of FileInfo objects for all members.
98

99
    Returns:
100
    List of FileInfo objects
101
    """
102
```
103

104
#### Usage Examples
105

106
```python
107
import py7zr
108

109
# Extract all files
110
with py7zr.SevenZipFile('archive.7z', 'r') as archive:
111
    archive.extractall('/tmp/output')
112

113
# Extract specific files
114
with py7zr.SevenZipFile('archive.7z', 'r') as archive:
115
    files = ['readme.txt', 'docs/manual.pdf']
116
    archive.extract(path='/tmp/output', targets=files)
117

118
# Extract with callback for progress
119
def progress_callback(archive_file):
120
    print(f"Extracting: {archive_file.filename}")
121

122
with py7zr.SevenZipFile('archive.7z', 'r') as archive:
123
    archive.extractall(callback=progress_callback)
124

125
# Get archive contents info
126
with py7zr.SevenZipFile('archive.7z', 'r') as archive:
127
    file_list = archive.getnames()
128
    for filename in file_list:
129
        info = archive.getinfo(filename)
130
        print(f"{filename}: {info.file_size} bytes")
131
```
132

133
### Writing and Compression Operations
134

135
Create 7z archives with files and directories, supporting compression configuration, encryption, and various output modes.
136

137
```python { .api }
138
def writeall(self, path, arcname=None):
139
    """
140
    Add entire directory tree to archive.
141

142
    Parameters:
143
    - path: str, directory path to add
144
    - arcname: str, archive name for directory (default: basename of path)
145

146
    Returns:
147
    None
148
    """
149

150
def write(self, file, arcname=None):
151
    """
152
    Add single file to archive.
153

154
    Parameters:
155
    - file: str, file path to add
156
    - arcname: str, name in archive (default: filename)
157

158
    Returns:
159
    None
160
    """
161

162
def writef(self, bio, arcname):
163
    """
164
    Write data from file-like object to archive.
165

166
    Parameters:
167
    - bio: file-like object, data source
168
    - arcname: str, name in archive
169

170
    Returns:
171
    None
172
    """
173

174
def writestr(self, data, arcname):
175
    """
176
    Write string or bytes data to archive.
177

178
    Parameters:
179
    - data: str or bytes, data to write
180
    - arcname: str, name in archive
181

182
    Returns:
183
    None
184
    """
185
```
186

187
#### Compression Configuration
188

189
```python
190
# Custom compression filters
191
lzma2_filters = [{"id": py7zr.FILTER_LZMA2, "preset": 9}]
192
zstd_filters = [{"id": py7zr.FILTER_ZSTD}]
193
multi_filters = [
194
    {"id": py7zr.FILTER_X86},
195
    {"id": py7zr.FILTER_LZMA2, "preset": 7}
196
]
197

198
# Create archive with custom compression
199
with py7zr.SevenZipFile('output.7z', 'w', filters=lzma2_filters) as archive:
200
    archive.writeall('/path/to/directory')
201
```
202

203
#### Usage Examples
204

205
```python
206
import py7zr
207

208
# Create archive from directory
209
with py7zr.SevenZipFile('backup.7z', 'w') as archive:
210
    archive.writeall('/home/user/documents', 'documents')
211

212
# Add individual files
213
with py7zr.SevenZipFile('files.7z', 'w') as archive:
214
    archive.write('/path/to/file1.txt', 'file1.txt')
215
    archive.write('/path/to/file2.txt', 'renamed_file2.txt')
216

217
# Create encrypted archive
218
with py7zr.SevenZipFile('secure.7z', 'w', password='my_password') as archive:
219
    archive.writeall('/sensitive/data')
220

221
# Write string data directly
222
with py7zr.SevenZipFile('data.7z', 'w') as archive:
223
    archive.writestr("Hello, World!", "greeting.txt")
224
    archive.writestr(b"\\x00\\x01\\x02", "binary_data.bin")
225
```
226

227
### Testing and Validation Operations
228

229
Verify archive integrity and test extraction without writing files to disk.
230

231
```python { .api }
232
def test(self):
233
    """
234
    Test archive integrity by attempting decompression.
235

236
    Returns:
237
    None (raises exception on failure)
238

239
    Raises:
240
    Bad7zFile: if archive is corrupted
241
    DecompressionError: if decompression fails
242
    PasswordRequired: if password needed
243
    """
244

245
def testzip(self) -> Optional[str]:
246
    """
247
    Test archive and return first bad file name.
248

249
    Returns:
250
    Optional[str]: name of first bad file, or None if all files are good
251
    """
252
```
253

254
#### Usage Examples
255

256
```python
257
import py7zr
258

259
# Test archive integrity
260
try:
261
    with py7zr.SevenZipFile('archive.7z', 'r') as archive:
262
        archive.test()
263
    print("Archive is valid")
264
except py7zr.Bad7zFile:
265
    print("Archive is corrupted")
266

267
# Test and get bad file info
268
with py7zr.SevenZipFile('archive.7z', 'r') as archive:
269
    bad_file = archive.testzip()
270
    if bad_file:
271
        print(f"Corrupted file: {bad_file}")
272
    else:
273
        print("All files are good")
274
```
275

276
### Archive Information and Properties
277

278
Access archive metadata and file information.
279

280
```python { .api }
281
def archiveinfo(self) -> 'ArchiveInfo':
282
    """
283
    Get archive metadata information.
284

285
    Returns:
286
    ArchiveInfo object with archive details
287
    """
288

289
def needs_password(self) -> bool:
290
    """
291
    Check if archive requires password.
292

293
    Returns:
294
    bool: True if password required
295
    """
296

297
@property
298
def files(self) -> 'ArchiveFileList':
299
    """
300
    Get list of files in archive.
301

302
    Returns:
303
    ArchiveFileList containing ArchiveFile objects
304
    """
305

306
@property
307
def password_protected(self) -> bool:
308
    """
309
    Check if archive is password protected.
310

311
    Returns:
312
    bool: True if encrypted
313
    """
314
```
315

316
### Configuration Methods
317

318
Configure archive behavior and encryption settings.
319

320
```python { .api }
321
def set_encoded_header_mode(self, mode: bool):
322
    """
323
    Enable or disable header encoding.
324

325
    Parameters:
326
    - mode: bool, True to enable header encoding
327
    """
328

329
def set_encrypted_header(self, mode: bool):
330
    """
331
    Enable or disable header encryption.
332

333
    Parameters:
334
    - mode: bool, True to encrypt headers
335
    """
336

337
def reset(self):
338
    """
339
    Reset archive to beginning for re-reading.
340
    
341
    Returns:
342
    None
343
    """
344
```
345

346
## Archive Metadata Classes
347

348
### ArchiveInfo
349

350
Container for archive-level metadata.
351

352
```python { .api }
353
class ArchiveInfo:
354
    @property
355
    def filename(self) -> str: ...
356
    @property  
357
    def size(self) -> int: ...
358
    @property
359
    def header_size(self) -> int: ...
360
    @property
361
    def method_names(self) -> list: ...
362
    @property
363
    def solid(self) -> bool: ...
364
    @property
365
    def blocks(self) -> int: ...
366
    @property
367
    def uncompressed(self) -> int: ...
368
```
369

370
### FileInfo
371

372
Container for individual file metadata.
373

374
```python { .api }
375
class FileInfo:
376
    @property
377
    def filename(self) -> str: ...
378
    @property
379
    def file_size(self) -> int: ...
380
    @property
381
    def compressed_size(self) -> int: ...
382
    @property
383
    def header_size(self) -> int: ...
384
    @property
385
    def crc(self) -> int: ...
386
    @property
387
    def is_dir(self) -> bool: ...
388
```
389

390
### ArchiveFile
391

392
Detailed file information within archives.
393

394
```python { .api }
395
class ArchiveFile:
396
    """
397
    Represent metadata for a single file in a 7z archive.
398
    
399
    Contains file properties including filename, permissions, timestamps,
400
    and type information (directory, symlink, etc.).
401
    """
402
    
403
    @property
404
    def filename(self) -> str:
405
        """Return filename of archive file."""
406
    
407
    @property
408
    def emptystream(self) -> bool:
409
        """True if file is empty (0-byte file), otherwise False."""
410
    
411
    def file_properties(self) -> dict[str, Any]:  
412
        """
413
        Return file properties as dictionary.
414
        
415
        Keys include: 'readonly', 'is_directory', 'posix_mode', 'archivable',
416
        'emptystream', 'filename', 'creationtime', 'lastaccesstime',
417
        'lastwritetime', 'attributes'
418
        
419
        Returns:
420
        dict: file properties and metadata
421
        """
422
    
423
    def is_directory(self) -> bool:
424
        """True if file is a directory, otherwise False."""
425
    
426
    def is_symlink(self) -> bool:
427
        """True if file is a symbolic link, otherwise False."""
428
    
429
    @property
430
    def is_junction(self) -> bool:
431
        """True if file is a junction/reparse point on Windows, otherwise False."""
432
    
433
    @property
434
    def is_socket(self) -> bool:
435
        """True if file is a socket, otherwise False."""
436
    
437
    @property
438
    def readonly(self) -> bool:
439
        """True if file is readonly, otherwise False."""
440
        
441
    @property
442
    def archivable(self) -> bool:
443
        """True if file has archive attribute set, otherwise False."""
444
    
445
    @property
446
    def compressed(self) -> Optional[int]:
447
        """Compressed size in bytes."""
448
        
449
    @property
450
    def uncompressed(self) -> list[int]:
451
        """List of uncompressed sizes."""
452
        
453
    @property
454
    def crc32(self) -> Optional[int]:
455
        """CRC32 checksum of archived file (optional)."""
456
        
457
    @property
458
    def lastwritetime(self) -> Optional[ArchiveTimestamp]:
459
        """Return last written timestamp of a file."""
460
        
461
    @property
462
    def posix_mode(self) -> Optional[int]:
463
        """POSIX file mode permissions."""
464
```
465

466
## Supporting Types
467

468
### ArchiveTimestamp
469

470
Windows FILETIME timestamp representation used in archive metadata.
471

472
```python { .api }
473
class ArchiveTimestamp(int):
474
    """
475
    Windows FILETIME timestamp.
476
    
477
    Represents timestamps as found in 7z archives using Windows FILETIME format.
478
    """
479
    
480
    def totimestamp(self) -> float:
481
        """
482
        Convert 7z FILETIME to Python timestamp.
483
        
484
        Returns:
485
        float: Unix timestamp
486
        """
487
```
488

489
### ArchiveFileList
490

491
Container for ArchiveFile objects with iteration support.
492

493
```python { .api }
494
class ArchiveFileList:
495
    """
496
    Iterable container of ArchiveFile objects.
497
    
498
    Provides indexed access and iteration over files in an archive.
499
    """
500
    
501
    def __init__(self, offset: int = 0): ...
502
    def __getitem__(self, index) -> ArchiveFile: ...
503
    def __iter__(self) -> ArchiveFileListIterator: ...
504
    def __len__(self) -> int: ...
505
```