xtr_storage.bundle ¶
The xtr-dependency-injection bundle for xtr-storage.
DEFAULT_STORAGE
module-attribute
¶
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
¶
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.Visibilityor 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
Noneto let the backend find one. Kept out of therepr. -
secret(str | None) –The secret access key, paired with
key. Kept out of therepr. -
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
¶
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:
-
InvalidArgumentError–Naming the storage whose configuration is wrong.
StorageConfig
dataclass
¶
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:
-
storages(Mapping[str, StorageDefinition | AdapterEntry]) –Each storage by name. An empty mapping means the default.
definitions ¶
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.