pico-caching 0.1.0__py3-none-any.whl

pico_caching/__init__.py

@@ -0,0 +1,19 @@
+"""pico-caching: declarative caching for the Pico ecosystem.
+
+``@cacheable`` over pico-ioc method interception, with a pluggable
+``CacheBackend`` protocol and a built-in thread-safe in-memory LRU with TTL.
+Auto-discovered by pico-boot; zero-config (no ``cache:`` block required).
+
+Public API:
+    Decorator: cacheable
+    Protocol: CacheBackend
+    Backend: InMemoryCacheBackend
+    Settings: CacheSettings
+"""
+
+from .backend import CacheBackend, InMemoryCacheBackend
+from .config import CacheSettings
+from .decorators import cacheable
+from .interceptor import CacheInterceptor
+
+__all__ = ["cacheable", "CacheBackend", "InMemoryCacheBackend", "CacheSettings", "CacheInterceptor"]

pico_caching/_version.py

@@ -0,0 +1 @@
+__version__ = '0.1.0'

pico_caching/backend.py

@@ -0,0 +1,59 @@
+"""Cache backend protocol and the built-in in-memory LRU backend."""
+
+import threading
+import time
+from collections import OrderedDict
+from typing import Any, Protocol, Tuple, runtime_checkable
+
+from pico_ioc import component
+
+from .config import CacheSettings
+
+_MISS = object()
+
+
+@runtime_checkable
+class CacheBackend(Protocol):
+    """Implement as a ``@component`` to replace the in-memory backend."""
+
+    def get(self, key: str) -> Tuple[bool, Any]: ...
+    def set(self, key: str, value: Any, ttl_seconds: float) -> None: ...
+    def delete(self, key: str) -> None: ...
+    def clear(self) -> None: ...
+
+
+@component
+class InMemoryCacheBackend:
+    """Thread-safe LRU with per-entry TTL (``time.monotonic`` based)."""
+
+    def __init__(self, settings: CacheSettings):
+        self._max = settings.max_entries
+        self._data: OrderedDict[str, Tuple[float, Any]] = OrderedDict()
+        self._lock = threading.Lock()
+
+    def get(self, key: str) -> Tuple[bool, Any]:
+        with self._lock:
+            item = self._data.get(key, _MISS)
+            if item is _MISS:
+                return False, None
+            expires_at, value = item
+            if time.monotonic() >= expires_at:
+                del self._data[key]
+                return False, None
+            self._data.move_to_end(key)
+            return True, value
+
+    def set(self, key: str, value: Any, ttl_seconds: float) -> None:
+        with self._lock:
+            self._data[key] = (time.monotonic() + ttl_seconds, value)
+            self._data.move_to_end(key)
+            while len(self._data) > self._max:
+                self._data.popitem(last=False)
+
+    def delete(self, key: str) -> None:
+        with self._lock:
+            self._data.pop(key, None)
+
+    def clear(self) -> None:
+        with self._lock:
+            self._data.clear()

pico_caching/config.py

@@ -0,0 +1,15 @@
+"""Settings for pico-caching (prefix ``cache``, zero-config)."""
+
+from dataclasses import dataclass
+
+from pico_ioc import configured
+
+
+@configured(target="self", prefix="cache", mapping="tree")
+@dataclass
+class CacheSettings:
+    """``enabled: false`` makes ``@cacheable`` a pass-through."""
+
+    enabled: bool = True
+    default_ttl_seconds: float = 300.0
+    max_entries: int = 1024

pico_caching/decorators.py

@@ -0,0 +1,32 @@
+"""``@cacheable`` marker: stores the policy and attaches the interceptor."""
+
+from typing import Any, Callable
+
+CACHE_META = "_pico_caching_meta"
+
+
+def cacheable(
+    _func: Callable | None = None,
+    *,
+    ttl_seconds: float | None = None,
+    key: Callable[..., str] | None = None,
+):
+    """Cache the method's return value. Sync or async; async methods cache
+    the awaited result, never the coroutine. ``key(*args, **kwargs)``
+    overrides the default repr-based key; ``ttl_seconds`` overrides
+    ``cache.default_ttl_seconds``."""
+
+    def dec(fn):
+        setattr(fn, CACHE_META, {"ttl_seconds": ttl_seconds, "key": key})
+        from pico_ioc import intercepted_by
+
+        from .interceptor import CacheInterceptor
+
+        return intercepted_by(CacheInterceptor)(fn)
+
+    return dec(_func) if callable(_func) else dec
+
+
+def _meta(ctx: Any) -> dict:
+    fn = getattr(ctx.cls, ctx.name, None)
+    return getattr(fn, CACHE_META, {})

pico_caching/interceptor.py

@@ -0,0 +1,51 @@
+"""Cache interceptor: get-or-compute through the selected backend."""
+
+import inspect
+from typing import Any, Callable, List
+
+from pico_ioc import MethodCtx, component
+
+from .backend import CacheBackend, InMemoryCacheBackend
+from .config import CacheSettings
+from .decorators import _meta
+
+
+def _default_key(ctx: MethodCtx) -> str:
+    kw = ",".join(f"{k}={v!r}" for k, v in sorted(ctx.kwargs.items()))
+    return f"{ctx.cls.__module__}.{ctx.cls.__qualname__}.{ctx.name}({','.join(map(repr, ctx.args))};{kw})"
+
+
+@component(scope="singleton")
+class CacheInterceptor:
+    """Uses the first user-provided ``CacheBackend``; falls back to the
+    built-in in-memory LRU."""
+
+    def __init__(self, settings: CacheSettings, backends: List[CacheBackend]):
+        self.settings = settings
+        custom = [b for b in backends if not isinstance(b, InMemoryCacheBackend)]
+        fallback = [b for b in backends if isinstance(b, InMemoryCacheBackend)]
+        self.backend = (custom or fallback)[0]
+
+    def invoke(self, ctx: MethodCtx, call_next: Callable[[MethodCtx], Any]) -> Any:
+        meta = _meta(ctx)
+        if not self.settings.enabled or not meta:
+            return call_next(ctx)
+        key_fn = meta["key"]
+        key = key_fn(*ctx.args, **ctx.kwargs) if key_fn else _default_key(ctx)
+        ttl = meta["ttl_seconds"] if meta["ttl_seconds"] is not None else self.settings.default_ttl_seconds
+        if inspect.iscoroutinefunction(ctx.method):
+            return self._get_or_compute_async(ctx, call_next, key, ttl)
+        hit, value = self.backend.get(key)
+        if hit:
+            return value
+        value = call_next(ctx)
+        self.backend.set(key, value, ttl)
+        return value
+
+    async def _get_or_compute_async(self, ctx, call_next, key: str, ttl: float):
+        hit, value = self.backend.get(key)
+        if hit:
+            return value
+        value = await call_next(ctx)
+        self.backend.set(key, value, ttl)
+        return value

pico_caching-0.1.0.dist-info/METADATA

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: pico-caching
+Version: 0.1.0
+Summary: Declarative caching for the Pico ecosystem: @cacheable AOP with pluggable backends.
+Author-email: David Perez Cabrera <dperezcabrera@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2025 David Pérez Cabrera
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/dperezcabrera/pico-caching
+Project-URL: Documentation, https://dperezcabrera.github.io/pico-caching/
+Project-URL: Repository, https://github.com/dperezcabrera/pico-caching
+Project-URL: Changelog, https://github.com/dperezcabrera/pico-caching/blob/main/CHANGELOG.md
+Project-URL: Issue Tracker, https://github.com/dperezcabrera/pico-caching/issues
+Keywords: cache,cacheable,lru,ttl,aop,ioc,spring boot
+Classifier: Development Status :: 4 - Beta
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pico-ioc>=2.2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: pytest-cov>=5; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# 📦 pico-caching
+
+[![PyPI](https://img.shields.io/pypi/v/pico-caching.svg)](https://pypi.org/project/pico-caching/)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/dperezcabrera/pico-caching)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+![CI (tox matrix)](https://github.com/dperezcabrera/pico-caching/actions/workflows/ci.yml/badge.svg)
+[![codecov](https://codecov.io/gh/dperezcabrera/pico-caching/branch/main/graph/badge.svg)](https://codecov.io/gh/dperezcabrera/pico-caching)
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=dperezcabrera_pico-caching&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=dperezcabrera_pico-caching)
+[![Duplicated Lines (%)](https://sonarcloud.io/api/project_badges/measure?project=dperezcabrera_pico-caching&metric=duplicated_lines_density)](https://sonarcloud.io/summary/new_code?id=dperezcabrera_pico-caching)
+[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=dperezcabrera_pico-caching&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=dperezcabrera_pico-caching)
+[![PyPI Downloads](https://img.shields.io/pypi/dm/pico-caching)](https://pypi.org/project/pico-caching/)
+[![Docs](https://img.shields.io/badge/Docs-pico--caching-blue?style=flat&logo=readthedocs&logoColor=white)](https://dperezcabrera.github.io/pico-caching/)
+[![Interactive Lab](https://img.shields.io/badge/Learn-online-green?style=flat&logo=python&logoColor=white)](https://dperezcabrera.github.io/pico-learn/)
+
+Declarative **method caching** for the [Pico](https://github.com/dperezcabrera/pico-ioc) ecosystem: `@cacheable` over pico-ioc method interception, pluggable backends, auto-discovered by [pico-boot](https://github.com/dperezcabrera/pico-boot). Zero-config.
+
+## Install
+
+```bash
+pip install pico-caching
+```
+
+## Use
+
+```python
+from pico_ioc import component
+from pico_caching import cacheable
+
+@component
+class UserRepo:
+    @cacheable(ttl_seconds=60)
+    async def find(self, user_id: int): ...
+
+    @cacheable(key=lambda q: f"search:{q}")
+    def search(self, q: str): ...
+```
+
+Sync and async (the awaited **result** is cached, never the coroutine). Default backend: thread-safe in-memory LRU with per-entry TTL (`cache.max_entries`, `cache.default_ttl_seconds`). Bring your own backend by implementing the `CacheBackend` protocol as a `@component` — it replaces the built-in automatically.
+
+```yaml
+# application.yaml (optional)
+cache:
+  default_ttl_seconds: 300
+  max_entries: 1024
+```
+
+Skipped for now: `@cache_evict` and a Redis backend — planned once real usage asks for them.
+
+## Documentation
+
+Full docs at **[dperezcabrera.github.io/pico-caching](https://dperezcabrera.github.io/pico-caching/)**.
+
+## License
+
+MIT

pico_caching-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+pico_caching/__init__.py,sha256=pylGqOfjMh-yU1d2ECsKwSOaFM9rwKONFn_vWCtKUhc,680
+pico_caching/_version.py,sha256=IMjkMO3twhQzluVTo8Z6rE7Eg-9U79_LGKMcsWLKBkY,22
+pico_caching/backend.py,sha256=46nATdKrJH2bfOMPElvvdmfa2rH2-gTcHUVXBtKu9sA,1824
+pico_caching/config.py,sha256=GoCmJhrTGPT51U-FvS_JnUY8pfl-DX3inkNtLuWi_8k,385
+pico_caching/decorators.py,sha256=2F0t-D76_6PYafgopiCtTM8TUiKKmfMhUZH07DmdUR0,943
+pico_caching/interceptor.py,sha256=zpYavThTukbTXk0-FfnCz_d1kOvM0BFq1m1Dk6kZDCc,1970
+pico_caching/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pico_caching-0.1.0.dist-info/licenses/LICENSE,sha256=N1_nOvHTM6BobYnOTNXiQkroDqCEi6EzfGBv8lWtyZ0,1077
+pico_caching-0.1.0.dist-info/METADATA,sha256=1BkZd8DYNervaVzGR75ztxTyGNdo9oKz833sS7Xw3k4,5601
+pico_caching-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+pico_caching-0.1.0.dist-info/entry_points.txt,sha256=3R_ryGuGL5r2wdkRS1EQh5WyJSEkIWGyICxMS8AxPrM,48
+pico_caching-0.1.0.dist-info/scm_file_list.json,sha256=GaoZRveD_DMMpuE-cLdGbm_Fp2NhoIfArxSjHpXsWF0,1303
+pico_caching-0.1.0.dist-info/scm_version.json,sha256=wEnomyEM9-j3rRRc8h5W7_YItJn4L6nA36ZlEDcuigI,160
+pico_caching-0.1.0.dist-info/top_level.txt,sha256=M1jez3sLSGVJ5r_G3HfafvcQ_3wKJj2YRSk-ver4iLg,13
+pico_caching-0.1.0.dist-info/RECORD,,

pico_caching-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pico_caching-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[pico_boot.modules]
+pico_caching = pico_caching

pico_caching-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 David Pérez Cabrera
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pico_caching-0.1.0.dist-info/scm_file_list.json

@@ -0,0 +1,51 @@
+{
+  "files": [
+    ".coveragerc",
+    "README.md",
+    "Makefile",
+    "tox.ini",
+    "LICENSE",
+    "pyproject.toml",
+    "SECURITY.md",
+    "mkdocs.yml",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "AGENTS.md",
+    "CLAUDE.md",
+    "MANIFEST.in",
+    "Dockerfile.test",
+    ".gitignore",
+    "CODE_OF_CONDUCT.md",
+    "docs/getting-started.md",
+    "docs/requirements.txt",
+    "docs/LEARN.md",
+    "docs/CHANGELOG.md",
+    "docs/faq.md",
+    "docs/troubleshooting.md",
+    "docs/skills.md",
+    "docs/index.md",
+    "docs/hooks.py",
+    "docs/architecture.md",
+    "docs/stylesheets/extra.css",
+    "docs/javascripts/extra.js",
+    "docs/reference/api.md",
+    "docs/reference/index.md",
+    "src/pico_caching/interceptor.py",
+    "src/pico_caching/py.typed",
+    "src/pico_caching/__init__.py",
+    "src/pico_caching/config.py",
+    "src/pico_caching/decorators.py",
+    "src/pico_caching/backend.py",
+    "tests/__init__.py",
+    "tests/conftest.py",
+    "tests/test_cache.py",
+    ".github/PULL_REQUEST_TEMPLATE.md",
+    ".github/dependabot.yml",
+    ".github/ISSUE_TEMPLATE/bug_report.yml",
+    ".github/ISSUE_TEMPLATE/feature_request.yml",
+    ".github/workflows/docs.yml",
+    ".github/workflows/codeql.yml",
+    ".github/workflows/ci.yml",
+    ".github/workflows/publish-to-pypi.yml"
+  ]
+}

pico_caching-0.1.0.dist-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "0.1.0",
+  "distance": 0,
+  "node": "g0371d292c577375653beb97ef06543a62be28345",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-07-04"
+}

pico_caching-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pico_caching