jcpm-data 0.1.0__tar.gz

jcpm_data-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Ambiente local
+.env
+
+# macOS
+.DS_Store

jcpm_data-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

jcpm_data-0.1.0/PKG-INFO

@@ -0,0 +1,435 @@
+Metadata-Version: 2.5
+Name: jcpm-data
+Version: 0.1.0
+Summary: Framework padronizado de engenharia de dados do Grupo JCPM (carga e validação para o DW)
+Author-email: Ullysses Rosendo <ullysses.rosendo@jcpm.com.br>
+License: Proprietary
+Keywords: bigquery,data,data-warehouse,dlt,etl,jcpm
+Requires-Python: >=3.12
+Requires-Dist: click>=8.1.0
+Requires-Dist: copier>=9.0.0
+Requires-Dist: dlt[bigquery]>=1.30.0
+Requires-Dist: google-cloud-storage>=2.0.0
+Requires-Dist: loguru>=0.7.0
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: python-ulid>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.6.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# jcpm-data
+
+Framework padronizado de engenharia de dados do Grupo JCPM. Implementa regras e
+validações de carga de dados para o Data Warehouse (BigQuery via
+[`dlt`](https://dlthub.com/)), com convenção estrita de nomenclatura de tabelas.
+
+## Instalação
+
+```bash
+uv add jcpm-data        # ou: pip install jcpm-data
+```
+
+## Criar um projeto (CLI)
+
+A lib traz um CLI (estilo `django-admin`) que gera um projeto a partir de um
+template [copier](https://copier.readthedocs.io/):
+
+```bash
+jcpm-data startproject "Vendas Diarias" .     # nome e local (. = atual)
+jcpm-data startproject                        # pergunta nome, local e scopes
+```
+
+Pergunta os **scopes** (multiselect): `jcpm` e `external` são **exclusivos** (não
+combinam com outros); os shoppings podem ser combinados. Gera:
+
+```
+.
+├── deploy.yml               # contrato de infra (plataforma jcpm-data-devops)
+├── pyproject.toml           # dependências (inclui jcpm-data)
+├── README.md
+├── project/
+│   ├── main.py              # entrypoint (scope por task + run das sources)
+│   └── sources/example.py   # exemplo de @data
+└── .github/workflows/deploy.yml   # chama o reusable workflow do devops
+```
+
+### `jcpm-data run`
+
+Executa o pipeline do projeto (`project/main.py`), equivalente a
+`python -m project.main`:
+
+```bash
+jcpm-data run              # roda no diretório atual (--path para outro)
+```
+
+### `jcpm-data check`
+
+Dentro de um projeto, valida tudo de uma vez (sai com código ≠ 0 se algo falha):
+
+```bash
+jcpm-data check            # roda no diretório atual (--path para outro)
+```
+
+- **deploy.yml** — existe e tem `apiVersion` + `name` (contrato de infra)
+- **sintaxe** — compila todos os `.py`
+- **imports** — importa `project/` e sources (pega imports quebrados)
+- **lint (ruff)** — roda o `ruff` (pulado se não instalado)
+
+## Módulos
+
+O código da biblioteca vive em `jcpm_data.pipelines`; a raiz reexporta a API
+pública por conveniência (`from jcpm_data import ...`):
+
+| Import (raiz, recomendado) | Módulo-casa | Conteúdo |
+|----------------------------|-------------|----------|
+| `from jcpm_data import Pipeline, ScopeConfig, ScopeName` | `jcpm_data.pipelines` | Núcleo: pipeline e escopo |
+| `from jcpm_data.pipelines.bigquery import data, Column, WRITE_MODE, PARTITION, SCHEMA_POLICY, BigQueryConfig` | `jcpm_data.pipelines.bigquery` | API `@data`, schema e destino BigQuery |
+| `from jcpm_data.pipelines.utils import get_env, get_scope_by_task_id, range_dates, stand_names` | `jcpm_data.pipelines.utils` | Env com escopo, dispatch de tasks, datas, nomes |
+| `from jcpm_data.pipelines.storage import StorageConfig, DataLake` | `jcpm_data.pipelines.storage` | Data lake no GCS (download / mark_processed) |
+
+## Uso (`@data`)
+
+O decorator `@data` carrega toda a configuração de carga; o handler só produz os
+registros brutos (`yield` de lotes). A tabela de destino e o `pipeline_name` do
+dlt seguem a convenção `{scope}__{source}__{resource}` (ex.:
+`jcpm__raw_crm__usuarios`). `source` e `resource` devem ser **minúsculos, sem
+espaços/acentos** (senão `IdentifierValidationError`).
+
+```python
+from jcpm_data.pipelines.bigquery import (
+    Column, PARTITION, SCHEMA_POLICY, WRITE_MODE, data,
+)
+
+USERS_SCHEMA = [
+    Column("id", "INT64", mode="REQUIRED"),
+    Column("nome", "STRING", mode="NULLABLE"),
+    Column("updated_at", "TIMESTAMP", mode="REQUIRED"),
+    Column("particao_data", "DATE", mode="REQUIRED"),
+]
+
+
+@data(
+    source="raw_crm",
+    resource="usuarios",
+    write_mode=WRITE_MODE.MERGE,
+    primary_key=["id"],
+    partition_by=PARTITION.DAY,          # exige a coluna particao_data
+    cluster_by=["status"],
+    cursor_field="updated_at",           # carga incremental (dlt)
+    schema=USERS_SCHEMA,
+    schema_policy=SCHEMA_POLICY.IGNORE,  # STRICT(freeze) / EVOLVE / IGNORE(descarta col extra)
+)
+def extract_crm_users(context):
+    page = 1
+    while True:
+        records = api.get_users(page=page)
+        if not records:
+            break
+        yield records                    # cada lote vai para o BigQuery
+        page += 1
+
+
+pipeline.run(data=extract_crm_users, context={"date": date})
+```
+
+- **`Column(name, type, mode, description)`** — tipos BigQuery (`INT64`, `STRING`,
+  `DATE`, `TIMESTAMP`, ...) convertidos para o schema do dlt.
+- **`WRITE_MODE`**: `APPEND` / `REPLACE` / `MERGE` / `REPLACE_PARTITION`.
+  - `MERGE` exige `primary_key` (upsert por chave).
+  - `REPLACE_PARTITION` **substitui as partições presentes no lote** sem exigir
+    chave natural — ideal para reprocessar um dia/período. Exige `partition_by`;
+    por baixo usa o `merge` do dlt com `merge_key` em `particao_data` (apaga as
+    datas do lote no destino e insere as novas; partições de outras datas ficam
+    intactas). Com `PARTITION.DAY`, substitui exatamente a partição do dia.
+- **`PARTITION`**: `HOUR`/`DAY`/`MONTH`/`YEAR`. A coluna é sempre **`particao_data`**.
+  `DAY` usa o particionamento nativo do dlt; `MONTH`/`YEAR`/`HOUR` **pré-criam a
+  tabela** com `PARTITION BY DATE_TRUNC(...)` (exigem `schema`, pois o dlt só faz DAY).
+- **`SCHEMA_POLICY`** → `schema_contract` do dlt:
+  - `STRICT` (freeze): falha se vier coluna/tabela nova (a tabela precisa já existir).
+  - `EVOLVE` (evolve): adiciona colunas novas automaticamente.
+  - `IGNORE`: mantém as linhas e **descarta as colunas fora do schema** — o
+    DataFrame é projetado no `schema` antes da escrita e o contrato usa
+    `columns: discard_value` (a tabela ainda é criada/evolui).
+- `cluster_by` e `cursor_field` aplicados via `bigquery_adapter`/incremental do dlt.
+- **DataFrames são coagidos ao `schema`** antes da carga (`cast_to_schema`): colunas
+  `DATE`/`TIMESTAMP`/`INT64`/... saem no tipo certo (evita o erro `DATE → STRING`).
+
+### Execução e logs
+
+- `Pipeline(name, scope, bq_config)` — `name` é o nome do projeto (o mesmo do
+  `deploy.yml`) e vira o prefixo dos logs/observabilidade; a `source` vai no
+  `run(data=...)`, então o mesmo pipeline roda várias sources.
+- `run(data, context=None, drop_pending=True)` — por padrão descarta pacotes
+  pendentes de uma carga anterior (evita o loop em que o dlt re-tenta um pacote cujo
+  staging já foi limpo). Use `drop_pending=False` para o retry nativo do dlt.
+- Durante a execução, o framework **emite eventos estruturados** (JSON) para
+  observabilidade — `PIPELINE_STARTED` → `STAGE_*` → `PIPELINE_COMPLETED`/
+  `PIPELINE_FAILED`, com `run_id` único e um `run_summary` (linhas, tempo, status).
+  No handler, use `context.log.info/warning/error(...)` para registrar sinais.
+  Detalhes em [`docs/observabilidade.md`](docs/observabilidade.md).
+
+Utilitários relacionados:
+
+```python
+from jcpm_data.pipelines.utils import range_dates, stand_names  # datas / snake_case
+```
+
+### Códigos de erro do projeto
+
+Declare os erros (código + descrição) num só lugar (`project/errors.py`) e
+reutilize via `context.ERROR.<NOME>` — para **logar** ou **abortar**:
+
+```python
+# project/errors.py
+from jcpm_data import ErrorCatalog
+
+class Errors(ErrorCatalog):              # NOME = "descrição"  (o nome é o código)
+    API_TIMEOUT = "A fonte externa não respondeu no tempo limite"
+    EMPTY_RESULT = "A consulta retornou sem registros"
+```
+
+O mesmo `context.ERROR.<NOME>` serve para **dois usos diferentes** — e quem decide
+abortar é o `raise`, **não** o log:
+
+```python
+# no handler
+def extract(context):
+    # 1) LOGAR (NÃO levanta, NÃO aborta): registra um evento ERROR e segue
+    context.log.error(context.ERROR.API_TIMEOUT)
+
+    # 2) ABORTAR: raise levanta a exceção e interrompe a carga
+    raise context.ERROR.API_TIMEOUT("status 504")
+```
+
+> **`context.log.error` NÃO levanta exceção** — é só um log estruturado (como o
+> `logger.error` do Python). O pipeline **continua**. Para **parar** a carga, use
+> `raise context.ERROR.X(...)`.
+
+| Como você usa | Levanta exceção? | Evento(s) | Status final |
+|---------------|------------------|-----------|--------------|
+| `context.log.error(context.ERROR.X)` | **Não** (segue) | `ERROR` | `WARNING` (concluiu) |
+| `raise context.ERROR.X("detalhe")` | **Sim** (aborta) | `ERROR` + `PIPELINE_FAILED` | `FAILED` |
+
+Detalhes:
+- `context.log.info/warning/error` aceitam o `ErrorCode` direto (usam o código +
+  descrição). **Nenhum** deles interrompe o fluxo — são logs.
+- `raise context.ERROR.X("detalhe")` levanta um `PipelineError` com o `code` do
+  projeto; o `PIPELINE_FAILED` sai com `error_code=API_TIMEOUT` e a `message` inclui
+  a descrição + o detalhe.
+- Os códigos são registrados ao importar o módulo (o `main.py` gerado já faz
+  `import project.errors`). Também dá para usar `Errors.API_TIMEOUT` direto.
+
+### Dev: inferir o schema de um DataFrame
+
+Para não escrever o `schema=` na mão, passe um DataFrame de amostra — o
+`infer_schema` devolve a lista de `Column` pronta para usar:
+
+```python
+from jcpm_data.pipelines.dev import infer_schema
+
+schema = infer_schema(df)                     # -> [Column("customer_id", "INT64", ...), ...]
+
+@data(source="crm", resource="usuarios", schema=infer_schema(df))
+def extract(context): ...
+```
+
+- Tipo deduzido do dtype/valores; `mode=REQUIRED` quando a coluna não tem nulos.
+- Nomes padronizados (snake_case ASCII) por default (`standardize=False` mantém).
+
+Para inspecionar o **conteúdo** de cada coluna (ver o que tem antes de definir
+`schema`/`primary_key`), `sample_distinct` devolve uma amostra de valores distintos
+por coluna:
+
+```python
+from jcpm_data.pipelines.dev import sample_distinct
+
+sample_distinct(df, n=10)   # -> {coluna: [até n valores distintos, não nulos]}
+```
+
+## Chave primária (validação automática)
+
+Quando você define `primary_key` no `@data`, a lib **valida os dados antes de
+enviar ao BigQuery**: se a chave tiver **nulos** ou **duplicatas**, a carga
+**falha** com `PrimaryKeyValidationError` (nada chega ao destino). A verificação
+usa o DataFrame + schema que já estão em mãos — não envolve o dlt.
+
+Para checar manualmente no desenvolvimento (`jcpm_data.pipelines.quality`):
+
+```python
+from jcpm_data.pipelines.quality import check_primary_key
+
+r = check_primary_key(df, ["cod_contrato", "item_cobranca"])
+if not r:                       # é "truthy" quando a chave é única
+    print(r)
+# PrimaryKeyCheck(['cod_contrato', 'item_cobranca']) NÃO única: 4 linha(s),
+#   3 combinação(ões) distinta(s), 1 duplicada(s) (2 linha(s))
+```
+
+- `r.unique`, `r.duplicated_rows`, `r.duplicated_combinations`, `r.examples` (as
+  combinações que mais repetem).
+- **Nulo na chave levanta `PrimaryKeyValidationError`** — uma PK não pode ter nulo.
+
+## Storage (GCS): `DataLake`
+
+Acesso ao data lake no Google Cloud Storage:
+
+```python
+from jcpm_data.pipelines.storage import StorageConfig, DataLake
+
+storage = StorageConfig(bucket="meu-bucket", path_processed="processed")
+lake = DataLake(storage=storage)
+
+# Baixa um arquivo, uma pasta (prefixo) ou um padrão glob.
+# Retorna DownloadedFile (com .local = path local e .remote = blob no GCS).
+lake.download("landing/*.zip")   # usa StorageConfig.download_dir (criado se não existir)
+
+# Itera os arquivos locais — glob interno, sem importar glob:
+for f in lake.local_dir("**/*.zip"):
+    pipeline.run(data=minha_source, context={"zipfile": str(f)})  # f é um Path local
+    lake.mark_processed(f)   # aceita o path LOCAL e deriva o blob no GCS -> processed/...
+```
+
+- O `download` **já devolve** a lista de `DownloadedFile` (não precisa re-listar). Se
+  preferir, itere o retorno direto: `for f in lake.download("landing/*.zip"): ...`.
+- `lake.local_dir()` lista **todos** os arquivos de `download_dir` (recursivo); com um
+  padrão (`lake.local_dir("**/*.zip")`) filtra. (Para o caminho da pasta em si, use
+  `storage.download_dir`.)
+- `mark_processed` aceita `DownloadedFile`, caminho **remoto** (GCS) **ou** caminho
+  **local** sob `download_dir` (deriva o remoto removendo o prefixo).
+
+- **`StorageConfig`**: `bucket`, `project_id` (ADC se nulo), `path` (origem default
+  do download), `path_processed` (pasta de processados), `download_dir` (local).
+  Deriva do `.env` / env vars (`JCPM_GCS_BUCKET`, `JCPM_GCS_PATH_PROCESSED`, ...).
+- **`download(path=None, dest=None)`**: baixa um **arquivo**, uma **pasta** (prefixo)
+  ou um **padrão glob** (`*.zip`, `landing/2026/*.json` — via `fnmatch`, onde `*` casa
+  também `/`, logo recursivo). Preserva a estrutura e retorna a lista de `Path` locais.
+- **`mark_processed(file)`**: move (copy+delete) o arquivo para `path_processed`,
+  trocando a primeira pasta do caminho e mantendo o resto.
+
+## Validações de contrato
+
+Executadas automaticamente em `Pipeline.run()` (via `validate_datasource`),
+**antes** de qualquer acesso à infraestrutura:
+
+| Validação | Regra | Erro |
+|-----------|-------|------|
+| Identificadores | `source`/`resource` e nomes de coluna: minúsculos, `[a-z0-9_]`, sem espaços/acentos. | `IdentifierValidationError` |
+| Chave primária | Obrigatória quando `write_mode=MERGE`. | `PrimaryKeyValidationError` |
+| Partição | Se `partition_by` definido e houver `schema`, a coluna `particao_data` deve estar nele. | `DatePartitionValidationError` |
+| Replace partição | `write_mode=REPLACE_PARTITION` exige `partition_by`. | `DatePartitionValidationError` |
+| Schema | `primary_key`/`cluster_by`/`cursor_field` devem existir no `schema` (quando informado). | `SchemaValidationError` |
+| Tipo de coluna | `Column(type=...)` deve ser um tipo BigQuery válido. | `ColumnNameValidationError` |
+
+Todos os erros herdam de `JcpmDataError` e de `ValueError` (compatível com
+`except ValueError`), e expõem um `code` estável (ex.: `JCPM_PRIMARY_KEY`).
+
+## Cloud Run Jobs: uma task por scope
+
+Em um Cloud Run Job com N tasks, cada task recebe `CLOUD_RUN_TASK_INDEX` (0..N-1).
+`get_scope_by_task_id` mapeia o índice da task para o scope correspondente e
+**valida** que o valor é mesmo um scope:
+
+```python
+from jcpm_data import Pipeline, ScopeConfig, ScopeName
+from jcpm_data.pipelines.bigquery import BigQueryConfig
+from jcpm_data.pipelines.utils import get_scope_by_task_id
+
+# Uma task por scope (ordem = índice da task). Configure --tasks=3 no Job.
+SCOPES = [
+    ScopeName.RIOMAR_RECIFE,
+    ScopeName.RIOMAR_ARACAJU,
+    ScopeName.SALVADOR_SHOPPING,
+]
+
+
+def main() -> None:
+    scope_name = get_scope_by_task_id(SCOPES)        # usa CLOUD_RUN_TASK_INDEX
+    scope = ScopeConfig(name=scope_name)
+    pipeline = Pipeline(name="meu-projeto", scope=scope, bq_config=BigQueryConfig())
+    pipeline.run(data=minha_source, context={"date": "2026-03"})
+```
+
+- `task_id` pode ser passado explicitamente (ex.: testes locais); sem ele, lê
+  `CLOUD_RUN_TASK_INDEX` (ou `0` fora do Cloud Run).
+- Itens da lista podem ser `ScopeName`, `ScopeConfig` ou `str` (coagido para um
+  `ScopeName` conhecido). Valor desconhecido → `ScopeValidationError`.
+- Índice fora do intervalo ou lista vazia → `TaskIndexError`.
+- **`get_object_by_task_id(objetos, task_id=None)`** é a versão genérica (qualquer
+  objeto, sem validação de scope) — ex.: um cliente de API por task.
+
+## Variáveis de ambiente com escopo
+
+`get_env` resolve segredos/parâmetros por tenant seguindo a convenção
+`{SCOPE}_{KEY}`:
+
+```python
+from jcpm_data import ScopeName
+from jcpm_data.pipelines.utils import get_env
+
+# Lê RIOMAR_RECIFE_API_KEY (do ambiente ou do .env)
+api_key = get_env("api_key", scope=ScopeName.RIOMAR_RECIFE)
+
+# Sem escopo -> API_KEY
+token = get_env("token")
+
+# Opcional (não lança se ausente)
+host = get_env("host", scope="external", default="localhost")
+```
+
+- Sem `default`, a variável é **obrigatória**: lança `EnvVarNotFoundError` se ausente.
+- `scope` aceita `ScopeName`, `ScopeConfig` ou `str`.
+- Um arquivo `.env` próximo é carregado automaticamente na primeira leitura (sem
+  sobrescrever variáveis já definidas). Use `load_env(path=...)` para controlar.
+
+## Configuração do BigQuery por ambiente
+
+`BigQueryConfig` deriva seus defaults do ambiente de execução:
+
+| Variável | Default | Descrição |
+|----------|---------|-----------|
+| `JCPM_BQ_PROJECT_ID` / `GOOGLE_CLOUD_PROJECT` | `None` (usa ADC) | Projeto GCP |
+| `JCPM_BQ_LOCATION` | `us-central1` | Região do dataset |
+| `JCPM_BQ_DATASET` | `raw` | Dataset de destino |
+| `JCPM_BQ_TRUNCATE_STAGING` | `true` | Limpa o dataset de staging após a carga |
+| `JCPM_BQ_ADD_LOAD_ID` | `true` | Adiciona `_dlt_load_id` (id da carga) na tabela — lineage |
+
+> O `.env` mais próximo é carregado automaticamente ao construir `BigQueryConfig`.
+> A coluna `_dlt_load_id` é injetada no DDL de tabelas particionadas e, em tabelas
+> **já existentes** que não a têm, é adicionada como **NULLABLE** antes da carga
+> (o dlt não consegue adicionar um campo NOT NULL a uma tabela existente).
+
+> **Staging:** para `MERGE`/`REPLACE` o dlt usa um dataset separado `<dataset>_staging`
+> (ex.: `raw_staging`). Com `truncate_staging=True` as tabelas ficam **vazias** após a
+> carga, mas o dataset permanece (é reutilizado) — isso é esperado. Não dá para usar o
+> mesmo dataset do destino (o dlt exige nomes diferentes).
+
+## Logs e observabilidade
+
+Todo log sai como **JSON estruturado** no stdout (via
+[`loguru`](https://github.com/Delgan/loguru)), em qualquer ambiente — em Cloud Run
+vira `jsonPayload` no Cloud Logging. O framework instrumenta `Pipeline.run` e emite
+eventos padronizados (`PIPELINE_STARTED` → `STAGE_*` → `PIPELINE_COMPLETED`/
+`PIPELINE_FAILED`), cada um com `run_id`, `pipeline_id` e um `message` descritivo
+prefixado por `<name>:<pipeline_id>`. Nível por `LOG_LEVEL` (default `INFO`).
+
+No handler, registre sinais que entram na timeline:
+
+```python
+def extract(context):
+    context.log.info("extraindo clientes...")
+    context.log.warning("taxa de nulos alta", code="HIGH_NULL_RATE", metadata={"col": "cpf"})
+    ...
+```
+
+Guia completo (eventos, `run_summary`, correlação, queries no Cloud Logging):
+[`docs/observabilidade.md`](docs/observabilidade.md).
+
+## Desenvolvimento
+
+```bash
+uv sync --extra dev
+uv run pytest
+```