Metadata-Version: 2.4
Name: cfbpy
Version: 1.0.0
Summary: Python module for compressing/decompressing compound file binary format (CFB)
Author: killerwhalee
Author-email: killerwhalee <killerwhalee@kaist.ac.kr>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Requires-Python: >=3.12
Project-URL: Homepage, https://github.com/killerwhalee/cfbpy
Project-URL: Issues, https://github.com/killerwhalee/cfbpy/issues
Description-Content-Type: text/markdown

# 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:

```bash
pip install cfbpy
```

Or add it to a [uv](https://docs.astral.sh/uv/) project:

```bash
uv add cfbpy
```

## Usage

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

### Compress a Directory

```python
from cfbpy import compress

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

### Decompress a Compound File

```python
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](https://docs.astral.sh/uv/).

```bash
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.
