Install & Compatibility
Where this runs
tested against v0.2.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.043s · 17.8MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.7s · import 0.039s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
unpack_archive
✓ from handy_archives import unpack_archive
TarFile
✓ from handy_archives import TarFile
✗ import tarfile; tarfile.TarFile()
While `handy_archives.TarFile` exists, it's a direct re-export of `tarfile.TarFile`. Prefer the `handy_archives` import for consistency with the library.
ZipFile
✓ from handy_archives import ZipFile
✗ import zipfile; zipfile.ZipFile()
While `handy_archives.ZipFile` exists, it's a direct re-export of `zipfile.ZipFile`. Prefer the `handy_archives` import for consistency with the library.
This quickstart demonstrates how to create both ZIP and Tar.gz archives and then extract them using `handy-archives`. It leverages the re-exported `ZipFile` and `TarFile` classes for creation, and the convenient `unpack_archive` function for extraction, handling different archive formats automatically. Dummy files and directories are created for demonstration and then cleaned up.
import os
from pathlib import Path
from handy_archives import unpack_archive, TarFile, ZipFile
# Setup: Create some dummy files and a directory
Path('temp_files').mkdir(exist_ok=True)
Path('temp_files/file1.txt').write_text('Hello from file 1')
Path('temp_files/file2.log').write_text('Log entry 1\nLog entry 2')
Path('temp_files/subdir').mkdir(exist_ok=True)
Path('temp_files/subdir/nested.csv').write_text('a,b,c\n1,2,3')
archive_name_zip = 'my_archive.zip'
archive_name_tar_gz = 'my_archive.tar.gz'
# 1. Create a Zip Archive using handy_archives.ZipFile (re-export of standard library)
with ZipFile(archive_name_zip, 'w') as zipf:
zipf.write('temp_files/file1.txt', 'file1.txt')
zipf.write('temp_files/file2.log', 'file2.log')
zipf.write('temp_files/subdir/nested.csv', 'subdir/nested.csv')
print(f"Created ZIP archive: {archive_name_zip}")
# 2. Create a Tar.gz Archive using handy_archives.TarFile (re-export of standard library)
with TarFile(archive_name_tar_gz, 'w:gz') as tarf:
tarf.add('temp_files/file1.txt', arcname='file1.txt')
tarf.add('temp_files/file2.log', arcname='file2.log')
tarf.add('temp_files/subdir/nested.csv', arcname='subdir/nested.csv')
print(f"Created TAR.GZ archive: {archive_name_tar_gz}")
# 3. Extract the Zip Archive using handy_archives.unpack_archive
output_dir_zip = 'extracted_zip'
os.makedirs(output_dir_zip, exist_ok=True)
unpack_archive(archive_name_zip, output_dir_zip)
print(f"Extracted {archive_name_zip} to {output_dir_zip}")
# 4. Extract the Tar.gz Archive using handy_archives.unpack_archive
output_dir_tar = 'extracted_tar'
os.makedirs(output_dir_tar, exist_ok=True)
unpack_archive(archive_name_tar_gz, output_dir_tar)
print(f"Extracted {archive_name_tar_gz} to {output_dir_tar}")
# Cleanup
os.remove(archive_name_zip)
os.remove(archive_name_tar_gz)
os.remove('temp_files/file1.txt')
os.remove('temp_files/file2.log')
os.remove('temp_files/subdir/nested.csv')
os.rmdir('temp_files/subdir')
os.rmdir('temp_files')
os.rmdir(output_dir_zip)
os.rmdir(output_dir_tar)
Errors
Common errors & fixes
ValueError: Unknown archive format
Attempting to unpack an archive with an unrecognized file extension or an unsupported internal format by `handy_archives.unpack_archive`.
fixEnsure the archive file has a standard extension (e.g., .zip, .tar, .tar.gz, .tar.bz2, .tar.xz) that `shutil.unpack_archive` (which `handy-archives` uses) can recognize. If it's a custom or less common format, manual handling with specialized libraries may be required. You can also explicitly pass the `format` argument to `unpack_archive` if known, e.g., `unpack_archive('archive.xyz', 'output_dir', format='zip')`. FileNotFoundError: [Errno 2] No such file or directory: 'non_existent_file.txt'
Trying to create an archive by adding a file that does not exist at the specified path, or trying to unpack a non-existent archive.
fixVerify that all source files and directories intended for archiving exist before calling `zipf.write()` or `tarf.add()`. Similarly, ensure the archive file itself exists before attempting to unpack it with `unpack_archive()`.
Upgrade
Version history
0.2.0latest on PyPI · released Jul 31, 2023
Audit
Dependencies
No dependency data recorded yet.