Registry / data / handy-archives

handy-archives

JSON →
library0.2.0pypypi✓ verified 84d ago

handy-archives is a Python library providing a collection of convenient helpers for working with archive files, currently at version 0.2.0. It aims to simplify common archiving tasks, building upon functionalities available in Python's standard `zipfile`, `tarfile`, and `shutil` modules. Releases appear to follow an on-demand cadence as features or fixes are introduced.

pip install handy-archives
INSTALL
IMPORT
SIG · HANDY-ARCHIVES
H
handy-archives
datapythonv0.2.0
Install
1.7s avg
Import
41ms
Disk
16MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
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
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 0.043s · 17.8MB
glibc
py 3.103.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)
Debug
Known issues
gotchaThe `TarFile` and `ZipFile` classes in `handy_archives` are direct re-exports of the corresponding classes from Python's standard `tarfile` and `zipfile` modules. They do not add new functionality for archive creation beyond what the standard library offers.
fix
Refer to Python's official `zipfile` and `tarfile` documentation for comprehensive usage, including advanced features like compression levels, encryption, and handling large archives. Use `from handy_archives import ZipFile` or `TarFile` for convenience if preferred, but be aware it's effectively the standard library class.
affects: All versions
gotchaThe `unpack_archive` function wraps `shutil.unpack_archive`. While convenient, be aware of its default behavior to extract to the current working directory if `extract_dir` is not specified, and potential security implications of unpacking archives from untrusted sources.
fix
Always specify `extract_dir` to a dedicated, empty directory when unpacking archives to prevent unintended overwrites or file placement. Before unpacking archives from untrusted sources, inspect their contents using tools like `zipfile.ZipFile.namelist()` or `tarfile.TarFile.getnames()`.
affects: All versions
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`.
fix
Ensure 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.
fix
Verify 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.

Agent activity
6 hits · last 30 days
node
6
Resources
handy-archives — pip install handy-archives · libregistry