xtr-cache 5.0.1__tar.gz → 5.2.0__tar.gz

{xtr_cache-5.0.1 → xtr_cache-5.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xtr-cache
-Version: 5.0.1
+Version: 5.2.0
 Summary: Cache pools in memory, in files, in Redis, chained or tag-aware, with stampede protection.
 Keywords: cache,redis,stampede,tags,asyncio
 Author: Xterr
@@ -297,19 +297,21 @@ Everything adding this package to an application on
 - **Install** — `uv add xtr-cache xtr-dependency-injection`: the bundle needs the container
   installed beside it, never as an extra. Add `redis` or `sodium` for what you use; install
   xtr-console beside it for the `cache:pool:*` commands, and xtr-logging for a `cache` channel.
-- **Recipe** — `uv run xtr-recipes recipes:sync` does the *Activate* and *Ignore* steps below: it
-  lists `CacheBundle` and ignores `/var/`. There is no config file or environment to write.
-- **Activate** — `CacheBundle: {"all": True}` in `BUNDLES` in `<app>/bundles.py`, imported
+- **Recipe** — `uv run xtr-recipes recipes:sync` does the *Activate*, *Configure* and *Ignore*
+  steps below: it lists `CacheBundle`, writes `<app>/config/packages/cache.py` with the bundle's
+  own defaults, and ignores `/var/`. There is no environment to write.
+- **Activate** — `CacheBundle: {"all": True}` in `BUNDLES` in `<app>/config/bundles.py`, imported
   from `xtr_cache.bundle`.
 - **Brings along** — the logging and console bundles, when those packages are installed.
-- **Configure** — optional: with no configuration there is one `app` pool on files. Pools,
-  adapters and the stampede lock go in `<app>/config/cache.py`, a `@configure` function
-  returning `CacheConfig` — see [Kernel / bundle](#kernel--bundle).
+- **Configure** — optional: the recipe writes `<app>/config/packages/cache.py` holding the
+  defaults, one `app` pool on files. Pools, adapters and the stampede lock go in that same
+  `@configure` function returning `CacheConfig` — see [Kernel / bundle](#kernel--bundle).
 - **Environment** — nothing required. A DSN given as `env(...)` must be set when the
   application boots: booting checks every pool.
 - **Ignore** — `var/`: files live under `kernel.share_dir`, `var/share` in the project.
-- **Remove** — drop the `BUNDLES` entry, delete `<app>/config/cache.py`, then
-  `uv remove xtr-cache`.
+- **Remove** — drop the `BUNDLES` entry; `uv run xtr-recipes recipes:remove xtr-cache` deletes
+  `<app>/config/packages/cache.py`, unless you edited it, in which case it is moved aside to
+  `cache.py.removed`. Then `uv remove xtr-cache`.
 - **Check** — `debug:bundles` shows `cache` as `listed` and `active`.
 
 ## Kernel / bundle
@@ -319,14 +321,14 @@ not a dependency, and nothing outside `xtr_cache.bundle` needs it — list the b
 pools:
 
 ```python
-# app/bundles.py
+# app/config/bundles.py
 from xtr_cache.bundle import CacheBundle
 
 BUNDLES = {CacheBundle: {"all": True}}
 ```
 
 ```python
-# app/config/cache.py
+# app/config/packages/cache.py
 from xtr_dependency_injection import configure, env
 from xtr_cache.bundle import CacheConfig, PoolConfig
 

{xtr_cache-5.0.1 → xtr_cache-5.2.0}/README.md

@@ -268,19 +268,21 @@ Everything adding this package to an application on
 - **Install** — `uv add xtr-cache xtr-dependency-injection`: the bundle needs the container
   installed beside it, never as an extra. Add `redis` or `sodium` for what you use; install
   xtr-console beside it for the `cache:pool:*` commands, and xtr-logging for a `cache` channel.
-- **Recipe** — `uv run xtr-recipes recipes:sync` does the *Activate* and *Ignore* steps below: it
-  lists `CacheBundle` and ignores `/var/`. There is no config file or environment to write.
-- **Activate** — `CacheBundle: {"all": True}` in `BUNDLES` in `<app>/bundles.py`, imported
+- **Recipe** — `uv run xtr-recipes recipes:sync` does the *Activate*, *Configure* and *Ignore*
+  steps below: it lists `CacheBundle`, writes `<app>/config/packages/cache.py` with the bundle's
+  own defaults, and ignores `/var/`. There is no environment to write.
+- **Activate** — `CacheBundle: {"all": True}` in `BUNDLES` in `<app>/config/bundles.py`, imported
   from `xtr_cache.bundle`.
 - **Brings along** — the logging and console bundles, when those packages are installed.
-- **Configure** — optional: with no configuration there is one `app` pool on files. Pools,
-  adapters and the stampede lock go in `<app>/config/cache.py`, a `@configure` function
-  returning `CacheConfig` — see [Kernel / bundle](#kernel--bundle).
+- **Configure** — optional: the recipe writes `<app>/config/packages/cache.py` holding the
+  defaults, one `app` pool on files. Pools, adapters and the stampede lock go in that same
+  `@configure` function returning `CacheConfig` — see [Kernel / bundle](#kernel--bundle).
 - **Environment** — nothing required. A DSN given as `env(...)` must be set when the
   application boots: booting checks every pool.
 - **Ignore** — `var/`: files live under `kernel.share_dir`, `var/share` in the project.
-- **Remove** — drop the `BUNDLES` entry, delete `<app>/config/cache.py`, then
-  `uv remove xtr-cache`.
+- **Remove** — drop the `BUNDLES` entry; `uv run xtr-recipes recipes:remove xtr-cache` deletes
+  `<app>/config/packages/cache.py`, unless you edited it, in which case it is moved aside to
+  `cache.py.removed`. Then `uv remove xtr-cache`.
 - **Check** — `debug:bundles` shows `cache` as `listed` and `active`.
 
 ## Kernel / bundle
@@ -290,14 +292,14 @@ not a dependency, and nothing outside `xtr_cache.bundle` needs it — list the b
 pools:
 
 ```python
-# app/bundles.py
+# app/config/bundles.py
 from xtr_cache.bundle import CacheBundle
 
 BUNDLES = {CacheBundle: {"all": True}}
 ```
 
 ```python
-# app/config/cache.py
+# app/config/packages/cache.py
 from xtr_dependency_injection import configure, env
 from xtr_cache.bundle import CacheConfig, PoolConfig
 

{xtr_cache-5.0.1 → xtr_cache-5.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "xtr-cache"
-version = "5.0.1"
+version = "5.2.0"
 description = "Cache pools in memory, in files, in Redis, chained or tag-aware, with stampede protection."
 readme = "README.md"
 requires-python = ">=3.11"

{xtr_cache-5.0.1 → xtr_cache-5.2.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "xtr-cache"
-version = "5.0.1"
+version = "5.2.0"
 description = "Cache pools in memory, in files, in Redis, chained or tag-aware, with stampede protection."
 readme = "README.md"
 requires-python = ">=3.11"

{xtr_cache-5.0.1 → xtr_cache-5.2.0}/src/xtr_cache/.agents/skills/xtr-cache/SKILL.md

@@ -173,20 +173,21 @@ rotation.
 ## Use in an application
 
 `uv run xtr-recipes recipes:sync` applies the recipe shipped with this package: it lists
-`CacheBundle` and ignores `/var/`. That is the steps below a recipe can do; the others it prints
-for you to make.
+`CacheBundle`, writes `<app>/config/packages/cache.py` with the bundle's own defaults, and ignores
+`/var/`. That is the steps below a recipe can do; the others it prints for you to make.
 
 1. **Install** — `uv add xtr-cache xtr-dependency-injection`: the bundle needs the container
    installed beside it, never as an extra. Add `redis` or `sodium` for what you use; install
    xtr-console beside it for the `cache:pool:*` commands, and xtr-logging for a `cache` channel.
-2. **Activate** — `CacheBundle: {"all": True}` in `BUNDLES` in `<app>/bundles.py`, imported from
+2. **Activate** — `CacheBundle: {"all": True}` in `BUNDLES` in `<app>/config/bundles.py`, imported from
    `xtr_cache.bundle`.
 3. **Brings along** — the logging and console bundles, when those packages are installed. With
    logging, a `cache` channel is added and every pool logs there.
-4. **Configure** — optional; with no configuration there is one `app` pool on files:
+4. **Configure** — the recipe writes `<app>/config/packages/cache.py` holding the defaults, one
+   `app` pool on files, and that is where pools and adapters go:
 
    ```python
-   # <app>/config/cache.py
+   # <app>/config/packages/cache.py
    from xtr_dependency_injection import configure, env
 
    from xtr_cache.bundle import CacheConfig, PoolConfig
@@ -241,8 +242,9 @@ for you to make.
 8. **Check** — `debug:bundles` shows `cache` as `listed` and `active`.
    `cache:pool:list`, `cache:pool:clear`, `cache:pool:delete`, `cache:pool:invalidate-tags` and
    `cache:pool:prune` are there once the console bundle is active.
-9. **Remove** — drop the `BUNDLES` entry, delete `<app>/config/cache.py`, then
-   `uv remove xtr-cache`.
+9. **Remove** — drop the `BUNDLES` entry; `uv run xtr-recipes recipes:remove xtr-cache` deletes
+   `<app>/config/packages/cache.py`, unless you edited it, in which case it is moved aside to
+   `cache.py.removed`. Then `uv remove xtr-cache`.
 
 Without a container, hand the commands their pools once and import `xtr_cache.command` before the
 application runs:

xtr_cache-5.2.0/src/xtr_cache/recipe/files/config/cache.py.tmpl

@@ -0,0 +1,36 @@
+"""The cache pools: where cached values are kept, and for how long.
+
+The ``app`` pool exists with no configuration, on files under ``var/share/cache``, and is the
+pool a service asking for a cache with no name gets. Name more pools for values that need a
+lifetime or a backend of their own; a pool given no adapter keeps its values in ``app``'s,
+under a namespace of its own.
+
+```python
+CacheConfig(
+    app=env("CACHE_DSN"),
+    pools={
+        "sessions": PoolConfig(default_lifetime=3600),
+        "catalogue": PoolConfig(adapter=["array", "redis://localhost:6379"], tags=True),
+    },
+)
+```
+"""
+
+from __future__ import annotations
+
+from xtr_cache.bundle import CacheConfig
+from xtr_dependency_injection import configure
+
+__all__ = ["cache"]
+
+
+@configure
+def cache() -> CacheConfig:
+    """The ``app`` pool on the filesystem, and no other pool."""
+    # The app pool's adapter is "filesystem" until it is set: "array" keeps values in this
+    # process alone, and a DSN such as "redis://localhost:6379" shares them between processes.
+    # Several adapters chain, fastest first.
+    #
+    # Every pool's namespace is derived from prefix_seed, the project directory unless set, so
+    # two applications sharing one backend never read each other's values.
+    return CacheConfig()

{xtr_cache-5.0.1 → xtr_cache-5.2.0}/src/xtr_cache/recipe/manifest.toml

@@ -5,10 +5,11 @@
 # "<module>:<class>" = the environments it is listed with, exactly as in BUNDLES.
 "xtr_cache.bundle:CacheBundle" = { all = true }
 
-# No [files]: configuring is optional. With none there is one "app" pool on
-# files, and nothing is opened until a pool is first asked for. An application
-# that wants pools, adapters or a stampede lock of its own writes
-# config/cache.py itself.
+[files]
+# Destination under the application package = template under this recipe.
+# The bundle's own defaults written out — one "app" pool on files, nothing opened
+# until a pool is first asked for — as the place pools and adapters go.
+"config/packages/cache.py" = "files/config/cache.py.tmpl"
 
 # No [env]: nothing is required. A DSN an application gives as env(...) must be
 # set when it boots, because booting checks every pool.