Metadata-Version: 2.4
Name: p7z
Version: 1.0.0
Summary: A Pythonic wrapper around the 7-Zip console tool (7zz/7za/7z).
Project-URL: Homepage, https://zelo.github.io/p7z/
Project-URL: Documentation, https://zelo.github.io/p7z/
Project-URL: Source, https://github.com/zelo/p7z
Project-URL: Changelog, https://zelo.github.io/p7z/latest/changelog/
Author-email: zelo <zelo@zelo.pl>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: System :: Archiving :: Compression
Classifier: Topic :: System :: Archiving :: Packaging
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown

[![PyPI version](https://img.shields.io/pypi/v/p7z.svg)](https://pypi.org/project/p7z/)
[![Python versions](https://img.shields.io/pypi/pyversions/p7z.svg)](https://pypi.org/project/p7z/)
[![License](https://img.shields.io/pypi/l/p7z.svg)](https://github.com/zelo/p7z/blob/master/LICENSE)
[![CI](https://img.shields.io/github/actions/workflow/status/zelo/p7z/ci.yml?branch=master&label=CI)](https://github.com/zelo/p7z/actions/workflows/ci.yml)

# p7z

**Drive 7-Zip from Python with an API that feels native.** 7-Zip does the work; p7z owns the
developer experience — the common thing is one obvious line, and the hard thing is one more.

![p7z in action](https://raw.githubusercontent.com/zelo/p7z/master/docs/assets/demo.gif)

## Install

```
pip install p7z
```

Wheels bundle the 7-Zip binary for Linux (x86\_64, aarch64, musl), macOS (universal2),
and Windows (x86\_64, arm64) — no separate install required. The pure-source sdist falls
back to a `7zz`/`7za`/`7z` binary on PATH.

## The common thing — one line

```python
import p7z

p7z.compress("backup.7z", ["src/", "tests/"])
p7z.extract("backup.7z", "out/")
p7z.ls("backup.7z")          # → list[Entry], typed; no string-parsing
```

## The hard things — still one line each

```python
# Read one member out of an encrypted archive, straight to bytes — no temp file.
data = p7z.read_bytes("vault.7z", "secrets.env", password="hunter2")

# Real-time progress on any operation.
p7z.compress("big.7z", ["data/"], on_progress=lambda p: print(f"{p.percent}%"))

# Compress in-memory bytes — no disk round-trip.
p7z.compress_bytes("mem.7z", "note.txt", b"generated in RAM")

# The exact same API, async — run several at once.
import asyncio
await asyncio.gather(
    p7z.acompress("a.7z", ["a/"]),
    p7z.acompress("b.7z", ["b/"]),
)
```

## Why p7z

- **It is the real 7-Zip binary under the hood** — full format support and native performance
  (minus a small subprocess-spawn cost), with no compression algorithm reimplemented in Python.
- **Zero runtime dependencies** — stdlib only; the binary ships inside the wheels.
- **DX is the product** — typed results, real-time progress, in-memory and streamed I/O,
  encryption done right, and a typed exception hierarchy.

## Features

- **Full operation surface** — compress, extract, list, test, update, delete; sync and
  async (`acompress`, `aextract`, …) with identical signatures.
- **Streaming I/O** — read entries as bytes, stream to a file object, compress from bytes
  in memory without touching the filesystem.
- **Real-time progress** — pass `on_progress=` to any operation; fires on every 7-Zip
  progress event with a typed `Progress` object.
- **Encryption** — `password=` on all read and write ops; header encryption; typed
  `WrongPasswordError` / `PasswordRequiredError`; split stdin/argv transport (reads are
  never exposed on the process list).
- **Compression tuning** — `method=`, `dict_size=`, `solid=`, `threads=`, `volume_size=`.
- **`Archive` object** — fluent handle for repeated operations on one archive.
- **Typed errors** — 7-Zip exit codes map to a named exception hierarchy; warnings
  surface without raising.
- **Zero runtime dependencies** — stdlib only; all heavy lifting is delegated to the binary.
- **Python 3.11+** — no back-compat shims; multiplatform (Linux / macOS / Windows).

A runnable tour of all of the above lives in [`examples/demo.py`](examples/demo.py).

## Documentation

Full guides (installation, operations, streaming, progress, async, error handling,
architecture) at **[https://zelo.github.io/p7z/](https://zelo.github.io/p7z/)**.

## License

p7z is **MIT-licensed**. It bundles the 7-Zip binary, which is licensed under the LGPL
(see the vendored `License.txt` shipped inside the wheel for the full 7-Zip license text,
including the unRAR and BSD clauses).
