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
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
FileNotFoundError and colliding paths to StoragePathConflictError.
Members
load
tai42_contract.storage.Storage.load
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
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
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
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
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
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
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
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
path.
Raises FileNotFoundError when the object does not exist; a directory is
not an object.
Parameters
load_range
tai42_contract.storage.Storage.load_range
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
path is the rejected id; conflicts
names the stored ids it collides with.
Attributes
Members
conflicts_summary
tai42_contract.storage.StoragePathConflictError.conflicts_summary
_MESSAGE_CONFLICT_CAP.
Beyond the cap a … and N more tail is appended; the full list stays on
conflicts.
StoredObject
tai42_contract.storage.StoredObject
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
"", ".",
"/", " "), 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
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

