Zstar for Python
Python bindings for reading and writing Zstar indexed tar archives, with synchronous, asyncio, and optional fsspec APIs. Python 3.11 or later is required.
Installation
pip install zstar-py
# Include the optional fsspec integration:
pip install 'zstar-py[fsspec]'
The distribution is named zstar-py; the import is zstar. For a local build
and the installed-wheel test suite, run just check from the repository root.
Read an archive
from zstar import Archive, pack_file
encoded = pack_file("hello.txt", b"hello world")
with Archive(encoded) as archive:
assert archive.read("hello.txt", offset=6, length=5) == b"world"
Use Archive.open("archive.zstar") for a local file,
Archive.open(fileobj=source) for a borrowed seekable binary object, or
Archive.from_url(url) for HTTP ranges. HTTP sources require a strong ETag.
Keep borrowed sources immutable and open until the reader closes.
Opening authenticates the complete manifest. Reads validate selected frames;
use archive.verify() for full archive validation. External content requires a
resolver; use archive.verify(external=True) to validate the external closure. Digests establish internal
consistency, not authenticity.
Write an archive
from io import BytesIO
from tarfile import TarInfo
from zstar import ArchiveWriter
info = TarInfo("hello.txt")
info.size = 5
info.mode = 0o644
with ArchiveWriter.open("archive.zstar", mode="x") as writer:
writer.addfile(info, BytesIO(b"hello"))
Successful close finalizes the manifest and footer. Mode x refuses an existing
file; mode w replaces it. ArchiveWriter(fileobj) borrows a binary sink and
leaves it open. Paths use / separators and require explicit ancestor-directory
entries. Use writer.add(path, arcname=...) to capture filesystem entries, or
pack_directory(path) to collect a complete archive in memory.
Async reads
import asyncio
from zstar import AsyncArchive, pack_file
async def main():
encoded = pack_file("hello.txt", b"hello")
async with await AsyncArchive.from_bytes(encoded) as archive:
assert await archive.read("hello.txt") == b"hello"
asyncio.run(main())
AsyncArchive.open, from_source, from_url, and from_s3 are also async
constructors. Await metadata lookups such as getmember; iterate getmembers() with async for.
fsspec
Install the fsspec extra, then open a member through a filesystem:
from zstar import ZstarFileSystem
fs = ZstarFileSystem(fo="archive.zstar")
try:
with fs.open("hello.txt", "rb") as member:
data = member.read()
finally:
fs.close()
ZstarFileSystem(fo=...) accepts an archive path or binary file object and
provides read-only listing, globbing, and member streams. Close the filesystem
when finished. Generic remote chains use the selected backend's snapshot and
cache policies.
Reader, writer, source, cache, and filesystem classes document their ownership, limits, and thread-safety contracts in their docstrings and type definitions. The [format specification][spec] defines wire rules and validation scopes. [spec]: https://github.com/brian14708/zstar/blob/main/spec/v1.md
Metadata
Release files for zstar-py 0.0.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| zstar_py-0.0.1.tar.gz | 259.9 kB | With provenance | Details for zstar_py-0.0.1.tar.gz |
Built distributions (wheels)
| File | Actions Reset | |||
|---|---|---|---|---|
| zstar_py-0.0.1-cp311-abi3-win_amd64.whl | CPython 3.11 | abi3 | Windows x86-64 | Details for zstar_py-0.0.1-cp311-abi3-win_amd64.whl |
| zstar_py-0.0.1-cp311-abi3-manylinux_2_28_x86_64.whl | CPython 3.11 | abi3 | Linux glibc 2.28+ x86-64 | Details for zstar_py-0.0.1-cp311-abi3-manylinux_2_28_x86_64.whl |
| zstar_py-0.0.1-cp311-abi3-manylinux_2_28_aarch64.whl | CPython 3.11 | abi3 | Linux glibc 2.28+ ARM64 | Details for zstar_py-0.0.1-cp311-abi3-manylinux_2_28_aarch64.whl |
| zstar_py-0.0.1-cp311-abi3-macosx_14_0_arm64.whl | CPython 3.11 | abi3 | macOS 14.0+ ARM64 | Details for zstar_py-0.0.1-cp311-abi3-macosx_14_0_arm64.whl |
Total release size: 21.6 MB
Release files / zstar_py-0.0.1.tar.gz
| Download URL | zstar_py-0.0.1.tar.gz |
|---|---|
| Size | 259.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6812f559ea624c7e8cfcfa94eb1f05803b97096c2d7a1a96042e144456aad61a
|
|
BLAKE2b-256 checksum How to use checksums |
e1b528d8e3e8633a94999f2e4863f1e644d80afa51a2fb24b079375fa9d395d2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.
Transparency logRelease files / zstar_py-0.0.1-cp311-abi3-win_amd64.whl
| Download URL | zstar_py-0.0.1-cp311-abi3-win_amd64.whl |
|---|---|
| Size | 5.2 MB |
| Tags | CPython 3.11 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
64c1d7c6c0766d35cb2a8bdd5cc526d6ebbff4d62dd3a75af14ee6d4cbc72c9a
|
|
BLAKE2b-256 checksum How to use checksums |
9a507fd7925b52be550437f1c18c419307569321e2cd62a932cc80a067590de9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.
Transparency logRelease files / zstar_py-0.0.1-cp311-abi3-manylinux_2_28_x86_64.whl
| Download URL | zstar_py-0.0.1-cp311-abi3-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 5.8 MB |
| Tags | CPython 3.11 Linux glibc 2.28+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
34da6b3bf26e50149f107b07042a86d270a5c0caed553d3db3a218ae13bee5a8
|
|
BLAKE2b-256 checksum How to use checksums |
ce351b9f08b9219b922937c97395c9b6cdbfd4f7cac48097ddbb74f17ede798a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.
Transparency logRelease files / zstar_py-0.0.1-cp311-abi3-manylinux_2_28_aarch64.whl
| Download URL | zstar_py-0.0.1-cp311-abi3-manylinux_2_28_aarch64.whl |
|---|---|
| Size | 5.6 MB |
| Tags | CPython 3.11 Linux glibc 2.28+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
7708bc1ed22ae7c77d87c8322d45dc05fe5a774b28ecb105a4e9115415a85cfb
|
|
BLAKE2b-256 checksum How to use checksums |
74568c53942d2d28a257801c925746a4abac6a4c517695a896878a072ea4f1b2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.
Transparency logRelease files / zstar_py-0.0.1-cp311-abi3-macosx_14_0_arm64.whl
| Download URL | zstar_py-0.0.1-cp311-abi3-macosx_14_0_arm64.whl |
|---|---|
| Size | 4.7 MB |
| Tags | CPython 3.11 abi3 macOS 14.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
fbac6dfbe50fdba153d30da5142cc904ccfb571a37b4bec402743fc0bd6e80d7
|
|
BLAKE2b-256 checksum How to use checksums |
0758584432cdbff6def461c0a04de2024f81c43df560c5483123a50be03b6fd3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.
Transparency logSecurity for zstar-py 0.0.1
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.
Full provenance
All 5 files in this release have been uploaded with provenance metadata.
Attestation for zstar_py-0.0.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 31, 2026.
Transparency logA 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.