Skip to main content
The base content-store contract. Storage is “where content is stored” — distinct from tai42_contract.template (“what we do with it”, the render mixins). The store exposes the text surface load / list / upload / delete / delete_dir, the metadata read stat (content type and byte size), the bounded read load_range, the binary surface load_bytes / upload_bytes and the whole-object read load_object (the bytes with their content type), with the module-level assert_not_root guarding deletes against the store root. stat and load_range are abstract: only the backend knows an object’s size and how to read a slice of it without reading all of it. load_bytes / upload_bytes ship text-bridging defaults and load_object a default built on load_bytes and stat; binary-native backends override them.

ObjectStat

tai42_contract.storage.ObjectStat
Metadata for a stored object, returned by Storage.stat. Carries the content type and the byte size. content_type is the MIME type consumed for media gating (a backend that stores no metadata infers it from the path, a metadata-bearing backend returns the stored type); size is the stored object’s length in bytes. Frozen: a stat snapshot is a value, not a mutable handle. Attributes

Storage

tai42_contract.storage.Storage
The abstract object-store contract: load, list, upload and delete objects by path. Files and directories share one id space; a backend maps missing objects to FileNotFoundError and colliding paths to StoragePathConflictError.

Members

load

tai42_contract.storage.Storage.load
Return the content at path. Must raise FileNotFoundError when the item does not exist — the manager relies on that exact type to map a missing {% include %} / {% extends %} dependency to Jinja’s TemplateNotFound (so {% include ... ignore missing %} works). Content that is not UTF-8 text must raise UnicodeDecodeError (a strict decode, never a lossy substitution) — the manager maps it to a typed not-a-text-template error. Any other failure (auth, network) must propagate as its own error. Parameters

list

tai42_contract.storage.Storage.list
Return stored object paths, in no guaranteed order. With no directory, every object in the store. With a directory, only the objects beneath it (the paths starting with directory_prefix of it), read from the backend by that prefix rather than by listing the whole store; a directory holding no objects answers []. A blank directory raises ValueError. Parameters

upload

tai42_contract.storage.Storage.upload
Store content at path (create or overwrite). Files and directories share one id space, so an upload whose path collides with the store’s existing shape — an id that still names a non-empty directory, or an id nested beneath an id already held as a file — raises StoragePathConflictError. An id naming an empty leftover directory is free to hold a file. Parameters

delete

tai42_contract.storage.Storage.delete
Delete the object at path, raising FileNotFoundError when it does not exist. A caller wanting idempotent semantics maps that FileNotFoundError to a no-op. Parameters

delete_dir

tai42_contract.storage.Storage.delete_dir
Delete every object under path. Path and existence validation (ValueError / FileNotFoundError) must complete before any deletion begins — once destruction starts, failures surface as other exception types, so callers can treat those two as pre-mutation. Parameters

load_bytes

tai42_contract.storage.Storage.load_bytes
Return the raw bytes at path, with the same FileNotFoundError contract as load. Text-bridge default: reads the text via load and UTF-8 encodes it, so a text-only backend serves bytes for free. A binary-native backend (e.g. S3) overrides to return the stored bytes unaltered. Parameters

load_object

tai42_contract.storage.Storage.load_object
Return the bytes and the content type of the object at path. Raises FileNotFoundError when the object does not exist, as load does. Default: load_bytes for the bytes and stat for the type, two backend reads. A backend that answers both in one read (e.g. S3, whose object read carries its stored type) overrides, so a caller wanting both makes one call. Parameters

upload_bytes

tai42_contract.storage.Storage.upload_bytes
Store raw data at path, optionally tagging content_type. Text-bridge default: STRICT-decodes data as UTF-8 and stores it via upload; content_type is ignored (a text backend keeps no MIME metadata). The decode never passes errors= — non-UTF-8 bytes raise UnicodeDecodeError loudly rather than corrupting the stored content. A binary-native backend overrides to store data and content_type as-is. Parameters

stat

tai42_contract.storage.Storage.stat
Return the content type and the byte size of the object at path. Raises FileNotFoundError when the object does not exist; a directory is not an object. Parameters

load_range

tai42_contract.storage.Storage.load_range
Return at most length bytes of the object at path, from byte start. Fewer bytes when the object ends first, b"" when start is at or past the end. length == 0 answers b"" with no request to the backend (and so checks no existence). Raises FileNotFoundError when the object does not exist. Never reads the whole object to answer. Parameters

StoragePathConflictError

tai42_contract.storage.StoragePathConflictError
An upload id collides with the store’s existing shape. A single id space is shared by files and directories, so one id can name only one of them: an id that still names a directory holding objects cannot also become a file, and an object cannot be stored beneath an id already held as a file. A backend raises this instead of leaking a backend-specific error, so a surface maps it to a 409 conflict. path is the rejected id; conflicts names the stored ids it collides with. Attributes

Members

conflicts_summary

tai42_contract.storage.StoragePathConflictError.conflicts_summary
The conflicting ids as a human string, capped at _MESSAGE_CONFLICT_CAP. Beyond the cap a … and N more tail is appended; the full list stays on conflicts.

StoredObject

tai42_contract.storage.StoredObject
A stored object’s bytes and its content type, returned by Storage.load_object. content_type is the same MIME type Storage.stat reports. Frozen: a read object is a value, not a mutable handle. Attributes

assert_not_root

tai42_contract.storage.assert_not_root
Reject a directory path that resolves to the storage root. A blank path, one consisting only of slashes and dots ("", ".", "/", " "), or one whose normalized form escapes to or above the root ("a/..", "./x/../..") would target every stored item, so deleting it is refused. Shared by all storage backends to keep the guard identical. Parameters

directory_prefix

tai42_contract.storage.directory_prefix
The key prefix every object beneath directory starts with: the directory and one /. Surrounding slashes are dropped ("a/b/" and "/a/b" are "a/b/"). A blank directory ("", "/") names no directory and raises ValueError. Parameters