Python API¶

itar.open returns an IndexedTarFile, a mapping-like view that streams members directly from the underlying tar shards. Use it as a context manager and access members like dictionary values.

itar ¶

IndexedTarFile ¶

Bases: Mapping

Read-only mapping that serves members out of indexed tar shards.

PARAMETER	DESCRIPTION
`shards`	Shard sources (single tar, list of tars, or resolver callable). TYPE: `list[Shard] \| Shard \| ShardResolver`
`index`	Precomputed index mapping member names to offsets. TYPE: `IndexedTarIndex`
`open_fn`	Optional callable to open paths; defaults to a thread-safe file reader. TYPE: `Callable[[str \| PathLike], IO[bytes]]` DEFAULT: `None`
`buffered_file_reader`	Wrap member streams in a buffered reader when True. TYPE: `bool` DEFAULT: `True`

Use itar.open to construct this class. It supports the mapping protocol for read access (archive["path/to/file"]) and should be used as a context manager to close any open file handles.

Example

import itar

with itar.open("photos.itar") as archive:
    jpg = archive["vacation/sunrise.jpg"].read()
    assert "wedding/cake.jpg" in archive

file ¶

file(name: str) -> IO[bytes]

Return a readable file-like object for an indexed member.

info ¶

info(name: str) -> TarInfo

Return the TarInfo for an indexed member without reading data.

check_tar_index ¶

check_tar_index(names: list[str] | None = None)

Validate stored offsets for the given names (or all members).

These helpers are the public surface for building and loading .itar indexes.

itar.index ¶

create ¶

create(path: str | PathLike, shards: list[Shard] | Shard, *, progress_bar: bool = True) -> IndexedTarIndex

Build an index for shards and save it to path.

open ¶

open(path: str | PathLike, shards: list[Shard] | Shard | None = None, open_fn: Callable[[str | PathLike], IO[bytes]] | None = None, buffered_file_reader: bool = True) -> IndexedTarFile

Open an IndexedTarFile using an on-disk index file.

build ¶

build(shards: list[Shard] | Shard, *, progress_bar: bool = False) -> IndexedTarIndex

Build an index mapping without instantiating IndexedTarFile.

dump ¶

dump(index: IndexedTarIndex, path: str | PathLike) -> None

Persist index to disk in msgpack format.

load ¶

load(path: str | PathLike) -> IndexedTarIndex

Load an index dictionary from a saved .itar index file.