Skip to main content

kompress lets you transparently read common compressed files and archives through a pathlib.Path-like interface.

It attempts to keep the API as close to pathlib as practical, but only supports read-oriented operations.

The common case for this is:

  • You have a compressed file that contains some text
  • You have a function (perhaps from another library that you don't control) that accepts a pathlib.Path object and calls .open(), .read_text(), or .read_bytes() on it

Without wrapping the function or adding logic to let it read from compressed files, this lets you do the following:

from pathlib import Path
from kompress import CPath


def char_count(path: Path) -> int:
    # here, if a CPath is passed, it decompresses and returns a string
    return len(path.read_text())


inp = input("Enter a file to process: ")  # file came from user
char_count(CPath(inp))

For formats containing a directory tree, select a member with the usual / operator:

export = CPath("export.tar.xz")
settings = export / "profile" / "settings.json"
print(settings.read_text())

Supported single-file compression formats:

  • .gz
  • .bz2
  • .xz
  • .zst and .zstd (on Python older than 3.14, install kompress[zstd])
  • .lz4 (install kompress[lz4])

Supported archive formats:

  • .zip
  • .tar
  • .tgz and .tar.gz
  • .tar.bz2
  • .tar.xz
  • .tar.zst (Python 3.14 or newer)

If it doesn't recognize the filetype, it will just call pathlib.Path.open, reading it like a regular file.

Installing

pip install kompress

Motivation and prior art

The design is driven by one constraint: often you can't change the consumer of the path. Plenty of third-party code accepts a pathlib.Path, isinstance-checks it, and calls .open()/.read_text()/.iterdir() on it. So kompress paths have to literally pass as pathlib.Path objects (they subclass it, with some __class__ trickery for the zip adapter), rather than merely being "path-like".

That single requirement is what rules out the existing alternatives:

  • stdlib zipfile.Path (and its standalone counterpart zipp) is the closest thing, and is what kompress.ZipPath builds on -- but it isn't an actual pathlib.Path, only covers zip, and tarfile has no equivalent at all.
  • fsspec + universal-pathlib is the mainstream general-purpose answer (UPath even subclasses pathlib.Path). It's a considerably heavier dependency though, uses URL-style paths (zip://...), and won't transparently decompress a bare .gz/.xz file on .open().
  • PyFilesystem2 (with fs.archive) has its own filesystem abstraction, not compatible with pathlib.Path; it also seems unmaintained these days.
  • smart_open does transparent decompression, but only as an open() replacement -- there is no path object to pass around.
  • patool/pyunpack and stdlib shutil.unpack_archive extract archives to disk, rather than reading members in place.
  • FUSE mounts (ratarmount, archivemount) give you real paths and fast random access into large archives, but require a mount step and platform support.
  • pathlib-abc (which grew out of the Make pathlib extensible effort) is the future-facing way to implement custom path classes, and might eventually become the proper base for kompress. However its classes deliberately don't inherit from pathlib.Path, so on their own they wouldn't pass the isinstance checks that motivate this library in the first place.

Originally discussed in this issue (transferred from HPI), which collected many of the links above.

Metadata

Release files for kompress 0.4.20261017

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for kompress 0.4.20261017
File Size Uploaded Provenance Actions
kompress-0.4.20261017.tar.gz 33.9 kB Without provenance Details for kompress-0.4.20261017.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for kompress 0.4.20261017
File Interpreter ABI Platform Actions
kompress-0.4.20261017-py3-none-any.whl Python 3 none any Details for kompress-0.4.20261017-py3-none-any.whl

Total release size: 61.6 kB

Release files / kompress-0.4.20261017.tar.gz

Download URL kompress-0.4.20261017.tar.gz
Size 33.9 kB
Tags Source
SHA-256 checksum
How to use checksums
6f93bbacea3d7afd5e953e4f8e1c3172fa511fc3ba7cc799c85deba985fd2ae5
BLAKE2b-256 checksum
How to use checksums
2db59b4e2ee2adca3968ef04f7f51e004faded8d19db2b1432ea53a1c67ed55f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / kompress-0.4.20261017-py3-none-any.whl

Download URL kompress-0.4.20261017-py3-none-any.whl
Size 27.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b45391312fa4c431d24e9167112d97f1edf250ebae41bf835fa83705d48d5ccf
BLAKE2b-256 checksum
How to use checksums
1a7a8331008e927adaf244cf793db165a5022f5c231b26736b2530d7cc4ec9fd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for kompress 0.4.20261017

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page