pycacheable 0.1.1__tar.gz → 0.2.0__tar.gz

{pycacheable-0.1.1/src/pycacheable.egg-info → pycacheable-0.2.0}/PKG-INFO

@@ -1,8 +1,9 @@
 Metadata-Version: 2.4
 Name: pycacheable
-Version: 0.1.1
-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.
+Version: 0.2.0
+Summary: Decorator de cache para funções e métodos Python, com backends InMemory e SQLite, TTL configurável, hash estável de parâmetros e serialização segura.
 Author-email: Leonardo Pinho <contato@leonardopinho.com>
+Maintainer-email: Leonardo Pinho <contato@leonardopinho.com>
 License: MIT License
         
         Copyright (c) 2025 Leonardo Pinho
@@ -28,27 +29,37 @@ License: MIT License
 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
+Project-URL: Changelog, https://github.com/leonardopinho/pycacheable/blob/main/CHANGES.md
+Project-URL: Documentation, https://github.com/leonardopinho/pycacheable/blob/main/README.md
+Project-URL: Benchmarks, https://github.com/leonardopinho/pycacheable/tree/main/benchmarks
+Keywords: cache,decorator,sqlite,python,performance,memoization,caching
 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 :: Only
 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: Topic :: Utilities
+Classifier: Topic :: Database
 Classifier: Operating System :: OS Independent
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: typing-extensions>=4.0.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+Requires-Dist: ruff>=0.5.0; extra == "dev"
+Requires-Dist: pytest>=8.0.0; extra == "dev"
 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.
+Decorator de cache para métodos e funções Python com backends em memória e SQLite — serialização automática com estratégia JSON-first + pickle fallback, hash estável de parâmetros, suporte a instância/estado e arquitetura plugável.
 
 ---
 
@@ -74,6 +85,9 @@ A biblioteca fornece:
   - `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;
+- Serialização segura:
+  - JSON-first para estruturas simples (seguro, sem risco de RCE)
+  - Pickle fallback para objetos complexos (flexível)
 - Métodos auxiliares:
   - `.cache_clear()`, `.cache_info()` no wrapper para inspeção/manutenção;
 
@@ -110,11 +124,12 @@ 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.  
+- 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.
+- Serialização segura com JSON-first (sem risco de arbitrary code execution).
 
 ---
 
@@ -129,10 +144,11 @@ u2 = repo.get_user(42)  # HIT → retorna cache, consulta não é executada
 
 ## 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.
+- 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.
+- Pickle fallback mantém compatibilidade com objetos complexos, mas use com dados confiáveis.
 
 ---
 
@@ -142,11 +158,11 @@ 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 |
+| RAW | 0.4410 | — | — | — |
+| InMemory | 0.4043 | 0.000043 | ~9,494x | 1 |
+| SQLite | 0.4001 | 0.000763 | ~524x | 1 |
 
-O cache reduz o tempo de execução de ~0.68 s para ~0.0001 s — um **speedup superior a 5 000×**.
+O cache reduz o tempo de execução de ~0.4 s para ~0.00004 s — um **speedup superior a 9.000×**.
 
 ---
 

{pycacheable-0.1.1 → pycacheable-0.2.0}/README.md

@@ -1,6 +1,6 @@
 # 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.
+Decorator de cache para métodos e funções Python com backends em memória e SQLite — serialização automática com estratégia JSON-first + pickle fallback, hash estável de parâmetros, suporte a instância/estado e arquitetura plugável.
 
 ---
 
@@ -26,6 +26,9 @@ A biblioteca fornece:
   - `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;
+- Serialização segura:
+  - JSON-first para estruturas simples (seguro, sem risco de RCE)
+  - Pickle fallback para objetos complexos (flexível)
 - Métodos auxiliares:
   - `.cache_clear()`, `.cache_info()` no wrapper para inspeção/manutenção;
 
@@ -62,11 +65,12 @@ 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.  
+- 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.
+- Serialização segura com JSON-first (sem risco de arbitrary code execution).
 
 ---
 
@@ -81,10 +85,11 @@ u2 = repo.get_user(42)  # HIT → retorna cache, consulta não é executada
 
 ## 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.
+- 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.
+- Pickle fallback mantém compatibilidade com objetos complexos, mas use com dados confiáveis.
 
 ---
 
@@ -94,11 +99,11 @@ 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 |
+| RAW | 0.4410 | — | — | — |
+| InMemory | 0.4043 | 0.000043 | ~9,494x | 1 |
+| SQLite | 0.4001 | 0.000763 | ~524x | 1 |
 
-O cache reduz o tempo de execução de ~0.68 s para ~0.0001 s — um **speedup superior a 5 000×**.
+O cache reduz o tempo de execução de ~0.4 s para ~0.00004 s — um **speedup superior a 9.000×**.
 
 ---
 

{pycacheable-0.1.1 → pycacheable-0.2.0}/pyproject.toml

@@ -1,36 +1,51 @@
 [project]
 name = "pycacheable"
-version = "0.1.1"
-description = "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."
-readme = "README.md"
+version = "0.2.0"
+description = "Decorator de cache para funções e métodos Python, com backends InMemory e SQLite, TTL configurável, hash estável de parâmetros e serialização segura."
+readme = { file = "README.md", content-type = "text/markdown" }
 authors = [
   { name = "Leonardo Pinho", email = "contato@leonardopinho.com" }
 ]
+maintainers = [
+  { name = "Leonardo Pinho", email = "contato@leonardopinho.com" }
+]
 license = { file = "LICENSE" }
 requires-python = ">=3.9"
-keywords = ["cache", "decorator", "sqlite", "python", "performance", "memoization", "pycharm"]
+keywords = ["cache", "decorator", "sqlite", "python", "performance", "memoization", "caching"]
 classifiers = [
   "Development Status :: 4 - Beta",
   "Intended Audience :: Developers",
   "License :: OSI Approved :: MIT License",
   "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
   "Programming Language :: Python :: 3.9",
   "Programming Language :: Python :: 3.10",
   "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
   "Topic :: Software Development :: Libraries",
   "Topic :: Software Development :: Libraries :: Python Modules",
+  "Topic :: Utilities",
+  "Topic :: Database",
   "Operating System :: OS Independent",
 ]
 
-dependencies = [
-  "typing-extensions >=4.0.0",
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+  "build>=1.2.0",
+  "twine>=5.0.0",
+  "ruff>=0.5.0",
+  "pytest>=8.0.0",
 ]
 
 [project.urls]
 Homepage = "https://github.com/leonardopinho/pycacheable"
 Repository = "https://github.com/leonardopinho/pycacheable"
 Issues = "https://github.com/leonardopinho/pycacheable/issues"
+Changelog = "https://github.com/leonardopinho/pycacheable/blob/main/CHANGES.md"
+Documentation = "https://github.com/leonardopinho/pycacheable/blob/main/README.md"
+Benchmarks = "https://github.com/leonardopinho/pycacheable/tree/main/benchmarks"
 
 [build-system]
 requires = ["setuptools>=68.0", "wheel"]

pycacheable-0.2.0/src/pycacheable/backend_memory.py

@@ -0,0 +1,79 @@
+"""Cache em memória com LRU e TTL."""
+import threading
+import time
+from collections import OrderedDict
+from typing import Any, Dict, Optional, Tuple
+
+from .cache_base import CacheBackend
+from .serializers import SafeSerializer
+
+
+class InMemoryCache(CacheBackend):
+    """Cache em memória com LRU e TTL, thread-safe."""
+
+    def __init__(self, max_entries: int = 1024, serializer=None):
+        """
+        Args:
+            max_entries: Máximo de itens antes de evicção LRU
+            serializer: Instância de serializer (padrão: SafeSerializer)
+        """
+        self._store: OrderedDict[str, Tuple[float, bytes]] = OrderedDict()
+        self._lock = threading.RLock()
+        self._max_entries = max_entries
+        self._serializer = serializer or SafeSerializer()
+
+    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
+
+            # Verifica expiração
+            if expire_at and expire_at < now:
+                self._store.pop(key, None)
+                return False, None, "EXPIRE"
+
+            # Move para fim (LRU)
+            self._store.move_to_end(key)
+
+            # Desserializa
+            try:
+                value = self._serializer.loads(payload)
+                return True, value, "HIT"
+            except Exception:
+                # Se falhar na desserialização, remove do cache
+                self._store.pop(key, None)
+                return False, None, "DESERIALIZE_ERROR"
+
+    def set(self, key: str, value: Any, ttl_seconds: Optional[int]) -> None:
+        with self._lock:
+            expire_at = (time.time() + ttl_seconds) if ttl_seconds else 0.0
+
+            try:
+                payload = self._serializer.dumps(value)
+            except Exception:
+                # Se falhar na serialização, pula (não armazena)
+                return
+
+            self._store[key] = (expire_at, payload)
+            self._store.move_to_end(key)
+
+            # Evicção LRU
+            while len(self._store) > self._max_entries:
+                self._store.popitem(last=False)
+
+    def clear(self) -> None:
+        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-0.2.0/src/pycacheable/backend_sqlite.py

@@ -0,0 +1,99 @@
+"""Cache persistente em SQLite com TTL."""
+import os
+import sqlite3
+import threading
+import time
+from typing import Any, Dict, Optional, Tuple
+
+from .cache_base import CacheBackend
+from .serializers import SafeSerializer
+
+
+class SQLiteCache(CacheBackend):
+    """Cache persistente em SQLite com TTL, thread-safe."""
+
+    def __init__(self, path: str, serializer=None):
+        """
+        Args:
+            path: Caminho para arquivo SQLite
+            serializer: Instância de serializer (padrão: SafeSerializer)
+        """
+        self._path = path
+        self._lock = threading.RLock()
+        self._serializer = serializer or SafeSerializer()
+
+        # Cria diretório se não existir
+        dir_path = os.path.dirname(os.path.abspath(path))
+        if dir_path:
+            os.makedirs(dir_path, exist_ok=True)
+
+        # Inicializa banco
+        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):
+        """Cria nova conexão (autocommit mode)."""
+        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
+
+            # Verifica expiração
+            if expire_at and expire_at < now:
+                conn.execute("DELETE FROM cache WHERE k=?", (key,))
+                return False, None, "EXPIRE"
+
+            # Desserializa
+            try:
+                value = self._serializer.loads(blob)
+                return True, value, "HIT"
+            except Exception:
+                # Se falhar na desserialização, remove do cache
+                conn.execute("DELETE FROM cache WHERE k=?", (key,))
+                return False, None, "DESERIALIZE_ERROR"
+
+    def set(self, key: str, value: Any, ttl_seconds: Optional[int]) -> None:
+        expire_at = (time.time() + ttl_seconds) if ttl_seconds else 0.0
+
+        try:
+            blob = self._serializer.dumps(value)
+        except Exception:
+            # Se falhar na serialização, pula
+            return
+
+        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) -> None:
+        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-0.2.0/src/pycacheable/cache_base.py

@@ -0,0 +1,40 @@
+"""Interface abstrata para implementações de cache."""
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Optional, Tuple
+
+
+class CacheBackend(ABC):
+    """Interface clara e tipada para backends de cache."""
+
+    @abstractmethod
+    def get(self, key: str) -> Tuple[bool, Any, str]:
+        """
+        Recupera um valor do cache.
+
+        Retorna:
+            (hit: bool, value: Any, status: str)
+            - hit: True se encontrou, não expirou e desserializou com sucesso
+            - value: o valor cacheado (None se miss/expire/erro)
+            - status: "HIT", "MISS", "EXPIRE", ou "DESERIALIZE_ERROR"
+        """
+        pass
+
+    @abstractmethod
+    def set(self, key: str, value: Any, ttl_seconds: Optional[int]) -> None:
+        """Armazena um valor no cache com TTL opcional."""
+        pass
+
+    @abstractmethod
+    def clear(self) -> None:
+        """Remove todos os itens do cache."""
+        pass
+
+    @abstractmethod
+    def info(self) -> Dict[str, Any]:
+        """Retorna informações sobre o estado do cache."""
+        pass
+
+
+# Alias para compatibilidade com código existente
+CacheBase = CacheBackend
+

pycacheable-0.2.0/src/pycacheable/cacheable.py

@@ -0,0 +1,105 @@
+"""Decorator de cache com backends plugáveis."""
+import functools
+from typing import Any, Callable, Dict, Optional, Tuple
+
+from .backend_sqlite import SQLiteCache
+from .cache_base import CacheBackend
+from .hashing import _build_key_from_call
+
+
+def cacheable(
+        ttl: Optional[int] = 300,
+        backend: Optional[CacheBackend] = 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[..., CacheBackend]] = None,
+):
+    """
+    Decorator de cache com backend configurável.
+
+    Ciclo de vida do backend (ordem de prioridade):
+    1. Se backend_factory fornecido: chamado por chamada (per-instance ou per-param)
+    2. Se wrapper.cache_backend foi atribuído externamente: usa esse override
+    3. Se backend fornecido: usa esse (compartilhado entre chamadas)
+    4. Padrão: cria SQLiteCache novo
+
+    Args:
+        ttl: Tempo de vida em segundos (None = sem expiração)
+        backend: Instância de CacheBackend compartilhada
+        include_self: Se True, inclui 'self' na chave (para estado de instância)
+        key_fn: Função customizada de geração de chave
+        logger: Função para log de eventos cache
+        backend_factory: Callable que retorna CacheBackend por chamada
+
+    Exemplo:
+        >>> @cacheable(ttl=60, backend=InMemoryCache())
+        ... def get_user(user_id: int):
+        ...     return fetch_from_db(user_id)
+
+        >>> # Override backend em teste:
+        >>> get_user.cache_backend = test_backend
+    """
+    # Resolve backend padrão uma única vez
+    default_backend = backend or SQLiteCache(path="./.cache/db.sqlite3")
+
+    def decorator(func: Callable):
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            # Resolve qual backend usar (com fallback chain)
+            be = None
+
+            if backend_factory is not None:
+                try:
+                    be = backend_factory(*args, **kwargs)
+                except TypeError:
+                    # Fallback: tenta com first positional arg (self em métodos)
+                    try:
+                        be = backend_factory(args[0]) if args else None
+                    except Exception:
+                        pass
+
+            # Se factory falhou ou não existe, usa cache_backend ou padrão
+            if be is None:
+                be = getattr(wrapper, "cache_backend", default_backend)
+
+            # Gera chave estável
+            key = (
+                key_fn(func, args, kwargs)
+                if key_fn
+                else _build_key_from_call(func, args, kwargs, include_self)
+            )
+
+            # Tenta obter do cache
+            hit, value, status = be.get(key)
+            if hit:
+                if logger:
+                    logger(f"[CACHE {status}] {func.__qualname__} {key[:10]}…")
+                return value
+
+            # Cache miss: executa função
+            if logger:
+                logger(f"[CACHE {status}] {func.__qualname__} {key[:10]}… -> calling")
+
+            result = func(*args, **kwargs)
+
+            # Tenta armazenar no cache
+            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
+
+        # Atributos públicos para inspeção/controle
+        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-0.2.0/src/pycacheable/serializers.py

@@ -0,0 +1,50 @@
+"""Estratégias de serialização thread-safe para cache."""
+import json
+import pickle
+from typing import Any
+
+
+class SafeSerializer:
+    """
+    Serializer híbrido: tenta JSON (seguro) primeiro, fallback para pickle.
+
+    Prefixos:
+    - 0x00: JSON (seguro, sem risco de code execution)
+    - 0x01: Pickle (flexível, suporta objetos complexos)
+
+    Exemplo:
+        >>> ser = SafeSerializer()
+        >>> data = ser.dumps({"user": 42})
+        >>> obj = ser.loads(data)
+    """
+
+    def dumps(self, obj: Any) -> bytes:
+        """Serializa obj para bytes com prefixo de tipo."""
+        try:
+            # Tenta JSON primeiro
+            payload = json.dumps(
+                obj, ensure_ascii=False, sort_keys=True, separators=(",", ":")
+            ).encode("utf-8")
+            return b"\x00" + payload
+        except (TypeError, ValueError):
+            # Fallback para pickle
+            payload = pickle.dumps(obj, protocol=pickle.HIGHEST_PROTOCOL)
+            return b"\x01" + payload
+
+    def loads(self, data: bytes) -> Any:
+        """Desserializa bytes baseado no prefixo."""
+        if not data or len(data) < 1:
+            raise ValueError("Empty serialized data")
+
+        prefix = data[0:1]
+        payload = data[1:]
+
+        if prefix == b"\x00":
+            return json.loads(payload.decode("utf-8"))
+        elif prefix == b"\x01":
+            return pickle.loads(payload)
+        else:
+            prefix_hex = hex(prefix[0]) if prefix else "unknown"
+            raise ValueError(f"Unknown serializer prefix: {prefix_hex}")
+
+