zip-files

0.4.1 · active · verified Thu Apr 16

The `zip-files` Python library provides command-line utilities, `zip-files` and `zip-folder`, for creating ZIP archives. It offers an easy, platform-independent way to compress files and folders, allowing control over the internal root folder structure and compression method. The current version is 0.4.1, and its release cadence has been infrequent, with the last update in April 2021.

Common errors

```
command not found: zip-files
```
cause The `zip-files` command-line utility is not in your system's PATH, or the package was not installed correctly.

fix Ensure the package is installed in an environment whose `Scripts` directory is in your PATH. If using `pipx`, ensure the virtual environment is correctly linked. Reinstall using `pip install zip-files`.
```
zipfile.BadZipFile: File is not a zip file
```
cause Attempting to open a file that is either not a valid ZIP archive or is corrupted, possibly due to an incomplete download or incorrect file extension.

fix Verify the file's integrity and ensure it is a complete, valid ZIP archive. Try opening it with a standard unzipping tool. If using the Python API, check the path and permissions.
```
zipfile.BadZipFile: Unsupported compression method
```
cause The ZIP file was created using a compression method (e.g., Deflate64, old proprietary methods) that is not supported by Python's standard `zipfile` module (which `zip-files` relies upon) or the specific `compression` argument used.

fix Attempt to re-compress the archive using a widely supported method like 'deflated' (default for `zip-files`). If reading, use a tool that supports the specific compression method, or consider libraries like `zipfile-deflate64` or `zipfile-inflate64` if `DEFLATE64` is the issue.

Warnings

gotcha The `zip-files` package (hyphenated PyPI name) provides CLI utilities and a thin Python API, but it is distinct from Python's built-in `zipfile` module (underscore name). Many online resources refer to the standard `zipfile` module, which offers a more comprehensive API for ZIP archive manipulation.
Fix: Ensure you are importing from `zip_files.api` if you intend to use the programmatic interface of this specific library, or `import zipfile` for the standard library functionality.
gotcha ZIP files, especially large or corrupted ones, can be prone to extraction errors such as `BadZipFile` or `BadZipfile` (deprecated alias). This can be caused by incomplete downloads, header corruption, or unsupported compression methods if the archive was created by another tool.
Fix: Always validate the integrity of downloaded ZIP files. If encountering issues, try re-downloading the file or using an alternative extraction tool. For programmatic handling, wrap `zipfile.ZipFile` operations in `try-except BadZipFile` blocks. Ensure the correct compression method is specified when creating archives if compatibility is an issue.
gotcha When creating ZIP files, be mindful of the `root_folder` parameter. If not specified, files are added directly to the archive's root. If a `root_folder` is provided, all included files and folders will reside within that single top-level directory upon extraction. This influences how users interact with the extracted content.
Fix: Carefully consider the desired structure of the extracted ZIP. Use `-f` or `--root-folder` in the CLI, or the `root_folder` argument in `create_zip_file`, to control the top-level directory.

Install

pip install zip-files Install stable version

Imports

create_zip_file
wrong:
```
import zip_files
```
correct:
```
from zip_files.api import create_zip_file
```
The primary programmatic interface is `create_zip_file` within `zip_files.api`. The top-level `zip_files` import is for CLI execution.
ZipFile
wrong:
```
from zip_files.api import ZipFile
```
correct:
```
import zipfile
```
The `zip-files` library builds on Python's standard `zipfile` module. Direct usage of `ZipFile` for advanced operations should be from the standard library.

Quickstart

This quickstart demonstrates how to use the `create_zip_file` function from the programmatic API to generate a ZIP file. It includes creating two dummy files, zipping them into `my_archive.zip` under a specified root folder, and then cleaning up the generated files. The library also provides command-line tools `zip-files` and `zip-folder`.

import os
from zip_files.api import create_zip_file

# Create some dummy files for zipping
with open('file1.txt', 'w') as f:
    f.write('Content of file 1')
with open('file2.py', 'w') as f:
    f.write('print("Hello from file 2")')

output_zip = 'my_archive.zip'
files_to_zip = ['file1.txt', 'file2.py']
root_folder_in_zip = 'my_data'

print(f"Creating {output_zip} with files in root folder '{root_folder_in_zip}'...")
create_zip_file(output_zip, files_to_zip, root_folder=root_folder_in_zip)
print(f"Successfully created {output_zip}")

# You can also use the command-line utility
# import subprocess
# subprocess.run(['zip-files', '-f', 'another_data', 'another_archive.zip', 'file1.txt', 'file2.py'])

# Cleanup (optional)
os.remove('file1.txt')
os.remove('file2.py')
os.remove(output_zip)

view raw JSON →