emboss 0.1.0__py3-none-any.whl

emboss/__init__.py

@@ -0,0 +1,35 @@
+"""emboss — On-Disk Input-keyed Cache.
+
+Disk-backed memoization built on `diskcache`, with auto-detection of
+pydantic v2 `BaseModel` return types (encoded via `model_dump`, decoded
+via `model_validate`) so models defined in `__main__` round-trip across
+script invocations.
+
+Usage::
+
+    import diskcache
+    from emboss import cached
+
+    cache = diskcache.Cache("/tmp/my-cache")
+
+    @cached(cache)
+    def expensive(url: str) -> dict:
+        return requests.get(url).json()
+
+    # pydantic BaseModel returns are auto-encoded / decoded
+    from pydantic import BaseModel
+
+    class User(BaseModel):
+        name: str
+
+    @cached(cache)
+    def get_user(uid: int) -> User | None:
+        return User.model_validate(requests.get(f"/users/{uid}").json())
+
+See README.md for the full feature list.
+"""
+
+from emboss._cached import cached, safe_jsonable_encoder
+
+__version__ = "0.1.0"
+__all__ = ["cached", "safe_jsonable_encoder"]

emboss/_cached.py

@@ -0,0 +1,187 @@
+"""Internal: `@cached` decorator implementation. Public API lives in `emboss.__init__`."""
+
+from __future__ import annotations
+
+import asyncio
+import functools
+import hashlib
+import inspect
+import json
+import logging
+import types
+import typing
+from collections.abc import Callable
+from typing import Any, TypeVar, Union
+
+import diskcache
+
+try:
+    from pydantic import BaseModel
+except ImportError:  # pragma: no cover — pydantic is optional for callers
+    BaseModel = None  # type: ignore[assignment]
+
+T = TypeVar("T")
+logger = logging.getLogger(__name__)
+
+# Sentinel for "key absent from cache" — lets None be a valid cached value.
+_MISSING = object()
+
+
+def safe_jsonable_encoder(obj: Any) -> Any:
+    """Convert objects to JSON-serializable forms for cache keys."""
+    if obj is None or isinstance(obj, (bool, int, float, str)):
+        return obj
+    if isinstance(obj, (list, tuple)):
+        return [safe_jsonable_encoder(item) for item in obj]
+    if isinstance(obj, dict):
+        return {str(k): safe_jsonable_encoder(v) for k, v in obj.items()}
+    if isinstance(obj, set):
+        return sorted([safe_jsonable_encoder(item) for item in obj])
+    if isinstance(obj, bytes):
+        return obj.decode("utf-8", errors="ignore")
+    try:
+        import arrow
+
+        if isinstance(obj, arrow.Arrow):
+            return obj.isoformat()
+    except ImportError:
+        pass
+    try:
+        from datetime import date, datetime, time
+
+        if isinstance(obj, (datetime, date, time)):
+            return obj.isoformat()
+    except ImportError:
+        pass
+    try:
+        from pathlib import Path
+
+        if isinstance(obj, Path):
+            return str(obj)
+    except ImportError:
+        pass
+    if BaseModel is not None and isinstance(obj, BaseModel):
+        return obj.model_dump()
+    if hasattr(obj, "__dict__"):
+        return safe_jsonable_encoder(obj.__dict__)
+    return str(obj)
+
+
+def _is_basemodel_class(cls: Any) -> bool:
+    return BaseModel is not None and isinstance(cls, type) and issubclass(cls, BaseModel)
+
+
+def _model_info(annotation: Any) -> tuple[type | None, str]:
+    """Return `(Model class, container)` extracted from a return annotation.
+
+    `container` is one of `"none"` (single value), `"list"`, or `"dict"`.
+    Returns `(None, "none")` when no BaseModel is in play (decorator falls back
+    to pass-through encode/decode).
+    """
+    if BaseModel is None or annotation is inspect.Parameter.empty or annotation is None:
+        return None, "none"
+    if _is_basemodel_class(annotation):
+        return annotation, "none"
+
+    origin = typing.get_origin(annotation)
+    if origin in (Union, types.UnionType):
+        for arg in typing.get_args(annotation):
+            if _is_basemodel_class(arg):
+                return arg, "none"
+        return None, "none"
+    if origin is list:
+        args = typing.get_args(annotation)
+        if args and _is_basemodel_class(args[0]):
+            return args[0], "list"
+    if origin is dict:
+        args = typing.get_args(annotation)
+        if len(args) == 2 and _is_basemodel_class(args[1]):
+            return args[1], "dict"
+    return None, "none"
+
+
+def _encode(value: Any, model_cls: type | None, container: str) -> Any:
+    """Convert pydantic models to plain dicts before pickling."""
+    if value is None or model_cls is None:
+        return value
+    if container == "list":
+        return [v.model_dump() if isinstance(v, model_cls) else v for v in value]
+    if container == "dict":
+        return {k: (v.model_dump() if isinstance(v, model_cls) else v) for k, v in value.items()}
+    if isinstance(value, model_cls):
+        return value.model_dump()
+    return value
+
+
+def _decode(value: Any, model_cls: type | None, container: str) -> Any:
+    """Rehydrate dicts into pydantic models on cache hit."""
+    if value is None or model_cls is None:
+        return value
+    if container == "list":
+        return [model_cls.model_validate(v) if isinstance(v, dict) else v for v in value]
+    if container == "dict":
+        return {k: (model_cls.model_validate(v) if isinstance(v, dict) else v) for k, v in value.items()}
+    if isinstance(value, dict):
+        return model_cls.model_validate(value)
+    return value
+
+
+def cached(
+    cache: diskcache.Cache | None = None,
+) -> Callable[[Callable[..., T]], Callable[..., T]]:
+    """Disk-backed memoization decorator.
+
+    Detects `BaseModel` / `list[Model]` / `dict[str, Model]` return annotations
+    and stores them as dicts (rehydrated on read) so model classes defined in
+    `__main__` round-trip across script invocations.
+    """
+    if cache is None:
+        cache = diskcache.Cache()
+
+    def decorator(func: Callable[..., T]) -> Callable[..., T]:
+        func_source = inspect.getsource(func)
+        func_hash = hashlib.md5(func_source.encode()).hexdigest()
+        try:
+            return_anno = inspect.signature(func).return_annotation
+        except (TypeError, ValueError):
+            return_anno = inspect.Parameter.empty
+        model_cls, container = _model_info(return_anno)
+
+        @functools.wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> T:
+            json_args = [safe_jsonable_encoder(arg) for arg in args]
+            json_kwargs = {k: safe_jsonable_encoder(v) for k, v in kwargs.items()}
+            arg_hash = hashlib.md5(
+                f"{json.dumps(json_args)}{json.dumps(json_kwargs)}".encode()
+            ).hexdigest()
+            key: str = hashlib.md5(
+                f"{func.__name__}{func_hash}{arg_hash}".encode()
+            ).hexdigest()
+
+            raw = cache.get(key, default=_MISSING)
+            if raw is not _MISSING:
+                decoded = _decode(raw, model_cls, container)
+                if asyncio.iscoroutinefunction(func):
+
+                    async def return_cached():
+                        return decoded
+
+                    return return_cached()  # type: ignore[return-value]
+                return decoded  # type: ignore[return-value]
+
+            if asyncio.iscoroutinefunction(func):
+
+                async def execute():
+                    result = await func(*args, **kwargs)  # type: ignore[misc]
+                    cache.set(key, _encode(result, model_cls, container))
+                    return result
+
+                return execute()  # type: ignore[return-value]
+
+            result = func(*args, **kwargs)
+            cache.set(key, _encode(result, model_cls, container))
+            return result
+
+        return wrapper
+
+    return decorator

emboss-0.1.0.dist-info/METADATA

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: emboss
+Version: 0.1.0
+Summary: On-Disk Input-keyed Cache — disk-backed memoization with pydantic-aware encoding
+Author-email: Daniel Hails <emboss@hails.info>
+Project-URL: Homepage, https://github.com/DJRHails/emboss
+Project-URL: Bug Tracker, https://github.com/DJRHails/emboss/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: diskcache>=5
+Provides-Extra: pydantic
+Requires-Dist: pydantic>=2; extra == "pydantic"
+Dynamic: license-file
+
+# emboss
+
+**O**n-**D**isk **I**nput-keyed **C**ache — disk-backed memoization with pydantic-aware encoding.
+
+Version: 0.1.0
+
+```bash
+pip install emboss              # core (just diskcache)
+pip install emboss[pydantic]    # + pydantic v2 BaseModel support
+```
+
+## Why
+
+`functools.lru_cache` is per-process. `diskcache` survives invocations but pickles values as-is — which breaks the moment your cached return type is a pydantic `BaseModel` defined in `__main__` (the new process can't unpickle `__main__.MyModel`). `emboss` fixes that by detecting BaseModel return annotations and converting to/from plain dicts at the cache boundary.
+
+Plus: a `None`-aware sentinel so functions returning `None` actually cache instead of re-running every call.
+
+## Quick start
+
+```python
+import diskcache
+from emboss import cached
+
+cache = diskcache.Cache("/tmp/my-cache")
+
+@cached(cache)
+def fetch(url: str) -> dict:
+    import requests
+    return requests.get(url).json()
+
+fetch("https://api.example.com/users/1")  # network
+fetch("https://api.example.com/users/1")  # cached, no network
+```
+
+## Pydantic BaseModel returns
+
+`emboss` reads the function's return type annotation. If it sees a `BaseModel`, `list[BaseModel]`, `dict[str, BaseModel]`, or `BaseModel | None`, it serialises via `model.model_dump()` before pickling and rehydrates via `Model.model_validate(...)` on read. The cached value on disk is a plain dict — round-trips cleanly across process boundaries, even for models defined in `__main__`.
+
+```python
+from pydantic import BaseModel
+
+class User(BaseModel):
+    id: int
+    name: str
+
+@cached(cache)
+def get_user(uid: int) -> User | None:
+    ...
+
+@cached(cache)
+def list_users() -> list[User]:
+    ...
+
+@cached(cache)
+def users_by_id() -> dict[str, User]:
+    ...
+```
+
+Functions returning non-BaseModel types continue to pickle as-is — fully backward-compatible.
+
+## None caching
+
+```python
+@cached(cache)
+def lookup(query: str) -> str | None:
+    return external_api(query)
+
+lookup("missing")  # returns None, cached
+lookup("missing")  # returns cached None, no re-run
+```
+
+The previous behaviour (skip-cache-on-None) is replaced by a `_MISSING` sentinel internally so `None` is a valid cached value.
+
+## Cache key
+
+Arguments are converted via `safe_jsonable_encoder` (recursive JSON-friendly conversion handling sets, bytes, dates, `Path`, BaseModel, and objects with `__dict__`), then hashed with the function source + name. Re-decorating the same function body → same key; changing the function body → new key (transparent cache invalidation on code change).
+
+## Async support
+
+```python
+@cached(cache)
+async def fetch_async(url: str) -> dict:
+    async with httpx.AsyncClient() as c:
+        return (await c.get(url)).json()
+```
+
+Cache hits return a fresh awaitable wrapping the cached value, so the call site keeps `await`-ing as normal.
+
+## Daily-rolling caches
+
+The `diskcache.Cache` instance you pass is yours to manage. A common pattern for "expire daily" without thinking about it:
+
+```python
+from datetime import date
+import diskcache
+cache = diskcache.Cache(f"/tmp/my-cache-{date.today()}")
+```
+
+Each new day → new dir → effectively fresh cache. Old dirs land in `/tmp` and get reaped by the OS.
+
+## License
+
+MIT.

emboss-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+emboss/__init__.py,sha256=P-gRsT4MWIoeWW9KMeb3_t6NmTJlqmSQxtZCFrQQWeM,930
+emboss/_cached.py,sha256=x-99bi6j7_hqXorTeMy3g4u1b94mG5_H8H6f9oQ3r1Q,6504
+emboss-0.1.0.dist-info/licenses/LICENSE,sha256=RjexM-UPby8fRPlfzBjGcbGkb-awdO-A5pngqiggAAw,1069
+tests/test_cached.py,sha256=DtkCO6IRhaZH6E8j_eWDF6p_IzmyzCsnfADwdGQUe0k,2195
+emboss-0.1.0.dist-info/METADATA,sha256=xaGH2YeSre0bLFD-CxtZiisM0wHj9ddYTVv9KQT40Ks,3773
+emboss-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+emboss-0.1.0.dist-info/top_level.txt,sha256=d5kCPMCoP_GksIdWZk4T9oTU6NiPm2Z6cWuJgyHY3Yo,13
+emboss-0.1.0.dist-info/RECORD,,

emboss-0.1.0.dist-info/WHEEL

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

emboss-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Hails
+
+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.

emboss-0.1.0.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+emboss
+tests

tests/test_cached.py

@@ -0,0 +1,106 @@
+"""End-to-end round-trip tests for emboss.cached."""
+
+from __future__ import annotations
+
+import diskcache
+import pytest
+from pydantic import BaseModel
+
+from emboss import cached
+
+
+class M(BaseModel):
+    name: str
+    n: int = 0
+
+
+@pytest.fixture
+def cache(tmp_path):
+    c = diskcache.Cache(str(tmp_path / "cache"))
+    yield c
+    c.close()
+
+
+def test_plain_dict_round_trip(cache):
+    calls = {"n": 0}
+
+    @cached(cache)
+    def f(x: int) -> dict:
+        calls["n"] += 1
+        return {"value": x * 2}
+
+    assert f(3) == {"value": 6}
+    assert f(3) == {"value": 6}
+    assert calls["n"] == 1, "second call should be cached"
+
+
+def test_basemodel_round_trip(cache):
+    calls = {"n": 0}
+
+    @cached(cache)
+    def f() -> M:
+        calls["n"] += 1
+        return M(name="solo", n=1)
+
+    r1 = f()
+    r2 = f()
+    assert isinstance(r1, M) and isinstance(r2, M)
+    assert r1 == r2
+    assert calls["n"] == 1
+
+
+def test_list_of_basemodel_round_trip(cache):
+    calls = {"n": 0}
+
+    @cached(cache)
+    def f() -> list[M]:
+        calls["n"] += 1
+        return [M(name="a"), M(name="b", n=2)]
+
+    assert f() == f()
+    assert calls["n"] == 1
+    # All elements are still pydantic models, not dicts
+    assert all(isinstance(m, M) for m in f())
+
+
+def test_dict_of_basemodel_round_trip(cache):
+    calls = {"n": 0}
+
+    @cached(cache)
+    def f() -> dict[str, M]:
+        calls["n"] += 1
+        return {"x": M(name="x", n=9)}
+
+    assert f() == f()
+    assert calls["n"] == 1
+    assert isinstance(f()["x"], M)
+
+
+def test_optional_basemodel_none_caches(cache):
+    calls = {"n": 0}
+
+    @cached(cache)
+    def f(x: int) -> M | None:
+        calls["n"] += 1
+        return None if x < 0 else M(name="opt", n=x)
+
+    assert f(-1) is None
+    assert f(-1) is None
+    assert f(5).n == 5
+    assert f(5).n == 5
+    # 2 distinct keys (one for -1, one for 5), each computed once
+    assert calls["n"] == 2
+
+
+def test_none_return_caches(cache):
+    """Pre-emboss behaviour skipped caching None; we want None cached too."""
+    calls = {"n": 0}
+
+    @cached(cache)
+    def f(x: str) -> str | None:
+        calls["n"] += 1
+        return None
+
+    f("any")
+    f("any")
+    assert calls["n"] == 1