PTWM
ptwm

ptwm.stores

Pluggable weight-storage backends behind a shared :class:WeightStore API.

ptwm.stores

Pluggable weight-storage backends behind a shared :class:WeightStore API.

pymodule

ptwm.stores

python/ptwm/stores/__init__.py:1
module ptwm.stores

Pluggable weight-storage backends behind a shared :class:`WeightStore` API.

PTWM's binary container, an LMDB environment, and a WebDataset shard set are three serializations of the same canonical PTWM-JSON manifest. This package exposes them behind one protocol and an :func:`open_store` auto-detector. The LMDB and WebDataset integrations are opt-in extras (``ptwm[lmdb]``, ``ptwm[webdataset]``) and their third-party dependencies are imported lazily.
pyfunction

ptwm.stores.decode_member_tensor

python/ptwm/stores/_common.py:131
def decode_member_tensor(registry_json: str, tensor_json: str, members: dict[str, bytes]) -> torch.Tensor

Reconstruct a single tensor (as a :class:`torch.Tensor`) from members.

pyfunction

ptwm.stores.detect_format

python/ptwm/stores/__init__.py:49
def detect_format(path: str | Path) -> str | None

Return ``"ptwm"`` / ``"lmdb"`` / ``"webdataset"`` for ``path`` or ``None``.

Detection follows the resolved spec: WebDataset via ``index.json.ptwm_format == "ptwm-wds"`` (or a ``__shardmeta__.json`` member in a single shard); LMDB via the ``\\x00fmt`` key (an env directory contains ``data.mdb``); native ``.ptwm`` via the container magic.
pyfunction

ptwm.stores.explode_model

python/ptwm/stores/_common.py:96
def explode_model(blob: bytes) -> ExplodedModel

Explode a multi-tensor ``.ptwm`` container blob into an exploded model.

pyclass

ptwm.stores.ExplodedModel

python/ptwm/stores/_common.py:60
class ExplodedModel:

A compressed model projected to its canonical PTWM-JSON form.

Holds the archive registry manifest, the per-tensor manifests in file order, and the loose binary members. The LMDB and WebDataset writers consume this.
pymethod

ptwm.stores.ExplodedModel.__init__

python/ptwm/stores/_common.py:69
def __init__(self, registry_json: str, tensors: list[tuple[str, str, str]], members: dict[str, bytes]) -> None
pymethod

ptwm.stores.ExplodedModel.key

python/ptwm/stores/_common.py:86
def key(self, name: str) -> str
pymethod

ptwm.stores.ExplodedModel.member_size

python/ptwm/stores/_common.py:89
def member_size(self, name: str) -> int

Total compressed bytes owned by ``name`` (planes + per-tensor state).

pyattribute

ptwm.stores.ExplodedModel.members

python/ptwm/stores/_common.py:77
members = members
pymethod

ptwm.stores.ExplodedModel.names

python/ptwm/stores/_common.py:80
def names(self) -> list[str]
pyattribute

ptwm.stores.ExplodedModel.registry_json

python/ptwm/stores/_common.py:75
registry_json = registry_json
pymethod

ptwm.stores.ExplodedModel.tensor_json

python/ptwm/stores/_common.py:83
def tensor_json(self, name: str) -> str
pyattribute

ptwm.stores.ExplodedModel.tensors

python/ptwm/stores/_common.py:76
tensors = tensors
pyfunction

ptwm.stores.jcs_canonicalize

python/ptwm/stores/_common.py:149
def jcs_canonicalize(obj: Any) -> str

Serialize ``obj`` to a canonical (RFC 8785) JSON string.

Mirrors the Rust ``serde_jcs``-equivalent serializer in ``ptwm-core``: object keys sorted by UTF-16 code unit, no insignificant whitespace, integers in shortest form. Floats are rejected to enforce the integers-only-scalar manifest schema.
pyclass

ptwm.stores.LmdbWeightStore

python/ptwm/stores/_lmdb.py:187
class LmdbWeightStore:

Read/update API over an LMDB-backed PTWM model (both layouts).

pymethod

ptwm.stores.LmdbWeightStore.__enter__

python/ptwm/stores/_lmdb.py:238
def __enter__(self) -> Self
pymethod

ptwm.stores.LmdbWeightStore.__exit__

python/ptwm/stores/_lmdb.py:241
def __exit__(self, *exc: object = ()) -> None
pymethod

ptwm.stores.LmdbWeightStore.__init__

python/ptwm/stores/_lmdb.py:190
def __init__(self, path: str | Path, map_size: int = _DEFAULT_MAP_SIZE, readonly: bool = True) -> None
pymethod

ptwm.stores.LmdbWeightStore.close

python/ptwm/stores/_lmdb.py:234
def close(self) -> None

Close the underlying LMDB environment.

pymethod

ptwm.stores.LmdbWeightStore.get_bytes

python/ptwm/stores/_lmdb.py:309
def get_bytes(self, name: str) -> bytes

Return the raw decompressed bytes for ``name``.

pymethod

ptwm.stores.LmdbWeightStore.get_tensor

python/ptwm/stores/_lmdb.py:323
def get_tensor(self, name: str) -> torch.Tensor

Decompress ``name`` and return a :class:`torch.Tensor`.

pyattribute

ptwm.stores.LmdbWeightStore.layout

python/ptwm/stores/_lmdb.py:245
layout: str

Either ``"blob"`` or ``"exploded"``.

pymethod

ptwm.stores.LmdbWeightStore.names

python/ptwm/stores/_lmdb.py:305
def names(self) -> list[str]

Return tensor names in storage order.

pymethod

ptwm.stores.LmdbWeightStore.open

python/ptwm/stores/_lmdb.py:229
def open(cls, path: str | Path, readonly: bool = True) -> LmdbWeightStore

Open an LMDB PTWM environment for reading (or updating).

pymethod

ptwm.stores.LmdbWeightStore.put_tensor

python/ptwm/stores/_lmdb.py:353
def put_tensor(self, name: str, raw: bytes, dtype: Any, shape: tuple[int, ...], delta_reference: str | None = None, method_hint: int = 3) -> None

Atomically insert or replace tensor ``name`` (blob layout only).

When ``delta_reference`` names another tensor already in the store, the new tensor is stored as an XOR residual against it (a ``local_tensor`` reference with BLAKE3 verification), turning small per-step changes into small diffs.
pymethod

ptwm.stores.LmdbWeightStore.stream_tensors

python/ptwm/stores/_lmdb.py:343
def stream_tensors(self, names: Iterable[str] | None = None) -> Iterator[tuple[str, torch.Tensor]]

Yield ``(name, tensor)`` pairs.

pyfunction

ptwm.stores.open_store

python/ptwm/stores/__init__.py:88
def open_store(path: str | Path) -> WeightStore

Open ``path`` as a :class:`WeightStore`, auto-detecting the format.

pyfunction

ptwm.stores.raw_from_members

python/ptwm/stores/_common.py:116
def raw_from_members(registry_json: str, tensor_json: str, members: dict[str, bytes]) -> bytes

Reconstruct a one-tensor container and return its raw decompressed bytes.

``members`` must contain the tensor's plane/state members plus any archive-global shared state referenced by ``registry_json``.
pyconstant

ptwm.stores.SHARDMETA_MEMBER

python/ptwm/stores/_webdataset.py:46
SHARDMETA_MEMBER = '__shardmeta__.json'
pyconstant

ptwm.stores.WDS_FORMAT

python/ptwm/stores/_webdataset.py:45
WDS_FORMAT = 'ptwm-wds'
pyclass

ptwm.stores.WebDatasetWeightStore

python/ptwm/stores/_webdataset.py:132
class WebDatasetWeightStore:

Read API over a WebDataset shard set (or a single shard for streaming).

pymethod

ptwm.stores.WebDatasetWeightStore.__enter__

python/ptwm/stores/_webdataset.py:186
def __enter__(self) -> Self
pymethod

ptwm.stores.WebDatasetWeightStore.__exit__

python/ptwm/stores/_webdataset.py:189
def __exit__(self, *exc: object = ()) -> None
pymethod

ptwm.stores.WebDatasetWeightStore.__init__

python/ptwm/stores/_webdataset.py:135
def __init__(self, path: str | Path) -> None
pymethod

ptwm.stores.WebDatasetWeightStore.close

python/ptwm/stores/_webdataset.py:179
def close(self) -> None

Close any open shard tar handles.

pymethod

ptwm.stores.WebDatasetWeightStore.get_bytes

python/ptwm/stores/_webdataset.py:239
def get_bytes(self, name: str) -> bytes

Return the raw decompressed bytes for ``name``.

pymethod

ptwm.stores.WebDatasetWeightStore.get_tensor

python/ptwm/stores/_webdataset.py:246
def get_tensor(self, name: str) -> torch.Tensor

Decompress ``name`` and return a :class:`torch.Tensor`.

pymethod

ptwm.stores.WebDatasetWeightStore.names

python/ptwm/stores/_webdataset.py:235
def names(self) -> list[str]

Return tensor names in storage order.

pymethod

ptwm.stores.WebDatasetWeightStore.open

python/ptwm/stores/_webdataset.py:174
def open(cls, path: str | Path) -> WebDatasetWeightStore

Open a WebDataset store directory (or a single shard).

pymethod

ptwm.stores.WebDatasetWeightStore.stream_tensors

python/ptwm/stores/_webdataset.py:253
def stream_tensors(self, names: Iterable[str] | None = None) -> Iterator[tuple[str, torch.Tensor]]

Yield ``(name, tensor)`` pairs, reading shards sequentially.

Pure streaming: each shard is read once, its samples grouped and decoded via the per-shard ``__shardmeta__.json`` registry. No global index or container is materialized.
pymethod

ptwm.stores.WebDatasetWeightStore.webdataset_pipeline

python/ptwm/stores/_webdataset.py:296
def webdataset_pipeline(self) -> Any

Return a ``webdataset.WebDataset`` over the shard URLs.

Lazily imports the optional ``webdataset`` package (``pip install 'ptwm[webdataset]'``). Each yielded item is ``(name, tensor)``.
pyclass

ptwm.stores.WeightStore

python/ptwm/stores/_common.py:33
class WeightStore(Protocol):

Read API shared by every PTWM storage backend.

Generalizes :class:`ptwm.random_access.TensorIndex` so callers can treat a native ``.ptwm`` container, an LMDB environment, and a WebDataset shard set interchangeably.
pymethod

ptwm.stores.WeightStore.get_bytes

python/ptwm/stores/_common.py:45
def get_bytes(self, name: str) -> bytes

Return the raw decompressed bytes for ``name``.

pymethod

ptwm.stores.WeightStore.get_tensor

python/ptwm/stores/_common.py:48
def get_tensor(self, name: str) -> torch.Tensor

Decompress ``name`` and return a :class:`torch.Tensor`.

pymethod

ptwm.stores.WeightStore.names

python/ptwm/stores/_common.py:42
def names(self) -> list[str]

Return tensor names in storage order.

pymethod

ptwm.stores.WeightStore.stream_tensors

python/ptwm/stores/_common.py:51
def stream_tensors(self, names: Iterable[str] | None = None) -> Iterator[tuple[str, torch.Tensor]]

Yield ``(name, tensor)`` pairs.

pyfunction

ptwm.stores.write_lmdb

python/ptwm/stores/_lmdb.py:71
def write_lmdb(path: str | Path, tensors: Sequence[tuple[str, bytes, Any, tuple[int, ...]]], layout: str = 'blob', map_size: int = _DEFAULT_MAP_SIZE, method_hint: int = 3, chains_per_tensor: list[list[bytes]] | None = None) -> Path

Write ``tensors`` into an LMDB environment at ``path``.

``layout`` is ``"blob"`` (default) or ``"exploded"``. Returns ``path``.
pyfunction

ptwm.stores.write_webdataset

python/ptwm/stores/_webdataset.py:66
def write_webdataset(out_dir: str | Path, tensors: Sequence[tuple[str, bytes, Any, tuple[int, ...]]], max_shard_size: int = _DEFAULT_MAX_SHARD_SIZE, method_hint: int = 3, chains_per_tensor: list[list[bytes]] | None = None) -> Path

Write ``tensors`` as a WebDataset shard set rooted at ``out_dir``.

Returns the directory path. ``tensors`` is a sequence of ``(name, raw_bytes, dtype, shape)``; shards are packed by compressed size via :func:`ptwm.sharding.plan_shards` so a tensor never straddles a shard.