p7z 1.0.0

A Pythonic wrapper around the 7-Zip console tool (7zz/7za/7z).

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.

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

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

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

Documentation

Full guides (installation, operations, streaming, progress, async, error handling, architecture) at 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).