handy-archives

Common errors

• ValueError: Unknown archive format

  cause 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'

  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.
  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()`.

Warnings

• gotcha 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.
  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.
• gotcha 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.
  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()`.

Install

• pip install handy-archives Install with pip
• conda install -c conda-forge handy-archives Install with conda

Imports

• unpack_archive

  from handy_archives import unpack_archive

• TarFile
  wrong:

  import tarfile; tarfile.TarFile()

  correct:

  from handy_archives import 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
  wrong:

  import zipfile; zipfile.ZipFile()

  correct:

  from handy_archives import 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.

Quickstart

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)