Skip to content

Intro

Project template para criação e atualização de frictionless data packages das fontes de dados primárias utilizadas no âmbito da Assessoria de Inteligência de Dados.

Requirements

Para inicialização do projeto os seguintes softwares são necessários:

  • git;
  • make;
  • Python (e pacotes cookiecutter, jinja2-git, e uv preferencialmente instalados com pipx).

Para execução das etapas do processo de ETL é necessário:

  • Rstudio & R; ou
  • Docker.

Quickstart

Para iniciar um novo data package execute:

python -m cookiecutter https://github.com/splor-mg/cookiecutter-datapackage

Depois de informar uma slug para o projeto uma nova pasta será inicializada:

Creating virtual environment...
Running pip compile...
Initializing Git repository...
Initialized empty Git repository in ~/project/.git/

Agora pode ser um bom momento para fazer um commit dos arquivos originais do template:

cd ~/project/
git add .
git add -f data/.gitkeep data-raw/.gitkeep
git commit -m "initial commit"

Note

O cookiecutter-datapackage possui um workflow padronizado do Github Actions para executar os phony targets make all e make publish diariamente (on schedule) e sob demanda (on workflow_dispatch).

Ao criar um novo repositório no Github esse workflow vai estar ativo por padrão.

Se o agendamento diário não for necessário (como por exemplo em repositórios upstream) lembre-se de desativar o Github Actions para esse repositório.

Para execução local é necessário a instalação das dependências do python no ambiente virtual do projeto:

source venv/bin/activate
python -m pip install -r requirements.txt

Note

O arquivo requirements.in é utilizado para controle das dependências python diretas do projeto. Qualquer atualização neste arquivo deve ser seguida da execução do comando:

 uv pip compile requirements.in > requirements.txt

Dessa forma o arquivo requirements.txt vai estar atualizado com todas as versões das dependências diretas e indiretas do projeto.

Você pode testar que tudo funcionou com o comando:

make all

Que deve gerar o seguinte resultado:

python main.py extract fact && python main.py extract dim && true
2023-07-21T09:18:09-0300 INFO  [scripts.extract] Extract not implemented for resource {resource_name}...
2023-07-21T09:18:09-0300 INFO  [scripts.extract] Extract not implemented for resource {resource_name}...
frictionless validate datapackage.yaml
──────────────────────────────────────────────── Dataset ─────────────────────────────────────────────────
                   dataset                   
┏━━━━━━┳━━━━━━━┳━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┓
┃ name ┃ type  ┃ path              ┃ status ┃
┡━━━━━━╇━━━━━━━╇━━━━━━━━━━━━━━━━━━━╇━━━━━━━━┩
│ fact │ table │ data-raw/fact.txt │ VALID  │
│ dim  │ table │ data-raw/dim.txt  │ VALID  │
└──────┴───────┴───────────────────┴────────┘
python main.py transform fact --target-descriptor logs/transform/fact.json
2023-07-21T09:18:09-0300 INFO  [scripts.transform] Transforming resource fact
python main.py transform dim --target-descriptor logs/transform/dim.json
2023-07-21T09:18:10-0300 INFO  [scripts.transform] Transforming resource dim
python main.py build
frictionless validate datapackage.json
─────────────────────────────────────────────────────────── Dataset ────────────────────────────────────────────────────────────
                   dataset                   
┏━━━━━━┳━━━━━━━┳━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┓
┃ name ┃ type  ┃ path              ┃ status ┃
┡━━━━━━╇━━━━━━━╇━━━━━━━━━━━━━━━━━━━╇━━━━━━━━┩
│ fact │ table │ data/fact.csv     │ VALID  │
│ dim  │ table │ data/dim.csv      │ VALID  │
└──────┴───────┴───────────────────┴────────┘

Para entender como customizar o projeto siga o Tutorial.