Skip to content

xtr_storage.bundle

The xtr-dependency-injection bundle for xtr-storage.

DEFAULT_STORAGE module-attribute

DEFAULT_STORAGE = 'default'

The storage whose services are provided without a qualifier too.

AdapterEntry

AdapterEntry = LocalAdapterConfig | MemoryAdapterConfig | S3AdapterConfig | GcsAdapterConfig | FsspecAdapterConfig | Reference

One adapter: a configuration the bundle builds, or a service the container provides.

FsspecAdapterConfig dataclass

FsspecAdapterConfig(protocol: str, root: str = '', options: Mapping[str, object] = _empty_options())

Any other backend, named by its protocol and built for the application.

A caller who wants a backend this library has no named adapter for — an SFTP server, an in-cluster store — names its protocol and the keyword options that backend takes, and the bundle builds the filesystem. Visibility is not offered, so a definition that names one over such a backend is refused at boot.

Attributes:

  • protocol (str) –

    The filesystem protocol to build, such as "memory".

  • root (str) –

    What every path is stored under — a directory or a key prefix.

  • options (Mapping[str, object]) –

    The keyword options the backend is built with — a host, a passphrase, a key file. Kept out of the repr.

GcsAdapterConfig dataclass

GcsAdapterConfig(bucket: str, prefix: str = '', project: str | None = None, token: str | None = None, endpoint_url: str | None = None, write_options: Mapping[str, object] = _empty_options())

A bucket on Google Cloud Storage, through the gcs extra.

Visibility is not offered on this backend in this version, so a definition that names one over a bucket configured this way is refused at boot.

Attributes:

  • bucket (str) –

    The bucket every path lives in.

  • prefix (str) –

    A key prefix within the bucket the caller never sees.

  • project (str | None) –

    The project the bucket belongs to, for operations that need one.

  • token (str | None) –

    How the backend authenticates. Kept out of the repr.

  • endpoint_url (str | None) –

    Where to reach the store, for pointing at an emulator.

  • write_options (Mapping[str, object]) –

    Settings every write forwards unless a call overrides them. Kept out of the repr.

LocalAdapterConfig dataclass

LocalAdapterConfig(directory: str = '%kernel.project_dir%/var/storage', file_public: int = 420, file_private: int = 384, directory_public: int = 493, directory_private: int = 448, link_handling: LinkHandling = LinkHandling.DISALLOW)

Files on the disk of the machine the application runs on.

The default directory sits under the project's own var so an unconfigured application has somewhere to write without being told one, and two projects on one machine never share a tree. The four mode fields are what a visibility becomes on disk; a deployment whose web server runs as another user widens them.

Attributes:

  • directory (str) –

    The directory every path is relative to.

  • file_public (int) –

    The mode a file readable by everyone carries.

  • file_private (int) –

    The mode a file readable by its owner alone carries.

  • directory_public (int) –

    The mode a directory everyone may enter carries.

  • directory_private (int) –

    The mode a directory its owner alone may enter carries.

  • link_handling (LinkHandling) –

    What a listing does with a symbolic link it meets.

MemoryAdapterConfig dataclass

MemoryAdapterConfig(default_visibility: Visibility | str = Visibility.PUBLIC)

Files in a dictionary that vanish with the process.

What a test reaches for and what an application uses when a storage is only somewhere to hand bytes between two steps of one request.

Attributes:

  • default_visibility (Visibility | str) –

    What a file is worth when a write named none — a :class:~xtr_storage.Visibility or the string one carries.

S3AdapterConfig dataclass

S3AdapterConfig(bucket: str, prefix: str = '', region: str | None = None, endpoint_url: str | None = None, key: str | None = None, secret: str | None = None, token: str | None = None, anon: bool = False, client_kwargs: Mapping[str, object] = _empty_options(), config_kwargs: Mapping[str, object] = _empty_options(), write_options: Mapping[str, object] = _empty_options())

A bucket on Amazon S3 or a compatible store, through the s3 extra.

The credentials are optional because the backend can find them in the environment or an instance role; give them here only when the application holds them itself. An endpoint_url points the adapter at a compatible store or a local test server.

Attributes:

  • bucket (str) –

    The bucket every object is stored in.

  • prefix (str) –

    A key prefix under which this storage's objects live.

  • region (str | None) –

    The bucket's region, used to compose a public url.

  • endpoint_url (str | None) –

    An alternate endpoint, for a compatible store or emulator.

  • key (str | None) –

    The access key id, or None to let the backend find one. Kept out of the repr.

  • secret (str | None) –

    The secret access key, paired with key. Kept out of the repr.

  • token (str | None) –

    A session token, for temporary credentials. Kept out of the repr.

  • anon (bool) –

    Whether to reach the store without credentials.

  • client_kwargs (Mapping[str, object]) –

    Extra keyword settings for the underlying client. Kept out of the repr.

  • config_kwargs (Mapping[str, object]) –

    Extra client configuration for the underlying client. Kept out of the repr.

  • write_options (Mapping[str, object]) –

    Default write settings; only known keys are forwarded. Kept out of the repr.

StorageBundle

Bases: Bundle[StorageConfig]

Turns a :class:StorageConfig into a storage per name, and one mount over them.

load_extension

load_extension(config: StorageConfig, services: ServiceConfigurator, builder: ContainerBuilder) -> None

Register a storage under each name, its interface aliases, and the mount.

Each storage is an async-generator factory injecting the configuration and the container rather than closing over them, so an env(...) placeholder in the configuration is resolved when the storage is built.

boot async

boot() -> None

Refuse a reference nobody registered, a missing backend, or a bad visibility.

The configuration is read resolved, so a value given as env(...) is read here, and a variable that is not set fails the boot.

Raises:

StorageConfig dataclass

StorageConfig(storages: Mapping[str, StorageDefinition | AdapterEntry] = _default_storages())

Which storages exist, and how each one is built.

Every storage becomes a :class:~xtr_storage.Storage qualified by its name, reachable under the reader, writer and operator interfaces the same way; the one named "default" is provided without a qualifier too. A :class:~xtr_storage.MountManager over all of them is provided as well.

An entry is either a full :class:StorageDefinition or, as a shorthand, a bare adapter configuration — a :class:~xtr_storage.bundle.LocalAdapterConfig and the like, or a :class:Reference to an adapter the container provides — which is read as a definition with that adapter and everything else left at its default.

StorageConfig(
    storages={
        "default": LocalAdapterConfig(),
        "avatars": StorageDefinition(adapter=S3AdapterConfig("uploads"), prefix="avatars"),
    }
)

Attributes:

definitions

definitions() -> dict[str, StorageDefinition]

Return every storage as a full definition; the default when none is set.

A bare adapter configuration is wrapped in a :class:StorageDefinition naming it, so callers see one shape.

StorageDefinition dataclass

StorageDefinition(adapter: AdapterEntry = LocalAdapterConfig(), visibility: Visibility | str | None = None, directory_visibility: Visibility | str | None = None, retain_visibility: bool = True, public_url: str | Sequence[str] | None = None, public_url_generator: Reference | None = None, temporary_url_generator: Reference | None = None, read_only: bool = False, prefix: str | None = None, allow_relative_path_traversal: bool = True)

One storage in full: which backend it is, and how it behaves in front of it.

The adapter is the only thing a storage cannot do without, so it has a default — files under the project's var — and everything else layers on top of it. prefix roots the storage inside its backend, read_only forbids every write, and the visibility and url fields become the standing options the storage was built with, the defaults each call is laid over.

A public_url_generator or temporary_url_generator is a :class:Reference to a service the container provides, for a deployment that hands out addresses through a component of its own rather than the backend.

Attributes:

  • adapter (AdapterEntry) –

    What the storage stores through.

  • visibility (Visibility | str | None) –

    The default visibility a write gives a file.

  • directory_visibility (Visibility | str | None) –

    The default visibility a write gives a directory.

  • retain_visibility (bool) –

    Whether a copy or a move keeps what the source had.

  • public_url (str | Sequence[str] | None) –

    One prefix files are reachable from, or several to spread them over.

  • public_url_generator (Reference | None) –

    A service that builds lasting addresses.

  • temporary_url_generator (Reference | None) –

    A service that builds expiring addresses.

  • read_only (bool) –

    Whether every write is refused.

  • prefix (str | None) –

    A path the storage is rooted at inside its backend.

  • allow_relative_path_traversal (bool) –

    Whether .. in a path may climb.