CUP: a biblioteca Python da Baidu que resolve logging, cache, threads e monitoramento em produção

A Baidu mantém em código aberto uma biblioteca Python utilitária que resolve problemas recorrentes de engenharia de software com elegância. Chamada CUP (Common Useful Python), a biblioteca oferece logging estruturado, cache TTL em memória, configuração aninhada, pool de threads, monitoramento de recursos do Linux e várias outras ferramentas que aceleram o desenvolvimento de workflows confiáveis em Python.

O que é o CUP e por que ele importa

Disponível no GitHub (github.com/baidu/CUP), o CUP é um toolkit pensado para ambientes de produção. Ele não reinventa a roda — em vez disso, empacota padrões consolidados com uma API consistente e bem documentada. Se você já escreveu código repetitivo para logging, cache, configuração hierárquica ou gerenciamento de threads, o CUP provavelmente tem uma resposta pronta.

A biblioteca é instalada com um simples pip install cup e funciona em Linux, macOS e Windows, com suporte a Python 3.

Logging que não atrapalha

O módulo cup.log vai além do logging padrão do Python. Ele suporta rotação automática de arquivos, log simultâneo em stdout e arquivo, e níveis configuráveis por runtime:

from cup import log

log.init_comlog(
    "meu_app", log.INFO, "/var/log/app.log",
    log.ROTATION, 10 * 1024 * 1024,  # 10 MB
    True, False
)

log.info("processamento iniciado")
log.warning("latência acima do esperado")

# Altera nível sem reiniciar
log.setloglevel(log.DEBUG)

Funções como info_if(condição, mensagem) evitam boilerplate de if antes do log, e o parser integrado consegue extrair campos estruturados (timestamp, pid, nível, mensagem) de cada linha.

Configuração hierárquica sem dor

O sistema de configuração do CUP (cup.util.conf) lida com arquivos INI-like com seções aninhadas usando um seletor de ponto. Valores repetidos com @path: são automaticamente convertidos em listas:

# demo.conf
host: abc.com
port: 12345

[monitor]
enabled: true
interval: 60

[.thresholds]
cpu_max: 90
mem_max: 80

[storage]
@path: /data/disk1
@path: /data/disk2

Para ler:

from cup.util import conf

cfg = conf.Configure2Dict("demo.conf").get_dict()
print(cfg["monitor.thresholds.cpu_max"])  # 90
print(cfg["storage.path"])                 # ['/data/disk1', '/data/disk2']

O ciclo de leitura → modificação → escrita é suportado nativamente com Dict2Configure, permitindo que aplicações atualizem arquivos de configuração programaticamente.

Cache TTL e geradores de ID

O cup.cache.KVCache é um cache chave-valor em memória com TTL (time-to-live) configurável por entrada. Ideal para evitar chamadas repetidas a APIs, caching de embeddings ou qualquer dado que expire:

from cup import cache

kv = cache.KVCache(name="embeddings")
kv.set("doc_42", embedding_vector, ttl=3600)  # expira em 1h
cached = kv.get("doc_42")  # None se expirado

O CUP também fornece geradores de ID únicos e seguros para ambientes distribuídos via cup.util.id.

Threads, agendamento e execução confiável

O módulo de concorrência do CUP oferece três ferramentas que faltam na biblioteca padrão:

• ThreadPool com fila de trabalho: gerencie workers concorrentes com backpressure automático
• Threads interrompíveis: threads que respondem a sinais de cancelamento, permitindo shutdown gracioso sem threading.Event manual
• RW Lock: lock de leitura/escrita para cenários com muitas leituras e poucas escritas

Para agendamento, o CUP oferece um mini-cron (cup.time.cron) e execução com delay (cup.time.delayed_task), úteis para tarefas como limpeza de cache ou health checks periódicos:

from cup.time import delayed_task

def cleanup():
    print("limpando logs antigos...")

# Executa após 30 segundos
delayed_task(cleanup, delay=30)

Monitoramento de recursos do Linux

O módulo cup.res.linux expõe métricas do sistema sem dependências externas — CPU, memória, disco, rede e processos — usando apenas leitura de /proc e /sys:

from cup.res import linux as res

print(res.get_cpu_usage())        # {'user': 12.3, 'system': 4.1, 'idle': 83.6}
print(res.get_meminfo()["MemAvailable"])  # bytes disponíveis
print(res.get_disk_usage("/"))    # {'total': ..., 'used': ..., 'free': ...}
print(res.get_network_bytes("eth0"))  # (rx_bytes, tx_bytes)

Essas funções são leves o suficiente para serem chamadas a cada segundo em loops de monitoramento, sem o overhead de bibliotecas como psutil.

Outros utilitários que salvam o dia

O CUP inclui ainda:

• File locking (cup.util.lock): trava arquivos entre processos para evitar condições de corrida
• Networking helpers (cup.net): operações de rede com timeout e retry
• Object storage (cup.services.storage): interface unificada para S3, disco local e outros backends
• Type maps bidirecionais (cup.flag.TypeMan): mapeamento chave↔valor com busca O(1) nos dois sentidos
• Asserções de teste (cup.unittest): extensões para unittest do Python

Vale a pena adotar?

O CUP não é um framework opinativo — é uma coleção de ferramentas bem testadas que você pode adotar seletivamente. O fato de ser mantido pela Baidu e usado internamente em sistemas de larga escala é um bom indicador de maturidade. A documentação é razoável e o código é limpo, com tipagem e docstrings.

As limitações: o foco em Linux para o módulo de recursos significa que algumas funções não funcionam em macOS ou Windows. E, como qualquer dependência adicional, incluir o CUP no projeto adiciona superfície de manutenção — pese isso contra o código que você deixaria de escrever.

Para times que constroem pipelines de dados, agentes autônomos ou serviços Python que precisam de logging robusto, cache e monitoramento sem depender de dezenas de bibliotecas diferentes, o CUP merece um lugar no requirements.txt.