simvx.core.assets.source

Source protocol: abstract storage backend that yields bytes for a URI.

Sources do not parse: they just resolve a URI to bytes (and optional versioning metadata). Loaders parse those bytes into typed assets.

URI schemes supported by built-in Sources:

• pkg://<package>/<path>: Python package resource (importlib.resources).

• file:///<absolute path>: filesystem.

• Bare relative path: also routed to FileSource for ergonomics.

• http://... / https://...: network (HttpSource).

• mem://<key>: in-memory test source.

User code rarely touches Sources directly; the

class:

~simvx.core.assets.server.AssetServer looks up the right Source from a URI’s scheme.

Module Contents

Classes

Source

Storage backend mapped to a URI scheme.

API

class simvx.core.assets.source.Source

Bases: typing.Protocol

Storage backend mapped to a URI scheme.

Implementations should be cheap to construct and stateless beyond configuration; the AssetServer shares one instance per scheme.

scheme: str

None

read_bytes(uri: str) → bytes

Resolve uri and return the contents as raw bytes.

Should raise :class:FileNotFoundError, :class:OSError, or a source-specific exception on failure. Network sources may raise

Class:

ConnectionError or :class:TimeoutError.

version(uri: str) → str | None

Return a version hint (etag/mtime/None) for cache invalidation.

Implementations that don’t support versioning return None. AssetServer uses the value as part of the cache key.

list(uri: str) → collections.abc.Iterable[str]

List child URIs under uri (folder enumeration).

Sources that cannot list (e.g. HTTP without directory indexing) should raise :class:NotImplementedError.

__slots__

()

classmethod __init_subclass__(*args, **kwargs)

classmethod __class_getitem__(item)