Skip to main content

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)

Source distribution for zstar-py 0.0.1
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)

Table of built distributions (wheels) for zstar-py 0.0.1
File Actions
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 log

Release 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 log

Release 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 log

Release 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 log

Release 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 log

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

Select from 5 files

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 log

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.

Release history Release notifications | RSS feed

This release

0.0.1 This release

5 release files Full provenance

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