opendata-cvm

Visão geral

Biblioteca Python tipada para ler os arquivos abertos da CVM (Comissão de Valores Mobiliários): baixa o dump publicado em https://dados.cvm.gov.br/dados/ e devolve um DataFrame tipado e validado por contrato.

Valores decimais seguem a regra do projeto: nada de float onde a precisão importa. Colunas numéricas voltam como texto exato da fonte, sem truncar nem arredondar — a escala e o Decimal ficam a cargo de quem consome.

Migração: a seção de envio (opendata_cvm.submission, modelo validado → XML) foi removida e vive no pacote separado layouts-cvm (from layouts_cvm import PerfilMensal). Esta biblioteca não depende dele.

Fonte da verdade: nomes de coluna e tipos vêm dos arquivos reais publicados no portal de dados abertos da CVM — https://dados.cvm.gov.br/dados/ — não desta documentação.

Funcionalidades

Toda solução vive em opendata_cvm.ingestion (leitura ← CVM): analisa um arquivo baixado da CVM de volta para modelos tipados, agrupado por raiz do portal (ex.: opendata_cvm.ingestion.fi).

Para gerar os arquivos XML de envio → CVM, use o pacote separado layouts-cvm.

Documentação

A documentação completa (em pt-BR) fica em https://guilhermegor.github.io/opendata-cvm/ ou pode ser servida localmente:

make docs_server     # serve em http://0.0.0.0:8000  (sem make: ./tasks.sh docs_server)

Primeiros Passos

Pré-requisitos

• Python >= 3.11
• Poetry (recomendado)
• Opcional: Makefile (ou use ./tasks.sh no Git Bash / Windows)

Instalação

Como dependência:

pip install opendata-cvm
# ou
poetry add opendata-cvm

A partir do código-fonte:

git clone https://github.com/guilhermegor/opendata-cvm.git
cd opendata-cvm
make init            # cria a .venv e instala os hooks de pre-commit
                     # (sem make: ./tasks.sh init)

Uso básico

A leitura (← CVM) devolve um DataFrame tipado e validado por contrato:

from datetime import date

from opendata_cvm.ingestion.fi import InformeDiarioReader

df = InformeDiarioReader(date_ref=date(2025, 1, 15)).read()   # dump mensal inf_diario_fi

O exemplo completo (incluindo o bloco obrigatório de contagem de clientes) está em Uso.

Estrutura do projeto

opendata-cvm/
├── assets/                 # logo e imagens do projeto
├── bin/                    # scripts de gate e utilitários (inclui check_readme_structure.sh)
├── docs/                   # documentação MkDocs (pt-BR) — make docs_server
├── mkdocs.yml              # configuração do site de documentação
├── src/opendata_cvm/
│   ├── __init__.py         # API pública (controlada por __all__)
│   ├── ingestion/          # leitura ← CVM (arquivo baixado → DataFrame tipado)
│   └── _internal/          # PRIVADO — contratos, ports (interfaces) + helpers
├── tests/
│   ├── unit/  integration/  performance/
├── .pre-commit-config.yaml
├── Makefile  /  tasks.sh   # interfaces espelhadas (com e sem make)
├── pyproject.toml
└── README.md

Desenvolvimento

make unit_tests      # pytest tests/unit/
make test_cov        # cobertura + badge (coverage.svg)
make lint            # ruff, codespell, pydocstyle, check_docstrings
make help            # lista todos os comandos disponíveis

O README.md em si é validado por bin/check_readme_structure.sh (hook readme-structure no pre-commit e passo equivalente no CI): títulos sem emoji, marcadores <!-- slug: ... --> nas seções obrigatórias e lista de autores com links do GitHub e do LinkedIn.

API pública

A seção ingestion é dona dos seus nomes; o opendata_cvm.__all__ de topo guarda apenas o que não pertence a nenhuma delas. Tudo sob _internal/ é privado.

Publicação

As versões saem pelos workflows release-test-pypi.yaml (ensaio no Test PyPI) e release-pypi.yaml (PyPI + GitHub Release) em .github/workflows/; a tag git é a versão.

O caminho do 0.x ao 1.0.0, e o portão de release que o protege, está em docs/releasing-1-0-0.md.

Contribuição

Contribuições são bem-vindas — leia o docs/contributing.md antes de abrir sua primeira branch. Fluxo resumido:

make lint            # ruff, codespell, pydocstyle
make unit_tests      # pytest tests/unit/

Toda mudança entra por pull request: a branch padrão é protegida pelo ruleset pr-quality-gate (PR obrigatório, testes nos 3 SOs + build da doc verdes, CodeQL limpo e revisão automática do Copilot a cada push). Ele é provisionado por código — make init já o aplica, e make enable_repo_rules o (re)aplica sozinho; nenhuma configuração manual na UI do GitHub é necessária. Detalhes em docs/contributing.md.

Licença

Este projeto é licenciado sob a Licença MIT — veja LICENSE.

Autores

• Guilherme Rodrigues — GitHub | LinkedIn

Links úteis

• Documentação
• PyPI
• Repositório no GitHub
• Issues

_{Agradecimentos: gerado a partir do template lib-minimal via BlueprintX. Biblioteca não oficial, mantida pela comunidade: sem afiliação ou endosso da CVM; o emblema é do regulador.}