cfbpy

cfbpy is a Python package that allows you to compress and decompress compound file binary formats, similar to how zip/unzip works for regular zip files. It provides an easy-to-use interface for handling compound files through the CompoundFile class.

Features

• Compress a directory into a compound file format.
• Decompress a compound file back into a directory.

Installation

cfbpy is written in pure Python and has no dependencies. You can install cfbpy via pip:

pip install cfbpy

Or add it to a uv project:

uv add cfbpy

Usage

Here’s how you can use cfbpy to compress and decompress files:

Compress a Directory

from cfbpy import compress

compress('path/to/directory', 'path/to/output.cfb')

Decompress a Compound File

from cfbpy import decompress

decompress('path/to/input.cfb', 'path/to/extracted_directory')

The same functions are also available as CompoundFile.compress and CompoundFile.decompress.

Methods

• compress(src, dest=None): Compresses the contents of the src directory into a compound file at dest (default: <src>.cfb).
• decompress(src, dest=None): Decompresses the compound file from src to the directory dest (default: src without its extension).

Compound file names are limited by the format, so compress raises ValueError when a file or directory name

• is longer than 31 UTF-16 code units,
• contains any of / \ : !, or
• differs from a sibling only in letter case.

decompress raises CompoundFileError (a subclass of ValueError) if the input is not a valid compound file, and ValueError for entry names that would escape the destination directory, such as ...

Files are written as a major version 3 compound file (512-byte sectors). Both major version 3 and 4 (4096-byte sectors) files can be decompressed.

Development

The project is managed with uv.

uv sync                             # create .venv with the package and dev dependencies
uv run pytest                       # run tests
uv run python benchmarks/bench.py   # measure compress/decompress time and memory
uv build                            # build sdist and wheel into dist/

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Pull requests are welcome! For major changes, please open an issue first to discuss what you would like to change.