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.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.
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
Metadata
1 maintainer
Release files for filings-cvm 0.26.9
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| filings_cvm-0.26.9.tar.gz | 270.4 kB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| filings_cvm-0.26.9-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 941.1 kB
Release files / filings_cvm-0.26.9.tar.gz
| Download URL | filings_cvm-0.26.9.tar.gz |
|---|---|
| Size | 270.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b0e3760bdf3bf11102d26b1b0a4c24697d8f1d211225288432bd4f67165d08d3
|
|
BLAKE2b-256 checksum How to use checksums |
7bebb70112f1e54a6f6d0bc1efaec2a9f35cbde56beb4e70d9971a4d6d8c7f65
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 9, 2026.
Transparency logRelease files / filings_cvm-0.26.9-py3-none-any.whl
| Download URL | filings_cvm-0.26.9-py3-none-any.whl |
|---|---|
| Size | 670.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a0fcefd827e46505e05ae4b908b86d51496cf88789186d15cdc1e152bed1747a
|
|
BLAKE2b-256 checksum How to use checksums |
86c0b01db437da1c4c783e5b85f2fef6a16557096f13a27543be57624e4e2234
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 9, 2026.
Transparency logSecurity for filings-cvm 0.26.9
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for filings_cvm-0.26.9.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 9, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
