filings-cvm 0.1.0__tar.gz

filings_cvm-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 guilhermegor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

filings_cvm-0.1.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: filings-cvm
+Version: 0.1.0
+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/logo_lorem_ipsum.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-${PYTHON_VERSIONS}-blue.svg)
+![PyPI Version](https://img.shields.io/pypi/v/${PYPI_NAME})
+[![Snyk Vulnerabilities](https://snyk.io/test/github/${GITHUB_USERNAME}/${PROJECT_SLUG}/badge.svg)](https://snyk.io/test/github/${GITHUB_USERNAME}/${PROJECT_SLUG})
+[![Snyk License](https://snyk.io/advisor/python/${PYPI_NAME}/badge.svg)](https://snyk.io/advisor/python/${PYPI_NAME})
+![PyPI Downloads](https://static.pepy.tech/badge/${PYPI_NAME})
+[![Linting](https://img.shields.io/badge/linting-ruff_|_codespell-blue)](https://github.com/astral-sh/ruff+https://github.com/codespell-project/codespell)
+![Formatting: isort](https://img.shields.io/badge/formatting-isort-%231674b1)
+![Test Coverage](./coverage.svg)
+![License](https://img.shields.io/badge/license-${PROJECT_LICENSE}-green.svg)
+![Open Issues](https://img.shields.io/github/issues/${GITHUB_USERNAME}/${PROJECT_SLUG})
+![Contributions Welcome](https://img.shields.io/badge/contributions-welcome-darkgreen.svg)
+
+${PROJECT_DESCRIPTION}
+
+## ✨ Key Features
+
+> Replace these placeholder groups with your project's actual capabilities.
+> Group features by domain or capability — one `###` heading per area.
+
+### 🧩 Capability Group 1
+- [Feature placeholder 1](${LINK_PLACEHOLDER})
+- [Feature placeholder 2](${LINK_PLACEHOLDER})
+- [Feature placeholder 3](${LINK_PLACEHOLDER})
+
+### 🧩 Capability Group 2
+- [Feature placeholder 4](${LINK_PLACEHOLDER})
+- [Feature placeholder 5](${LINK_PLACEHOLDER})
+- [Feature placeholder 6](${LINK_PLACEHOLDER})
+
+### ⚙️ Utilities
+- [Utility placeholder 1](${LINK_PLACEHOLDER})
+- [Utility placeholder 2](${LINK_PLACEHOLDER})
+
+## 🚀 Getting Started
+
+### Prerequisites
+- Python ${PYTHON_VERSIONS}
+- Poetry (recommended)
+- Optional: Makefile
+
+### Installation
+
+**Option 1: Pip (recommended)**
+```bash
+pip install ${PYPI_NAME}
+```
+
+**Option 2: Build from source**
+```bash
+git clone https://github.com/${GITHUB_USERNAME}/${PROJECT_SLUG}.git
+cd ${PROJECT_SLUG}
+pyenv install ${PYTHON_VERSION_PIN}
+pyenv local ${PYTHON_VERSION_PIN}
+poetry install --no-root
+poetry shell
+```
+
+**Make (optional automation)**
+- Windows: install via MinGW or Chocolatey
+- macOS: Xcode CLI tools or Homebrew
+- Linux: sudo apt-get install build-essential
+
+### Running Tests
+```bash
+poetry run pytest tests/unit/ -v
+poetry run pytest tests/integration/ -v
+```
+
+## 📂 Project Structure (template)
+```
+${PROJECT_SLUG}/
+├── .github/
+│   ├── workflows/
+│   ├── CODEOWNERS
+│   └── PULL_REQUEST_TEMPLATE.md
+├── .vscode/
+├── bin/
+│   ├── check_unix_filenames.sh
+│   ├── fix_playwright.sh
+│   ├── start.sh
+│   └── test_urls_docstrings.sh
+├── data/
+├── docs/
+├── examples/
+├── img/
+├── assets/
+│   └── logo.png
+├── src/${PACKAGE_IMPORT_PATH}/
+├── tests/
+│   ├── unit/
+│   ├── integration/
+│   └── performance/
+├── .gitignore
+├── .pre-commit-config.yaml
+├── .python-version
+├── LICENSE
+├── Makefile
+├── poetry.lock
+├── pyproject.toml
+├── README.md
+├── requirements.txt
+└── requirements-prd.txt
+```
+
+## 👨‍💻 Authors
+- ${AUTHOR_NAME} — [GitHub](https://github.com/${GITHUB_USERNAME}) | [LinkedIn](${LINKEDIN_URL})
+
+## 📜 License
+This project is licensed under ${PROJECT_LICENSE}. Update this section if you use a different license.
+
+## 🙌 Acknowledgments
+- Inspired by relevant open-source work.
+- Thank contributors and the community.
+
+## 🔗 Useful Links
+- [GitHub Repository](https://github.com/${GITHUB_USERNAME}/${PROJECT_SLUG})
+- [Issue Tracker](https://github.com/${GITHUB_USERNAME}/${PROJECT_SLUG}/issues)
+

filings_cvm-0.1.0/README.md

@@ -0,0 +1,120 @@
+# Filings Cvm <img src="assets/logo_lorem_ipsum.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-${PYTHON_VERSIONS}-blue.svg)
+![PyPI Version](https://img.shields.io/pypi/v/${PYPI_NAME})
+[![Snyk Vulnerabilities](https://snyk.io/test/github/${GITHUB_USERNAME}/${PROJECT_SLUG}/badge.svg)](https://snyk.io/test/github/${GITHUB_USERNAME}/${PROJECT_SLUG})
+[![Snyk License](https://snyk.io/advisor/python/${PYPI_NAME}/badge.svg)](https://snyk.io/advisor/python/${PYPI_NAME})
+![PyPI Downloads](https://static.pepy.tech/badge/${PYPI_NAME})
+[![Linting](https://img.shields.io/badge/linting-ruff_|_codespell-blue)](https://github.com/astral-sh/ruff+https://github.com/codespell-project/codespell)
+![Formatting: isort](https://img.shields.io/badge/formatting-isort-%231674b1)
+![Test Coverage](./coverage.svg)
+![License](https://img.shields.io/badge/license-${PROJECT_LICENSE}-green.svg)
+![Open Issues](https://img.shields.io/github/issues/${GITHUB_USERNAME}/${PROJECT_SLUG})
+![Contributions Welcome](https://img.shields.io/badge/contributions-welcome-darkgreen.svg)
+
+${PROJECT_DESCRIPTION}
+
+## ✨ Key Features
+
+> Replace these placeholder groups with your project's actual capabilities.
+> Group features by domain or capability — one `###` heading per area.
+
+### 🧩 Capability Group 1
+- [Feature placeholder 1](${LINK_PLACEHOLDER})
+- [Feature placeholder 2](${LINK_PLACEHOLDER})
+- [Feature placeholder 3](${LINK_PLACEHOLDER})
+
+### 🧩 Capability Group 2
+- [Feature placeholder 4](${LINK_PLACEHOLDER})
+- [Feature placeholder 5](${LINK_PLACEHOLDER})
+- [Feature placeholder 6](${LINK_PLACEHOLDER})
+
+### ⚙️ Utilities
+- [Utility placeholder 1](${LINK_PLACEHOLDER})
+- [Utility placeholder 2](${LINK_PLACEHOLDER})
+
+## 🚀 Getting Started
+
+### Prerequisites
+- Python ${PYTHON_VERSIONS}
+- Poetry (recommended)
+- Optional: Makefile
+
+### Installation
+
+**Option 1: Pip (recommended)**
+```bash
+pip install ${PYPI_NAME}
+```
+
+**Option 2: Build from source**
+```bash
+git clone https://github.com/${GITHUB_USERNAME}/${PROJECT_SLUG}.git
+cd ${PROJECT_SLUG}
+pyenv install ${PYTHON_VERSION_PIN}
+pyenv local ${PYTHON_VERSION_PIN}
+poetry install --no-root
+poetry shell
+```
+
+**Make (optional automation)**
+- Windows: install via MinGW or Chocolatey
+- macOS: Xcode CLI tools or Homebrew
+- Linux: sudo apt-get install build-essential
+
+### Running Tests
+```bash
+poetry run pytest tests/unit/ -v
+poetry run pytest tests/integration/ -v
+```
+
+## 📂 Project Structure (template)
+```
+${PROJECT_SLUG}/
+├── .github/
+│   ├── workflows/
+│   ├── CODEOWNERS
+│   └── PULL_REQUEST_TEMPLATE.md
+├── .vscode/
+├── bin/
+│   ├── check_unix_filenames.sh
+│   ├── fix_playwright.sh
+│   ├── start.sh
+│   └── test_urls_docstrings.sh
+├── data/
+├── docs/
+├── examples/
+├── img/
+├── assets/
+│   └── logo.png
+├── src/${PACKAGE_IMPORT_PATH}/
+├── tests/
+│   ├── unit/
+│   ├── integration/
+│   └── performance/
+├── .gitignore
+├── .pre-commit-config.yaml
+├── .python-version
+├── LICENSE
+├── Makefile
+├── poetry.lock
+├── pyproject.toml
+├── README.md
+├── requirements.txt
+└── requirements-prd.txt
+```
+
+## 👨‍💻 Authors
+- ${AUTHOR_NAME} — [GitHub](https://github.com/${GITHUB_USERNAME}) | [LinkedIn](${LINKEDIN_URL})
+
+## 📜 License
+This project is licensed under ${PROJECT_LICENSE}. Update this section if you use a different license.
+
+## 🙌 Acknowledgments
+- Inspired by relevant open-source work.
+- Thank contributors and the community.
+
+## 🔗 Useful Links
+- [GitHub Repository](https://github.com/${GITHUB_USERNAME}/${PROJECT_SLUG})
+- [Issue Tracker](https://github.com/${GITHUB_USERNAME}/${PROJECT_SLUG}/issues)

filings_cvm-0.1.0/pyproject.toml

@@ -0,0 +1,95 @@
+[tool.poetry]
+name = "filings-cvm"
+# The version source depends on how this project was scaffolded. OFFLINE (no remote): this static
+# version, hand-bumped via `make bump_version`. ONLINE (GitHub remote): the scaffold rewrote this
+# to a "0.0.0" stub + poetry-dynamic-versioning, so the published version comes from the git tag
+# (vX.Y.Z) and `make bump_version` is removed (the CI release workflows cut releases by tagging).
+version = "0.1.0"
+description = "Simple and efficient Python library to interact with CVM regulatory filings."
+authors = ["guilhermegor"]
+readme = "README.md"
+license = "MIT"
+homepage = "https://guilhermegor.github.io/filings-cvm/"
+documentation = "https://guilhermegor.github.io/filings-cvm/"
+repository = "https://github.com/guilhermegor/filings-cvm"
+keywords = ["filings-cvm", "python", "library"]
+packages = [{ include = "filings_cvm", from = "src" }]
+# Keep internal dev docs out of the distributed wheel/sdist.
+exclude = ["src/**/CLAUDE.md"]
+package-mode = true
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "License :: OSI Approved :: MIT License",
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries",
+]
+
+[tool.poetry.urls]
+"Bug Reports" = "https://github.com/guilhermegor/filings-cvm/issues"
+"Source" = "https://github.com/guilhermegor/filings-cvm"
+"Documentation" = "https://guilhermegor.github.io/filings-cvm/"
+
+[tool.commitizen]
+# Conventional-commit driven changelog. The version comes from the git tag
+# (poetry-dynamic-versioning); `cz changelog` (via `make changelog`) groups commits by tag.
+# Releases are cut by the CI release workflows (tag -> build -> publish), not a hand-run bump.
+name = "cz_conventional_commits"
+version_provider = "poetry"
+tag_format = "v"
+update_changelog_on_bump = true
+
+[tool.poetry.dependencies]
+python = ">=3.10,<4.0"
+# Required by the private _internal helpers (dtypes / tabular_reader / config.contracts).
+pandas = ">=2.1.0"
+openpyxl = ">=3.1.0"
+# Schema validation for the CVM XML standards (submission/ingestion sections).
+pydantic = ">=2.6,<3"
+
+[tool.poetry.group.dev.dependencies]
+pre-commit = ">=4.1.0"
+pretty-errors = ">=1.2.25"
+commitizen = ">=4.4.1"
+poetry-plugin-export = ">=1.8"
+# Build + publish tooling for the PyPI / Test-PyPI release workflows (twine is the
+# publish fallback when `poetry publish` is unavailable).
+build = ">=1.2.2"
+twine = ">=6.1.0"
+# Pinned to the ruff-pre-commit hook minor (.pre-commit-config.yaml) so `make
+# lint` and the hook never disagree on formatting/lints.
+ruff = ">=0.11.13,<0.12"
+codespell = ">=2.4.1"
+pydocstyle = ">=6.3.0"
+pytest = ">=8.0.0"
+pytest-cov = ">=6.0.0"
+coverage = ">=7.6.0"
+# genbadge replaces the abandoned coverage-badge (it imported the removed
+# pkg_resources and breaks on setuptools >= 81).
+genbadge = {extras = ["coverage"], version = ">=1.1.0"}
+# Static type-checker + non-Python lint gates (mirrored in .pre-commit-config and
+# `make lint`). shellcheck + shfmt are pip dev-deps (shellcheck-py/shfmt-py); lint_shell.sh resolves them via poetry run, falls back to a system binary, then skips.
+mypy = ">=1.8.0"
+sqlfluff = ">=3.0.0"
+yamllint = ">=1.35.0"
+shfmt-py = ">=3.7.0"
+shellcheck-py = ">=0.10.0"
+
+[tool.poetry.group.docs.dependencies]
+mkdocs = ">=1.6.0"
+mkdocs-material = ">=9.5.0"
+pymdown-extensions = ">=10.0"
+
+[tool.poetry-dynamic-versioning]
+# Published version is derived from the latest git tag matching `v$version` (e.g. v0.2.0). On
+# an exact tag the build is clean (0.2.0); off-tag builds get a PEP 440 dev version. The CI
+# release workflows pass POETRY_DYNAMIC_VERSIONING_BYPASS to build a specific version. Needs
+# `python -m build` (a PEP 517 frontend), not `poetry build` (which ignores the backend).
+enable = false
+vcs = "git"
+style = "pep440"
+
+[build-system]
+requires = ["poetry-core>=1.7.0", "poetry-dynamic-versioning>=1.4.0,<2.0.0"]
+build-backend = "poetry_dynamic_versioning.backend"

filings_cvm-0.1.0/src/filings_cvm/__init__.py

@@ -0,0 +1,22 @@
+"""filings-cvm — typed access to CVM regulatory XML file standards.
+
+Two macro-sections organise every solution:
+
+- ``filings_cvm.submission`` — build and serialise files to *send* to CVM (envio).
+- ``filings_cvm.ingestion`` — parse and interpret files *received* from CVM (leitura).
+
+See the CVM XML Standards catalog in ``CLAUDE.md`` for the full source of truth.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from filings_cvm.submission import PerfilMensal, PerfilMensalDocument
+
+
+try:
+	__version__ = version("filings-cvm")
+except PackageNotFoundError:  # pragma: no cover - source tree without an installed dist
+	__version__ = "0.0.0"
+
+
+__all__ = ["PerfilMensal", "PerfilMensalDocument", "__version__"]

filings_cvm-0.1.0/src/filings_cvm/_internal/__init__.py

@@ -0,0 +1 @@
+"""Private internals of the filings-cvm package (not a public API)."""

filings_cvm-0.1.0/src/filings_cvm/_internal/config/__init__.py

@@ -0,0 +1 @@
+"""Private configuration internals (data contracts) of filings-cvm."""

filings_cvm-0.1.0/src/filings_cvm/_internal/config/contracts/__init__.py

@@ -0,0 +1,27 @@
+"""Data contracts for the project's input files (config layer).
+
+A contract is **declarative configuration** of an input's expected shape — which columns a
+source must carry, which must hold valid CNPJs — *not* data access, so contracts live in
+``config`` beside the other declarative config (``inputs.yaml``, ``connection_db``), imported
+by the model loaders and the controller boundary.
+
+Convention: **one file per source** under this package (``cadastro.py``, ``orders.py``, …),
+each defining a single ``FileContract`` instance; this aggregator re-exports them (plus the
+machinery from ``utils.tabular_reader``) so callers import from one place:
+``from config.contracts import EXAMPLE_SOURCE, find_file_problems``.
+
+``EXAMPLE_SOURCE`` is a reference instance — copy ``example_source.py`` per real source and
+delete the example once your own contracts exist.
+"""
+
+from __future__ import annotations
+
+from filings_cvm._internal.config.contracts.example_source import EXAMPLE_SOURCE
+from filings_cvm._internal.utils.tabular_reader import (
+	ContractError,
+	FileContract,
+	find_file_problems,
+)
+
+
+__all__ = ["EXAMPLE_SOURCE", "ContractError", "FileContract", "find_file_problems"]

filings_cvm-0.1.0/src/filings_cvm/_internal/config/contracts/example_source.py

@@ -0,0 +1,20 @@
+"""Reference data contract — copy this per real input source, then delete the example.
+
+Declares the columns the file must carry (``tuple_required``) and the columns that must hold
+at least one valid CNPJ (``tuple_cnpj_cols``). The model/controller passes this instance to
+``utils.tabular_reader.read_table`` / ``read_query``, which raises ``ContractError`` on any
+violation before types are applied.
+"""
+
+from __future__ import annotations
+
+from filings_cvm._internal.utils.tabular_reader import FileContract
+
+
+# str_name (human label), str_source_key (routes notifications), tuple_required, tuple_cnpj_cols.
+EXAMPLE_SOURCE = FileContract(
+	"Example Source",
+	"example_source",
+	("code", "amount"),
+	(),
+)

filings_cvm-0.1.0/src/filings_cvm/_internal/schemas/__init__.py

@@ -0,0 +1,40 @@
+"""Shared XML-standard schemas (Pydantic models) for the CVM file standards.
+
+Direction-neutral contracts consumed by both the ``submission`` section (models →
+XML) and the future ``ingestion`` section (XML → models). One module per CVM
+standard. Ships in the wheel under ``_internal``; the public API is curated by the
+``submission``/``ingestion`` packages, which re-export the names consumers need.
+"""
+
+from filings_cvm._internal.schemas.perfil_mensal import (
+	ClientCount,
+	DocumentHeader,
+	NominalRiskBlock,
+	NominalRiskFactor,
+	OtcOperation,
+	PatrimonyDistribution,
+	PerfilMensalDocument,
+	PerfilMensalRow,
+	PerformanceFeeDetails,
+	PrimitiveRiskFactor,
+	PrivateCreditIssuer,
+	VarOutros,
+	VarPercValCota,
+)
+
+
+__all__ = [
+	"ClientCount",
+	"DocumentHeader",
+	"NominalRiskBlock",
+	"NominalRiskFactor",
+	"OtcOperation",
+	"PatrimonyDistribution",
+	"PerfilMensalDocument",
+	"PerfilMensalRow",
+	"PerformanceFeeDetails",
+	"PrimitiveRiskFactor",
+	"PrivateCreditIssuer",
+	"VarOutros",
+	"VarPercValCota",
+]