Metadata-Version: 2.4
Name: filings-cvm
Version: 0.26.7
Summary: Simple and efficient Python library to interact with CVM regulatory filings.
License: MIT
License-File: LICENSE
Keywords: filings-cvm,python,library
Author: guilhermegor
Requires-Python: >=3.10,<4.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries
Requires-Dist: openpyxl (>=3.1.0)
Requires-Dist: pandas (>=2.1.0)
Requires-Dist: pydantic (>=2.6,<3)
Project-URL: Bug Reports, https://github.com/guilhermegor/filings-cvm/issues
Project-URL: Documentation, https://guilhermegor.github.io/filings-cvm/
Project-URL: Homepage, https://guilhermegor.github.io/filings-cvm/
Project-URL: Repository, https://github.com/guilhermegor/filings-cvm
Project-URL: Source, https://github.com/guilhermegor/filings-cvm
Description-Content-Type: text/markdown

# filings-cvm <img src="assets/cvm-logo.png" align="right" width="200" style="border-radius: 15px;" alt="filings-cvm">

[![Project Status: Active](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
![Python Version](https://img.shields.io/badge/python-3.10+-blue.svg)
![PyPI Version](https://img.shields.io/pypi/v/filings-cvm)
![PyPI Downloads](https://static.pepy.tech/badge/filings-cvm)
[![Linting](https://img.shields.io/badge/linting-ruff_|_codespell-blue)](https://github.com/astral-sh/ruff)
![Test Coverage](./coverage.svg)
![License](https://img.shields.io/badge/license-MIT-green.svg)
[![Docs](https://img.shields.io/badge/docs-mkdocs-blue)](https://guilhermegor.github.io/filings-cvm/)

Biblioteca Python **tipada** para os padrões de arquivo XML regulatórios da
[CVM](https://www.gov.br/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](https://docs.pydantic.dev/) 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:

```bash
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`](https://cvmweb.cvm.gov.br/SWB/Sistemas/SCW/PadroesXML/PadraoXMLPerfilV4.asp)) — `PerfilMensal` / `PerfilMensalDocument`
- ✅ **Informe Diário — V4** ([`PadraoXMLInfoDiarioNetV4.asp`](https://cvmweb.cvm.gov.br/SWB/Sistemas/SCW/PadroesXML/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.sh` no Git Bash / Windows)

### Instalação

**Como dependência:**

```bash
pip install filings-cvm
# ou
poetry add filings-cvm
```

**A partir do código-fonte:**

```bash
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

```python
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:

```python
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](https://guilhermegor.github.io/filings-cvm/usage/)**.

### Execução dos testes

```bash
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](docs/contributing.md) antes de abrir sua primeira branch. Fluxo
resumido:

```bash
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](docs/contributing.md#o-ruleset-pr-quality-gate-revisão-automática-e-proteção-da-branch).

## 👨‍💻 Autores

**Guilherme Rodrigues**

[![GitHub](https://img.shields.io/badge/GitHub-guilhermegor-181717?style=flat&logo=github)](https://github.com/guilhermegor)
[![LinkedIn](https://img.shields.io/badge/LinkedIn-Guilherme_Rodrigues-0077B5?style=flat&logo=linkedin)](https://www.linkedin.com/in/guilhermegor/)

## 📜 Licença

Este projeto é licenciado sob a Licença **MIT** — veja [LICENSE](LICENSE).

## 🙌 Agradecimentos

- Gerado a partir do template **lib-minimal** via [BlueprintX](https://github.com/guilhermegor/BlueprintX).

