Skip to content

xtr_cache.bundle

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

CACHE_CHANNEL module-attribute

CACHE_CHANNEL: Final = 'cache'

The logging channel pools write to.

APP_POOL module-attribute

APP_POOL: Final = 'app'

The application's own pool, provided without a qualifier too.

PoolEntry

PoolEntry = AdapterEntry | Sequence[AdapterEntry] | PoolConfig

A pool: its adapter, several to chain, or a :class:PoolConfig.

AdapterEntry

AdapterEntry = str | Reference

One adapter: a DSN or keyword :class:~xtr_cache.adapter.AdapterFactory reads, or a client.

CacheBundle

Bases: Bundle[CacheConfig]

Turns a :class:CacheConfig into a pool per name in the container.

prepend_extension

prepend_extension(builder: ContainerBuilder) -> None

When logging is active, add the cache channel to its config.

load_extension

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

Register every pool under its name, the marshaller, the lock registry, the commands.

boot async

boot() -> None

Refuse an adapter no DSN serves, or a connection nobody registered, before any read.

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

Raises:

CacheConfig dataclass

CacheConfig(app: AdapterEntry | Sequence[AdapterEntry] = 'filesystem', pools: Mapping[str, PoolEntry] = _no_pools(), directory: str = '%kernel.share_dir%/cache', prefix_seed: str = '%kernel.project_dir%', stampede_lock: str | None = 'flock://%kernel.share_dir%/cache/locks')

Which cache pools exist, and what each keeps its values in.

The app pool always exists; pools adds more. Each pool is registered under the cache interfaces, qualified by its name, and app without a qualifier too. A pool given no adapter uses app's, under a namespace of its own.

An adapter is one of:

  • "filesystem" — files in :attr:directory;
  • any DSN :meth:~xtr_cache.adapter.AdapterFactory.create_adapter reads — "array", "null", "filesystem:///var/cache/app", "redis://host:6379" and the like — including env(...);
  • a :class:~xtr_dependency_injection.Reference to a client the container provides.
CacheConfig(
    app=env("CACHE_DSN"),
    pools={
        "sessions": "redis://cache:6379/1",
        "catalogue": PoolConfig(adapter=["array", "redis://cache:6379"], tags=True),
        "reports": PoolConfig(default_lifetime=3600),
    },
)

Attributes:

  • app (AdapterEntry | Sequence[AdapterEntry]) –

    The app pool's adapter, or several to chain, fastest first.

  • pools (Mapping[str, PoolEntry]) –

    Every other pool, by name.

  • directory (str) –

    Where "filesystem" keeps its files: cache under the kernel's share_dir by default, var/share in the project.

  • prefix_seed (str) –

    What every pool's namespace is derived from, with its name: the project directory by default, so two applications sharing a backend never see each other's keys. Give two applications the same seed to have them share values.

  • stampede_lock (str | None) –

    Where the locks go that let one process at a time compute a missing value — any lock DSN: file locks next to the cache files by default, "redis://…" to span machines — or None to protect only within each process.

pool_configs

pool_configs() -> dict[str, PoolConfig]

Return every pool, app first, each with its adapters resolved to a tuple.

PoolConfig dataclass

PoolConfig(adapter: AdapterEntry | Sequence[AdapterEntry] | None = None, default_lifetime: float = 0.0, tags: bool | str = False, namespace: str | None = None)

One pool: its adapter, how long its values live, and whether it takes tags.

PoolConfig(adapter=["array", "redis://cache:6379"], default_lifetime=600, tags=True)
PoolConfig(adapter="redis://cache:6379", tags="tag_versions")  # versions in another pool

Attributes:

  • adapter (AdapterEntry | Sequence[AdapterEntry] | None) –

    The adapter, or several to chain, fastest first. None uses the application pool's.

  • default_lifetime (float) –

    Seconds a value lives when its item sets no expiry; 0 for no limit.

  • tags (bool | str) –

    Whether items can be tagged and invalidated by tag — True keeping tag versions in the pool itself, or the name of another pool to keep them in, a faster or wider-shared one.

  • namespace (str | None) –

    What every key is put under. None derives one from the pool's name and the configuration's prefix seed, so pools sharing a backend never see each other's keys.

adapters

adapters() -> tuple[AdapterEntry, ...]

Return the adapters as a tuple; empty when the pool uses the application pool's.