Py Key Value - AsyncKeyValue

py-key-value (do site strawgate.com)

py-key-value é uma biblioteca Python que oferece uma interface pluggable (plugável) para armazenamento tipo chave-valor (key-value) com suporte a múltiplos backends e recursos avançados. O foco principal é permitir que aplicativos e frameworks trabalhem com um contrato uniforme para armazenar, recuperar e manipular dados por meio de chaves, independentemente do sistema de armazenamento usado.

---

🧠 Visão Geral

O que é

• Uma framework Python para armazenamento tipo key-value com suporte a várias implementações de backend.
• Projetada para ser flexível, extensível e tipada, com suporte a TTL (time-to-live), coleções e adaptadores.
• Permite trocar o backend de armazenamento sem alterar o código da aplicação.

Características principais

• Múltiplos backends: Redis, DynamoDB, Elasticsearch, MongoDB, Memcached, RocksDB, arquivos de disco, armazenamento em memória, etc.
• TTL (expiração automática de chaves) suportado em todos os backends.
• Segurança de tipos com type hints e interfaces (AsyncKeyValue).
• Adaptadores e Wrappers para adicionar funcionalidades como:
  – serialização Pydantic,
  – rastreamento de métricas,
  – compressão,
  – criptografia.
• Organização por coleções/namespaces.

---

🧩 Instalação

Instale via pip o pacote principal (async) ou com suporte para backends específicos:

pip install py-key-value-aio
pip install py-key-value-aio[redis]
pip install py-key-value-aio[dynamodb]
pip install py-key-value-aio[all]

---

🚀 Exemplo Rápido

Exemplo usando o store de memória:

from key_value.aio.stores.memory import MemoryStore
 
store = MemoryStore()
 
# Armazena um valor com TTL de 1 hora
await store.put(
    key="user:123",
    value={"name": "Alice", "email": "alice@example.com"},
    collection="users",
    ttl=3600
)
 
# Recupera valor
user = await store.get(key="user:123", collection="users")
print(user)  # {"name": "Alice", "email": "alice@example.com"}

---

🧱 Conceitos Importantes

Protocolos

O núcleo define interfaces (protocols) como AsyncKeyValue, que especifica os métodos básicos:

• get(key, collection) — lê um valor por chave.
• put(key, value, collection, ttl) — armazena um valor (com TTL opcional).
• delete(key, collection) — remove um valor.
• Variações em lote/coleções também são suportadas.

(Os métodos exatos podem variar conforme o backend, mas seguem o contrato da interface.)

---

🛠️ Uso em Frameworks

Quando usado em um framework, o código só depende de AsyncKeyValue, então qualquer backend pode ser trocado sem alterar o framework:

class YourFramework:
    def __init__(self, cache: AsyncKeyValue):
        self.cache = cache

Usuários do framework podem escolher:

• MemoryStore() — desenvolvimento/testes
• RedisStore() — produção
• NullStore() — testes sem efeitos colaterais

…entre outros.

---

🔌 Adapters e Wrappers

Adaptadores

Adaptadores permitem:

• Serializar/deserializar tipos arbitrários (ex.: com Pydantic);
• Tratar ausência de chave de forma customizada;
• Mapear valores para modelos Python tipados.

Wrappers

Uma camada adicional sobre o store que pode:

• rastrear estatísticas;
• aplicar compressão;
• adicionar criptografia;
• implementar comportamentos transversais (cross-cutting concerns).

---

⚠️ Limitações e Observações

• O pacote foca em uso assíncrono (async).
• A versão síncrona foi descontinuada ou não é mais mantida ativamente.
• Valores podem ser armazenados internamente em um wrapper que inclui metadados (como TTL e timestamp).

---

🧭 Onde encontrar mais

• Documentação oficial: https://strawgate.com/py-key-value/
• Repositório no GitHub: https://github.com/strawgate/py-key-value

---

📌 Referências

• Documentação oficial do py-key-value
• Repositório oficial no GitHub