tenant-rpa-sdk 0.1.1

SDK de logging resiliente para automacoes Python com fallback local

tenant-rpa-sdk

SDK Python para automacoes, com foco em logging resiliente para banco de dados e fallback local.

Objetivo

• Padronizar logs de automacoes em uma tabela de eventos
• Evitar perda de eventos em indisponibilidade temporaria do DB
• Fornecer API simples para uso em qualquer automacao Python

Escopo

• Somente logging (sem lifecycle start/heartbeat/finish)
• Postgres-only (psycopg)
• Dedupe por idempotency_key
• Fallback local em JSONL + reconciliacao por flush_pending()

Instalacao

Desenvolvimento local

cd tenant-rpa-sdk
python -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -e .[dev]

Consumo em RPAs (producao)

Use versao pinada:

tenant-rpa-sdk==0.1.1

Canal 1 (oficial) - PyPI publico:

pip install tenant-rpa-sdk==0.1.1

Canal 2 - package no GitHub (asset da Release):

pip install "https://github.com/<org>/<repo>/releases/download/tenant-rpa-sdk-v0.1.1/tenant_rpa_sdk-0.1.1-py3-none-any.whl"

Se seu ambiente usa mirror privado, ajuste --index-url/--extra-index-url no pip.

Variaveis de ambiente (exemplo ficticio)

Os nomes abaixo sao apenas ilustrativos e podem ser ajustados no seu ambiente:

• APP_DB_PRIMARY ou APP_DB_FAILOVER
• APP_LOG_TABLE (default event_logs)
• APP_LOG_SOURCE (default automation.app)
• APP_LOG_FALLBACK_PATH (default /var/log/example-automation/pending_events.jsonl)
• APP_LOG_FLUSH_ON_START (default true)
• APP_LOG_DB_TIMEOUT_SECONDS (default 5)
• APP_LOG_MAX_MESSAGE_CHARS (default 2000)
• APP_LOG_MAX_METADATA_BYTES (default 32768)

Conexao de banco (exemplo ficticio)

Formato ilustrativo:

postgres,<host>,<port>,<database>,<user>,<password>

Alias encadeado aceito:

APP_DB_PRIMARY=APP_DB_FAILOVER
APP_DB_FAILOVER=postgres,db.example.local,5432,ops_data,svc_logger,***

Se APP_DB_PRIMARY nao existir, use um alias de contingencia.

Uso rapido

from tenant_rpa_sdk import TenantBackendLogger

logger = TenantBackendLogger(
    project_name="demo-project",
    source="automation.order-sync",
    execution_id=123,
    db_alias_env="APP_DB_PRIMARY",
    fallback_path="/tmp/pending_events.jsonl",
    echo_stdout=True,
    flush_on_start=True,
)

logger.info("Processo iniciado", metadata={"step": "bootstrap"})
logger.warning("API lenta", metadata={"latency_ms": 1200})
logger.error("Falha em consulta", metadata={"query_id": "q-09", "token": "redacted"})

result = logger.flush_pending(limit=200)
print(result)

API publica

Classe principal: tenant_rpa_sdk.logger.TenantBackendLogger

Metodos:

• debug(message, *, event_type="APP", metadata=None, execution_id=None)
• info(...)
• warning(...)
• error(...)
• critical(...)
• log(level, message, *, event_type="APP", metadata=None, execution_id=None)
• bind_execution(execution_id)
• flush_pending(limit=200) -> dict

Contrato de fallback JSONL

Cada linha contem:

• idempotency_key
• created_at
• payload
• attempt
• last_error
• next_retry_at

Versionamento e release

• Politica: SemVer estrito (MAJOR.MINOR.PATCH)
• Tags de release: tenant-rpa-sdk-vX.Y.Z (geradas automaticamente a partir de pyproject.toml)
• Publicacao automatica no PyPI por GitHub Actions ao criar tag valida
• Os artefatos .whl e .tar.gz tambem sao anexados na GitHub Release da mesma tag

Consulte:

• CHANGELOG.md
• CONTRIBUTING.md
• docs/versionamento.md
• docs/release.md
• docs/uso-em-rpas.md
• docs/faq.md

Testes

Unitarios:

pytest tests/unit

Integracao (Postgres real, execucao opt-in):

export TENANT_RPA_SDK_INTEGRATION=true
pytest tests/integration