filings-cvm 
Biblioteca Python tipada para os padrões de arquivo XML regulatórios da CVM (Comissão de Valores Mobiliários). Monte, valide e serialize documentos no formato exigido pela CVM — e, à medida que a biblioteca cresce, leia arquivos baixados da CVM de volta para modelos tipados.
Modelos Pydantic v2 validam tudo na construção — formato
de datas, dígitos verificadores de CNPJ/CPF e a escala decimal de cada campo — e valores
com casas decimais em excesso são truncados em direção a zero (ROUND_DOWN), nunca
arredondados, para que um valor reportado jamais seja inflado.
Fonte da verdade: nomes de campo, escalas decimais e cardinalidades vêm do catálogo oficial da CVM — https://cvmweb.cvm.gov.br/SWB/Sistemas/SCW/PadroesXML/PadroesXML.asp — não desta documentação.
📖 Documentação
A documentação completa (em pt-BR) fica em https://guilhermegor.github.io/filings-cvm/ ou pode ser servida localmente:
make docs_server # serve em http://0.0.0.0:8000 (sem make: ./tasks.sh docs_server)
✨ Funcionalidades
Toda solução vive em uma de duas macrosseções:
| Seção | Sentido | O que faz |
|---|---|---|
filings_cvm.submission |
envio → CVM | Recebe modelos de schema validados e produz o arquivo XML compatível com a CVM, pronto para envio. |
filings_cvm.ingestion |
leitura ← CVM | Analisa um arquivo baixado da CVM de volta para modelos tipados. Criada quando o primeiro padrão de leitura for implementado. |
O schema compartilhado (modelos Pydantic que espelham cada padrão XML) é neutro em
relação à direção e reexportado pelas seções públicas — você importa tudo de que precisa a
partir de filings_cvm.submission.
🧩 Padrões implementados (envio)
- ✅ Perfil Mensal — V4 (
PadraoXMLPerfilV4.asp) —PerfilMensal/PerfilMensalDocument - ✅ Informe Diário — V4 (
PadraoXMLInfoDiarioNetV4.asp) —InformeDiario/InformeDiarioDocument
Os demais padrões do catálogo (CDA, Lâmina, Informe Mensal FIDC, etc.) estão pendentes —
consulte o CLAUDE.md do repositório para o catálogo completo com o status de cada um.
🚀 Primeiros Passos
Pré-requisitos
- Python >= 3.10
- Poetry (recomendado)
- Opcional: Makefile (ou use
./tasks.shno Git Bash / Windows)
Instalação
Como dependência:
pip install filings-cvm
# ou
poetry add filings-cvm
A partir do código-fonte:
git clone https://github.com/guilhermegor/filings-cvm.git
cd filings-cvm
make init # cria a .venv e instala os hooks de pre-commit
# (sem make: ./tasks.sh init)
Uso básico
from filings_cvm.submission import (
DocumentHeader,
PerfilMensal,
PerfilMensalDocument,
PerfilMensalRow,
)
header = DocumentHeader(dt_compt="01/2025", dt_gerac_arq="15/01/2025")
row = PerfilMensalRow(cnpj_fdo="11222333000181", ...) # validado na construção
doc = PerfilMensalDocument(header=header, rows=[row])
xml = PerfilMensal().export(doc) # XML como str
PerfilMensal().export(doc, output_path="perfil.xml") # ou grava em disco (windows-1252)
E a leitura (← CVM) devolve um DataFrame tipado e validado por contrato:
from datetime import date
from filings_cvm.ingestion 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.
Execução dos testes
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
📂 Estrutura do projeto
filings-cvm/
├── assets/ # logo e imagens do projeto
├── docs/ # documentação MkDocs (pt-BR) — make docs_server
├── mkdocs.yml # configuração do site de documentação
├── src/filings_cvm/
│ ├── __init__.py # API pública (controlada por __all__)
│ ├── submission/ # envio → CVM (modelo validado → XML)
│ ├── ingestion/ # leitura ← CVM (arquivo baixado → DataFrame tipado)
│ └── _internal/ # PRIVADO — schemas Pydantic, ports (interfaces) + helpers
├── tests/
│ ├── unit/ integration/ performance/
├── .pre-commit-config.yaml
├── Makefile / tasks.sh # interfaces espelhadas (com e sem make)
├── pyproject.toml
└── README.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.
👨💻 Autores
Guilherme Rodrigues
📜 Licença
Este projeto é licenciado sob a Licença MIT — veja LICENSE.
🙌 Agradecimentos
- Gerado a partir do template lib-minimal via BlueprintX.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file filings_cvm-0.25.20.tar.gz.
File metadata
- Download URL: filings_cvm-0.25.20.tar.gz
- Upload date:
- Size: 194.9 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
6532a23a1ee33ec3238aaadaa5c3e7b63bf71d812577dc883bf89b2008fb86e5
|
|
| MD5 |
4c306dabcf538e54cba7a0ad39155cd0
|
|
| BLAKE2b-256 |
b55c98c93c2636712f809eb30db08d8ef19e4afe5307411bab0898dbd6d65095
|
Provenance
The following attestation bundles were made for filings_cvm-0.25.20.tar.gz:
Publisher:
release-pypi.yaml on guilhermegor/filings-cvm
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
filings_cvm-0.25.20.tar.gz -
Subject digest:
6532a23a1ee33ec3238aaadaa5c3e7b63bf71d812577dc883bf89b2008fb86e5 - Sigstore transparency entry: 2219967471
- Sigstore integration time:
-
Permalink:
guilhermegor/filings-cvm@86e7b592913f3f8737cd23bc97828bc5d86d0c38 -
Branch / Tag:
refs/heads/main - Owner: https://github.com/guilhermegor
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release-pypi.yaml@86e7b592913f3f8737cd23bc97828bc5d86d0c38 -
Trigger Event:
workflow_dispatch
-
Statement type:
File details
Details for the file filings_cvm-0.25.20-py3-none-any.whl.
File metadata
- Download URL: filings_cvm-0.25.20-py3-none-any.whl
- Upload date:
- Size: 469.5 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
e32c4793f478e872fb91d6fc5c9504a77093bebf18d7a1f5b1b7ff207d61c1ab
|
|
| MD5 |
cfaf7bbea8133432522d27a8a0481c01
|
|
| BLAKE2b-256 |
2f38ac635b8679f1e0083c59801da5161ecac9bf0a4fd8a5713b3e403cb06560
|
Provenance
The following attestation bundles were made for filings_cvm-0.25.20-py3-none-any.whl:
Publisher:
release-pypi.yaml on guilhermegor/filings-cvm
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
filings_cvm-0.25.20-py3-none-any.whl -
Subject digest:
e32c4793f478e872fb91d6fc5c9504a77093bebf18d7a1f5b1b7ff207d61c1ab - Sigstore transparency entry: 2219967522
- Sigstore integration time:
-
Permalink:
guilhermegor/filings-cvm@86e7b592913f3f8737cd23bc97828bc5d86d0c38 -
Branch / Tag:
refs/heads/main - Owner: https://github.com/guilhermegor
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release-pypi.yaml@86e7b592913f3f8737cd23bc97828bc5d86d0c38 -
Trigger Event:
workflow_dispatch
-
Statement type:
