pycacheable 0.1.0__py3-none-any.whl

pycacheable/backend_memory.py

@@ -0,0 +1,48 @@
+import pickle
+import threading
+import time
+from typing import Any, Dict, Optional, Tuple, OrderedDict
+
+from src.pycacheable.cache_base import CacheBase
+
+
+class InMemoryCache(CacheBase):
+    def __init__(self, max_entries: int = 1024):
+        self._store: "OrderedDict[str, Tuple[float, bytes]]" = OrderedDict()
+        self._lock = threading.RLock()
+        self._max_entries = max_entries
+
+    def get(self, key: str) -> Tuple[bool, Any, str]:
+        with self._lock:
+            entry = self._store.get(key)
+            now = time.time()
+            if not entry:
+                return False, None, "MISS"
+            expire_at, payload = entry
+            if expire_at and expire_at < now:
+                self._store.pop(key, None)
+                return False, None, "EXPIRE"
+
+            self._store.move_to_end(key)
+            return True, pickle.loads(payload), "HIT"
+
+    def set(self, key: str, value: Any, ttl_seconds: Optional[int]):
+        with self._lock:
+            expire_at = (time.time() + ttl_seconds) if ttl_seconds else 0.0
+            payload = pickle.dumps(value, protocol=pickle.HIGHEST_PROTOCOL)
+            self._store[key] = (expire_at, payload)
+            self._store.move_to_end(key)
+            while len(self._store) > self._max_entries:
+                self._store.popitem(last=False)
+
+    def clear(self):
+        with self._lock:
+            self._store.clear()
+
+    def info(self) -> Dict[str, Any]:
+        with self._lock:
+            return {
+                "backend": "InMemoryCache",
+                "size": len(self._store),
+                "max_entries": self._max_entries,
+            }

pycacheable/backend_sqlite.py

@@ -0,0 +1,70 @@
+import os
+import pickle
+import sqlite3
+import threading
+import time
+from typing import Any, Dict, Optional, Tuple
+
+from src.pycacheable.cache_base import CacheBase
+
+
+class SQLiteCache(CacheBase):
+    def __init__(self, path: str):
+        self._path = path
+        self._lock = threading.RLock()
+        os.makedirs(os.path.dirname(os.path.abspath(path)), exist_ok=True)
+
+        with self._conn() as conn:
+            conn.execute("""
+                         CREATE TABLE IF NOT EXISTS cache
+                         (
+                             k
+                             TEXT
+                             PRIMARY
+                             KEY,
+                             expire_at
+                             REAL,
+                             v
+                             BLOB
+                         )
+                         """)
+
+            conn.execute("PRAGMA journal_mode=WAL;")
+
+    def _conn(self):
+        return sqlite3.connect(self._path, timeout=30, isolation_level=None)
+
+    def get(self, key: str) -> Tuple[bool, Any, str]:
+        with self._lock, self._conn() as conn:
+            row = conn.execute("SELECT expire_at, v FROM cache WHERE k=?", (key,)).fetchone()
+            now = time.time()
+            if not row:
+                return False, None, "MISS"
+            expire_at, blob = row
+            if expire_at and expire_at < now:
+                conn.execute("DELETE FROM cache WHERE k=?", (key,))
+                return False, None, "EXPIRE"
+            return True, pickle.loads(blob), "HIT"
+
+    def set(self, key: str, value: Any, ttl_seconds: Optional[int]):
+        expire_at = (time.time() + ttl_seconds) if ttl_seconds else 0.0
+        blob = pickle.dumps(value, protocol=pickle.HIGHEST_PROTOCOL)
+        with self._lock, self._conn() as conn:
+            conn.execute(
+                "REPLACE INTO cache (k, expire_at, v) VALUES (?, ?, ?)",
+                (key, expire_at, sqlite3.Binary(blob))
+            )
+
+    def clear(self):
+        with self._lock, self._conn() as conn:
+            conn.execute("DELETE FROM cache")
+
+    def info(self) -> Dict[str, Any]:
+        with self._lock, self._conn() as conn:
+            row = conn.execute("SELECT COUNT(*) FROM cache").fetchone()
+            size = int(row[0]) if row else 0
+            return {
+                "backend": "SQLiteCache",
+                "size": size,
+                "path": self._path,
+            }

pycacheable/cache_base.py

@@ -0,0 +1,19 @@
+from abc import ABC, abstractmethod
+
+
+class CacheBase(ABC):
+    @abstractmethod
+    def get(self, **args):
+        pass
+
+    @abstractmethod
+    def set(self, **args):
+        pass
+
+    @abstractmethod
+    def clear(self, **args):
+        pass
+
+    @abstractmethod
+    def info(self, **args):
+        pass

pycacheable/cacheable.py

@@ -0,0 +1,53 @@
+import functools
+from typing import Any, Callable, Dict, Optional, Tuple
+
+from src.pycacheable.backend_sqlite import SQLiteCache
+from src.pycacheable.hashing import _build_key_from_call
+
+
+def cacheable(
+        ttl: Optional[int] = 300,
+        backend: Optional[object] = None,
+        *,
+        include_self: bool = False,
+        key_fn: Optional[Callable[[Callable, Tuple[Any, ...], Dict[str, Any]], str]] = None,
+        logger: Optional[Callable[[str], None]] = None,
+        backend_factory: Optional[Callable[..., object]] = None,
+):
+    default_backend = backend or SQLiteCache(path="./.cache/db.sqlite3")
+
+    def decorator(func: Callable):
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            be = getattr(wrapper, "cache_backend", None)
+            if be is None and backend_factory is not None:
+                try:
+                    be = backend_factory(*args, **kwargs)
+                except TypeError:
+                    be = backend_factory(args[0]) if args else None
+            if be is None:
+                be = default_backend
+
+            key = (key_fn(func, args, kwargs)
+                   if key_fn else _build_key_from_call(func, args, kwargs, include_self))
+
+            hit, value, status = be.get(key)
+            if hit:
+                if logger: logger(f"[CACHE {status}] {func.__qualname__} {key[:10]}…")
+                return value
+
+            if logger: logger(f"[CACHE {status}] {func.__qualname__} {key[:10]}… -> calling")
+            result = func(*args, **kwargs)
+            try:
+                be.set(key, result, ttl)
+                if logger: logger(f"[CACHE SET] {func.__qualname__} {key[:10]}… ttl={ttl}")
+            except Exception as e:
+                if logger: logger(f"[CACHE ERROR SET] {func.__qualname__}: {e}")
+            return result
+
+        wrapper.cache_backend = default_backend
+        wrapper.cache_clear = lambda: wrapper.cache_backend.clear()
+        wrapper.cache_info = lambda: wrapper.cache_backend.info()
+        return wrapper
+
+    return decorator

pycacheable/hashing.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+import datetime as dt
+import decimal
+import enum
+import hashlib
+import inspect
+import json
+import pathlib
+import pickle
+import uuid
+from typing import Any, Mapping, Iterable
+from typing import Callable, Dict, Tuple
+
+
+def _to_canonical(obj: Any) -> Any:
+    if obj is None or isinstance(obj, (bool, int, float, str)):
+        return obj
+
+    if isinstance(obj, decimal.Decimal):
+        return str(obj)
+    if isinstance(obj, uuid.UUID):
+        return str(obj)
+
+    if isinstance(obj, (dt.datetime, dt.date, dt.time)):
+        if isinstance(obj, dt.datetime):
+            if obj.tzinfo is None:
+                obj = obj.replace(tzinfo=dt.timezone.utc)  # padroniza se vier naive
+            return obj.astimezone(dt.timezone.utc).isoformat(timespec="microseconds")
+        if isinstance(obj, dt.date):
+            return obj.isoformat()
+        if isinstance(obj, dt.time):
+            if obj.tzinfo is None:
+                obj = obj.replace(tzinfo=dt.timezone.utc)
+            return obj.isoformat(timespec="microseconds")
+
+    if isinstance(obj, pathlib.Path):
+        return str(obj)
+    if isinstance(obj, enum.Enum):
+        return obj.value if isinstance(obj.value, (str, int, float, bool)) else obj.name
+
+    if isinstance(obj, set):
+        return sorted(_to_canonical(x) for x in obj)
+    if isinstance(obj, tuple):
+        return ["__tuple__", *(_to_canonical(x) for x in obj)]  # preserva semântica
+
+    if isinstance(obj, Mapping):
+        return {str(k): _to_canonical(v) for k, v in sorted(obj.items(), key=lambda kv: str(kv[0]))}
+
+    if isinstance(obj, Iterable) and not isinstance(obj, (str, bytes, bytearray)):
+        return [_to_canonical(x) for x in obj]
+
+    if isinstance(obj, (bytes, bytearray, memoryview)):
+        return {"__bytes__": bytes(obj).hex()}
+
+    try:
+        import numpy as np  # type: ignore
+        if isinstance(obj, (np.generic,)):  # np.int64, np.float32 etc.
+            return obj.item()
+        if isinstance(obj, (np.ndarray,)):
+            return {"__ndarray__": obj.tolist(), "dtype": str(obj.dtype), "shape": obj.shape}
+    except Exception:
+        pass
+
+    return {"__type__": type(obj).__name__, "__repr__": repr(obj)}
+
+
+def _json_canonical_dumps(payload: Any) -> bytes:
+    canon = _to_canonical(payload)
+    return json.dumps(canon, ensure_ascii=False, sort_keys=True, separators=(",", ":")).encode("utf-8")
+
+
+class EnhancedJSONEncoder(json.JSONEncoder):
+    def default(self, o: Any):
+        try:
+            return {"__type__": type(o).__name__, "__repr__": repr(o)}
+        except Exception:
+            return super().default(o)
+
+
+def _json_dumps_canonical(obj: Any) -> bytes:
+    return json.dumps(obj, ensure_ascii=False, sort_keys=True, separators=(",", ":"), cls=EnhancedJSONEncoder).encode("utf-8")
+
+
+def _stable_hash(payload: Any) -> str:
+    try:
+        data = _json_canonical_dumps(payload)
+    except Exception:
+        data = pickle.dumps(payload, protocol=pickle.HIGHEST_PROTOCOL)
+
+    return hashlib.sha256(data).hexdigest()
+
+
+def _build_key_from_call(func: Callable, args: Tuple[Any, ...], kwargs: Dict[str, Any], include_self: bool) -> str:
+    sig = inspect.signature(func)
+    bound = sig.bind_partial(*args, **kwargs)
+    bound.apply_defaults()
+    items = dict(bound.arguments)
+
+    if not include_self:
+        items.pop("self", None)
+        items.pop("cls", None)
+
+    key_payload = {
+        "fn": f"{func.__module__}.{func.__qualname__}",
+        "params": items,
+    }
+
+    return _stable_hash(key_payload)

pycacheable-0.1.0.dist-info/METADATA

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: pycacheable
+Version: 0.1.0
+Summary: Decorator de cache para funções e métodos Python, com backends InMemory e SQLite, TTL configurável e hash estável de parâmetros.
+Author-email: Leonardo Pinho <contato@leonardopinho.com>
+License: MIT License
+        
+        Copyright (c) 2025 Leonardo Pinho
+        
+        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/leonardopinho/pycacheable
+Project-URL: Repository, https://github.com/leonardopinho/pycacheable
+Project-URL: Issues, https://github.com/leonardopinho/pycacheable/issues
+Keywords: cache,decorator,sqlite,python,performance,memoization,pycharm
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typing-extensions>=4.0.0
+Dynamic: license-file
+
+# PyCacheable
+
+Decorator de cache para métodos e funções Python com backends em memória e SQLite — serialização automática, hash estável de parâmetros, suporte a instância/estado e arquitetura plugável.
+
+---
+
+## Problema
+
+Em muitos aplicativos Python existem métodos que:
+
+- fazem consultas repetidas ao banco de dados ou a APIs externas;
+- recebem os mesmos parâmetros múltiplas vezes;
+- repetem trabalho caro de CPU ou I/O;
+- ou seja: fazem **o mesmo trabalho mais de uma vez**, desperdiçando tempo e recursos.
+
+Sem um mecanismo de cache, cada chamada resulta em reexecução completa, levando a latências elevadas, carga extra no banco/serviço, e experiência de usuário piorada.
+
+---
+
+## Solução
+
+A biblioteca fornece:
+
+- Um decorator `@cacheable(...)` que envolve funções ou métodos, gera uma **chave estável** a partir dos parâmetros (serialização canônica + sha256);
+- Suporte a backends:
+  - `InMemoryCache`: cache volátil em memória com LRU + TTL.
+  - `SQLiteCache`: cache persistente em disco (SQLite) com TTL, ideal para entre execuções ou processos;
+- Logs claros de fluxo: HIT / MISS / EXPIRE — permitindo entender se o cache está funcionando;
+- Métodos auxiliares:
+  - `.cache_clear()`, `.cache_info()` no wrapper para inspeção/manutenção;
+
+---
+
+## Como usar
+
+```python
+from src.pycacheable.backend_sqlite import SQLiteCache
+from src.pycacheable.backend_memory import InMemoryCache
+from src.pycacheable.cacheable import cacheable
+
+mem = InMemoryCache(max_entries=512)
+disk = SQLiteCache(path="./.cache/myapp.sqlite")
+
+
+class Repo:
+    @cacheable(ttl=60, backend=mem)
+    def get_user(self, user_id: int) -> dict:
+        # consulta cara ao banco
+        return {"user_id": user_id, "name": f"user{user_id}"}
+
+    @cacheable(ttl=300, backend=disk)
+    def get_orders(self, user_id: int, status: str = "open") -> list:
+        return [{"order_id": 101, "user_id": user_id, "status": status}]
+
+
+repo = Repo()
+u1 = repo.get_user(42)  # MISS → executa consulta
+u2 = repo.get_user(42)  # HIT → retorna cache, consulta não é executada
+```
+
+---
+
+## Benefícios
+
+- Menor latência em chamadas repetidas (hit quase instantâneo).  
+- Menor carga no banco/serviço, menos I/O repetido.  
+- Persistência local (via SQLite) permite cache entre reinícios/processos.  
+- Transparente para o usuário da função — apenas aplicar o decorator.  
+- Logs e métricas ajudam a monitorar impacto real.
+
+---
+
+## Quando usar
+
+- Funções/métodos com **resultado determinístico** (mesmos parâmetros → mesmo resultado)  
+- Consultas idempotentes e repetidas  
+- Cálculos caros de CPU ou I/O  
+- Cenários onde latência importa e repetição deve ser evitada
+
+---
+
+## Considerações e limites
+
+- O cache evita reexecuções **somente** se os parâmetros para o método forem os mesmos e serializáveis.  
+- Se o método depende de estados mutáveis fora dos parâmetros (ex.: `self.some_state`), você deve usar `include_self=True` ou custom `key_fn`.  
+- TTL é usado para expiração — resultados podem ficar “stale” se parâmetros ou contexto mudarem sem mudar a chave.  
+- Embora o backend SQLite seja persistente, ele **não substitui** um cache distribuído (ex.: Redis) em cenários multi‑processo/semi‑distribuídos.
+
+---
+
+## Benchmarks
+
+Veja resultados reais que medem MISS vs HIT:
+
+| Backend | MISS (s) | HIT (s) | Speedup | Calls |
+|----------|-----------|----------|----------|--------|
+| RAW | 0.6827 | — | — | — |
+| InMemory | 0.6630 | 0.000113 | ~5 870× | 1 |
+| SQLite | 0.7157 | 0.000098 | ~7 300× | 1 |
+
+O cache reduz o tempo de execução de ~0.68 s para ~0.0001 s — um **speedup superior a 5 000×**.
+
+---
+
+## Próximos passos
+
+- Suporte a funções `async def` (decorator awaitable)   
+- Backend Redis / LMDB para cenários distribuídos  
+- Métricas e integração com Prometheus  
+
+---
+
+## Licença
+
+MIT License — veja o arquivo `LICENSE` para detalhes.

pycacheable-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+pycacheable/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pycacheable/backend_memory.py,sha256=KG8u44jJ16Quhr951oJBrNJDIHROf0OEL7yIWfM5CZI,1638
+pycacheable/backend_sqlite.py,sha256=w4ehSE9N2XUInECoTe_xnjM5x1CprZS8LR5i1E9ZyVw,2430
+pycacheable/cache_base.py,sha256=ToC_dRqAJw_L3MKwQU5WkYhLkUrRSgdbxKfoqQL4LKY,306
+pycacheable/cacheable.py,sha256=ZCrZdEfsNpSrN9R3ABPmyKl9Z7O0n0drhKOMnurFMg0,2065
+pycacheable/hashing.py,sha256=4oRSIoFvU8Uf-FitdmHBlbqJB1i8ChtKDjwpzpZ_yjk,3534
+pycacheable-0.1.0.dist-info/licenses/LICENSE,sha256=-JZxc1XvWnZpw2JnH6jFzuLgKVNMrN-sInApa3vcICg,1071
+pycacheable-0.1.0.dist-info/METADATA,sha256=YFd3P7X3QbBoJOjju9ez0LLuSw4M5EGUIuRBXww8DLU,6457
+pycacheable-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pycacheable-0.1.0.dist-info/top_level.txt,sha256=mdIW77ehuhwiwZKUktjcQssACUrfMwSudWQZvrc99rA,12
+pycacheable-0.1.0.dist-info/RECORD,,

pycacheable-0.1.0.dist-info/WHEEL

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

pycacheable-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Leonardo Pinho
+
+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.

pycacheable-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pycacheable