{"id":8212,"library":"handy-archives","title":"handy-archives","description":"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.","status":"active","version":"0.2.0","language":"en","source_language":"en","source_url":"https://github.com/domdfcoding/handy-archives","tags":["archive","zip","tar","compression","file management","shutil","standard library"],"install":[{"cmd":"pip install handy-archives","lang":"bash","label":"Install with pip"},{"cmd":"conda install -c conda-forge handy-archives","lang":"bash","label":"Install with conda"}],"dependencies":[],"imports":[{"symbol":"unpack_archive","correct":"from handy_archives import unpack_archive"},{"note":"While `handy_archives.TarFile` exists, it's a direct re-export of `tarfile.TarFile`. Prefer the `handy_archives` import for consistency with the library.","wrong":"import tarfile; tarfile.TarFile()","symbol":"TarFile","correct":"from handy_archives import TarFile"},{"note":"While `handy_archives.ZipFile` exists, it's a direct re-export of `zipfile.ZipFile`. Prefer the `handy_archives` import for consistency with the library.","wrong":"import zipfile; zipfile.ZipFile()","symbol":"ZipFile","correct":"from handy_archives import ZipFile"}],"quickstart":{"code":"import os\nfrom pathlib import Path\nfrom handy_archives import unpack_archive, TarFile, ZipFile\n\n# Setup: Create some dummy files and a directory\nPath('temp_files').mkdir(exist_ok=True)\nPath('temp_files/file1.txt').write_text('Hello from file 1')\nPath('temp_files/file2.log').write_text('Log entry 1\\nLog entry 2')\nPath('temp_files/subdir').mkdir(exist_ok=True)\nPath('temp_files/subdir/nested.csv').write_text('a,b,c\\n1,2,3')\n\narchive_name_zip = 'my_archive.zip'\narchive_name_tar_gz = 'my_archive.tar.gz'\n\n# 1. Create a Zip Archive using handy_archives.ZipFile (re-export of standard library)\nwith ZipFile(archive_name_zip, 'w') as zipf:\n    zipf.write('temp_files/file1.txt', 'file1.txt')\n    zipf.write('temp_files/file2.log', 'file2.log')\n    zipf.write('temp_files/subdir/nested.csv', 'subdir/nested.csv')\nprint(f\"Created ZIP archive: {archive_name_zip}\")\n\n# 2. Create a Tar.gz Archive using handy_archives.TarFile (re-export of standard library)\nwith TarFile(archive_name_tar_gz, 'w:gz') as tarf:\n    tarf.add('temp_files/file1.txt', arcname='file1.txt')\n    tarf.add('temp_files/file2.log', arcname='file2.log')\n    tarf.add('temp_files/subdir/nested.csv', arcname='subdir/nested.csv')\nprint(f\"Created TAR.GZ archive: {archive_name_tar_gz}\")\n\n# 3. Extract the Zip Archive using handy_archives.unpack_archive\noutput_dir_zip = 'extracted_zip'\nos.makedirs(output_dir_zip, exist_ok=True)\nunpack_archive(archive_name_zip, output_dir_zip)\nprint(f\"Extracted {archive_name_zip} to {output_dir_zip}\")\n\n# 4. Extract the Tar.gz Archive using handy_archives.unpack_archive\noutput_dir_tar = 'extracted_tar'\nos.makedirs(output_dir_tar, exist_ok=True)\nunpack_archive(archive_name_tar_gz, output_dir_tar)\nprint(f\"Extracted {archive_name_tar_gz} to {output_dir_tar}\")\n\n# Cleanup\nos.remove(archive_name_zip)\nos.remove(archive_name_tar_gz)\nos.remove('temp_files/file1.txt')\nos.remove('temp_files/file2.log')\nos.remove('temp_files/subdir/nested.csv')\nos.rmdir('temp_files/subdir')\nos.rmdir('temp_files')\nos.rmdir(output_dir_zip)\nos.rmdir(output_dir_tar)","lang":"python","description":"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."},"warnings":[{"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.","message":"The `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.","severity":"gotcha","affected_versions":"All versions"},{"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()`.","message":"The `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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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')`.","cause":"Attempting to unpack an archive with an unrecognized file extension or an unsupported internal format by `handy_archives.unpack_archive`.","error":"ValueError: Unknown archive format"},{"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()`.","cause":"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.","error":"FileNotFoundError: [Errno 2] No such file or directory: 'non_existent_file.txt'"}]}