layouts-cvm

Overview

Build, validate and serialise the files a fund sends to CVM, in CVM's own file layouts.

Source of truth. Field names, decimal scales and cardinalities come from the official CVM catalog of XML standards, not from this documentation. When the two disagree, the catalog wins; please open an issue.

• Direction: submission only (build, then send to CVM). Reading CVM files back is out of scope today.
• Coverage: the layouts in the table below are implemented. The rest are tracked as open writer issues, so they are planned, not forgotten.
• Decimals are truncated, never rounded (ROUND_DOWN): a value with more digits than the layout's scale loses the excess, so a reported figure is never inflated.
• CNPJ and CPF check digits are validated before anything is serialised.

Features

• Pydantic models for every CVM XML layout listed below, validated before anything is serialised.
• One writer per layout (export(doc, output_path=None)), producing windows-1252 XML.
• Byte-identical to the original filings-cvm writers, pinned by a golden-file test.
• Runtime dependencies: pydantic and beartype. No network.

Documentation

The documentation site lives at https://guilhermegor.github.io/layouts-cvm/. Serve it locally with bash bin/poe_exec.sh docs_serve.

Getting Started

Python 3.10+ is the only prerequisite; bin/venv.sh installs Poetry when it is missing.

Install

pip install layouts-cvm

Or from source:

git clone https://github.com/guilhermegor/layouts-cvm.git
cd layouts-cvm
bash bin/venv.sh
bash bin/poe_exec.sh init

poe lives inside the virtualenv, so bin/venv.sh creates it first; bin/poe_exec.sh then runs poe init without activating anything. Once the virtualenv exists, poetry run poe init does the same.

Usage

from layouts_cvm import InformeDiario

dict_payload = {
    "header": {"dt_compt": "15/01/2025", "dt_gerac_arq": "15/01/2025"},
    "informs": [
        {
            "cnpj_fdo": "11222333000181",
            "data_prox_pl": "16/01/2025",
            "vl_total": "0",
            "vl_quota": "0",
            "patrim_liq": "0",
            "captc_dia": "0",
            "resg_dia": "0",
            "vl_total_sai": "0",
            "vl_total_atv": "0",
            "nr_cotst": 0,
        }
    ],
}

xml = InformeDiario().export(dict_payload)                  # returns the XML text
InformeDiario().export(dict_payload, "informe_diario.xml")  # or writes it, atomically

The payload is plain data: the writer validates it against the layout's document model before serialising. The document models are private (layouts_cvm._internal) and not part of the public API; each layout's page in the documentation lists its fields.

Each layout has its own page under the Layouts section of the documentation.

Project Structure

layouts-cvm/
├── .github/        workflows, CODEOWNERS, PR template
├── .specs/         feature specs and backlog trackers
├── bin/            gate scripts and helpers
├── docs/           published documentation
├── src/layouts_cvm/
│   ├── <layout>.py one writer module per layout, exported in __init__.py
│   └── _internal/  private: config/schemas/ (the document models), utils/
├── tests/
│   ├── unit/
│   ├── integration/
│   └── golden/     byte-parity fixture against the original filings-cvm writers
├── pyproject.toml
└── poe_tasks.toml  task runner entry points

Development

After the bootstrap under Install, any task can be run with the bootstrap script: bash bin/poe_exec.sh <task>, and bash bin/poe_exec.sh with no task lists them.

bash bin/poe_exec.sh unit_tests
bash bin/poe_exec.sh integration_tests

Once the first release's docs deploy has created the gh-pages branch, run bash bin/poe_exec.sh enable_pages once: until that branch exists, init leaves Pages untouched.

Public API

The public surface is whatever the package __init__.py lists in __all__; everything under _internal/ is private. That surface is the writers: the document models live in _internal/config/schemas/ and a writer takes plain data (or a built model). The check-public-all-not-internal gate fails if __all__ ever exports a name defined there.

Publishing

Releases go out from the release workflows under .github/workflows/; the git tag is the version.

The path from 0.x to 1.0.0, and the release gate that guards it, is in docs/releasing-1-0-0.md.

Contributing

See CONTRIBUTING.md for the branch, commit and review rules.

License

This project is licensed under MIT; see LICENSE.

Authors

• Guilherme Rodrigues — GitHub | LinkedIn

Useful Links

• GitHub Repository
• Issue Tracker
• Documentation

_{Generated from the lib-minimal template via BlueprintX. Unofficial, community library. Not affiliated with or endorsed by the Comissão de Valores Mobiliários (CVM); the emblem is theirs and is not covered by this project's MIT license.}