layouts-cvm 0.1.0__py3-none-any.whl

layouts_cvm/__init__.py

@@ -0,0 +1,415 @@
+"""layouts-cvm — CVM submission (envio) layouts.
+
+Submission section — build and serialise files to *send* to CVM (envio).
+
+Every "envio" solution lives here: it takes validated schema models (or a filled
+spreadsheet) and produces a CVM-compliant file ready to submit. The reading/parsing
+counterpart lives in the ``ingestion`` section.
+
+The shared XML-standard models are re-exported here so callers construct documents
+and serialise them through a single import:
+
+    from layouts_cvm import PerfilMensal, PerfilMensalDocument
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from layouts_cvm.cadastro_ativos import (
+    CadastroAtivos,
+)
+from layouts_cvm.cda import (
+    Cda,
+)
+from layouts_cvm.extrato import Extrato
+from layouts_cvm.inf_fundo_157 import InfFundo157
+from layouts_cvm.inf_mensal_fidc import (
+    InfMensalFidc,
+)
+from layouts_cvm.informe_diario import (
+    InformeDiario,
+)
+from layouts_cvm.informe_diario_v3 import InformeDiarioV3
+from layouts_cvm.informe_portabilidade import InformePortabilidade
+from layouts_cvm.informe_quadrimestral import InformeQuadrimestral
+from layouts_cvm.informe_trimestral_v1 import InformeTrimestralV1
+from layouts_cvm.inr_mensal import InrMensal
+from layouts_cvm.lamina import Lamina
+from layouts_cvm.main import main
+from layouts_cvm.perfil_mensal import (
+    PerfilMensal,
+)
+from layouts_cvm.perfil_mensal_original import PerfilMensalOriginal
+from layouts_cvm.schemas.cadastro_ativos import (
+    CadastroAtivosDocument,
+    CadastroAtivosHeader,
+    CadastroAtivosRow,
+)
+from layouts_cvm.schemas.cda import (
+    CdaAplic,
+    CdaAtivoExt,
+    CdaBankEmitter,
+    CdaCotas,
+    CdaDemaisCodif,
+    CdaDemaisNCodif,
+    CdaDepPrazoTitIf,
+    CdaDocument,
+    CdaEmitter,
+    CdaHeader,
+    CdaInform,
+    CdaInvExt,
+    CdaNegoc,
+    CdaPosFim,
+    CdaPosFixIndex,
+    CdaRiskRating,
+    CdaSwap,
+    CdaSwapAplic,
+    CdaSwapPosFim,
+    CdaTitAgroCredPriv,
+    CdaTitPub,
+)
+from layouts_cvm.schemas.extrato import (
+    ExtratoDocument,
+    ExtratoHeader,
+    ExtratoRow,
+)
+from layouts_cvm.schemas.inf_fundo_157 import (
+    InfFundo157Cotista,
+    InfFundo157Document,
+    InfFundo157Header,
+)
+from layouts_cvm.schemas.inf_mensal_fidc import (
+    Alienacao,
+    Amort,
+    Amortizacao,
+    AplicAtivo,
+    CaptaResgaAmorti,
+    CaptMes,
+    CartSegmt,
+    Cedent,
+    CedentCredExiste,
+    ClasseCotistas,
+    CompmtDicred,
+    CotasMovimento,
+    CotistasPorTipo,
+    CredExiste,
+    DescSerieClasse,
+    Desemp,
+    DesempClasse,
+    DevSacado,
+    Dicred,
+    Garantia,
+    InfMensalFidcDocument,
+    InfMensalFidcHeader,
+    InfMensalFidcInform,
+    InformSacados,
+    Liquidez,
+    ListaCedent,
+    ListaCedentCredExiste,
+    ListaDevSacados,
+    MercDerivativo,
+    NegocDicredMes,
+    NumCotistas,
+    NumCotistasDesc,
+    OutrasInform,
+    OutrosAtivos,
+    Passiv,
+    PassivPosicoes,
+    PassivValores,
+    Patrliq,
+    QtVl,
+    RentClasse,
+    RentMes,
+    ResgMes,
+    ResgSolic,
+    SegmtComerc,
+    SegmtFact,
+    SegmtFinanc,
+    SegmtServ,
+    SegmtSetorPublic,
+    SerieClasse,
+    Taxa,
+    TaxaAquis,
+    TaxaAtivRf,
+    TaxaCdb,
+    TaxaNegocDicredMes,
+    TaxaSemAquis,
+    TaxaTitpubFed,
+    TaxaValorMobili,
+    ValoresMob,
+)
+from layouts_cvm.schemas.informe_diario import (
+    InformeDiarioDocument,
+    InformeDiarioHeader,
+    InformeDiarioInform,
+    SignificantShareholder,
+)
+from layouts_cvm.schemas.informe_diario_v3 import (
+    InformeDiarioV3Document,
+    InformeDiarioV3Header,
+    InformeDiarioV3Inform,
+)
+from layouts_cvm.schemas.informe_portabilidade import (
+    InformePortabilidadeDocument,
+    PortabilidadeHeader,
+    PortabilidadeInform,
+)
+from layouts_cvm.schemas.informe_quadrimestral import (
+    ClasseCotas,
+    CotistCategory,
+    InformeQuadrimestralDocument,
+    InformeQuadrimestralHeader,
+    InformeQuadrimestralInform,
+    ListaClasseCotas,
+    ListaCotstCateg,
+)
+from layouts_cvm.schemas.informe_trimestral_v1 import (
+    InformeTrimestralV1Document,
+    InformeTrimestralV1Header,
+    InformeTrimestralV1Inform,
+)
+from layouts_cvm.schemas.inr_mensal import (
+    Aplicacoes,
+    EntradaSaida,
+    InrMensalDocument,
+    InrMensalHeader,
+    MovRecursos,
+    Participante,
+    RecursosEnvMesmoInvest,
+    RecursosEnvOutroInvest,
+    RecursosMesmoInvest,
+    RecursosOutroInvest,
+    RecursosRecebMesmoInvest,
+    RecursosRecebOutroInvest,
+    TransfRecursos,
+)
+from layouts_cvm.schemas.lamina import (
+    LaminaAntesInic2,
+    LaminaCarencia,
+    LaminaCompCarteira,
+    LaminaConversao,
+    LaminaDespesas,
+    LaminaDocument,
+    LaminaHeader,
+    LaminaInform,
+    LaminaInformExemploComp,
+    LaminaInforTabRentAnual,
+    LaminaListaCompCarteira,
+    LaminaListaTabRentAnual,
+    LaminaListaTabRentMensal,
+    LaminaTabRentAnual,
+    LaminaTabRentMensal,
+    LaminaTabSimulDespesas,
+    LaminaTabVarDesemp,
+    LaminaTaxaAdministracao,
+    LaminaTaxaEntrada,
+    LaminaTaxaSaida,
+)
+from layouts_cvm.schemas.perfil_mensal import (
+    ClientCount,
+    DocumentHeader,
+    NominalRiskBlock,
+    NominalRiskFactor,
+    OtcOperation,
+    PatrimonyDistribution,
+    PerfilMensalDocument,
+    PerfilMensalRow,
+    PerformanceFeeDetails,
+    PrimitiveRiskFactor,
+    PrivateCreditIssuer,
+    VarOutros,
+    VarPercValCota,
+)
+from layouts_cvm.schemas.perfil_mensal_original import (
+    PerfilMensalOriginalClientCount,
+    PerfilMensalOriginalDocument,
+    PerfilMensalOriginalHeader,
+    PerfilMensalOriginalPatrimonyDistribution,
+    PerfilMensalOriginalRow,
+    PerfilMensalOriginalTradingDays,
+)
+
+
+try:
+    __version__ = version("layouts-cvm")
+except PackageNotFoundError:  # pragma: no cover - source tree without an installed dist
+    __version__ = "0.0.0"
+
+
+__all__ = [
+    "__version__",
+    "main",
+    "Alienacao",
+    "Amort",
+    "Amortizacao",
+    "AplicAtivo",
+    "Aplicacoes",
+    "CadastroAtivos",
+    "CadastroAtivosDocument",
+    "CadastroAtivosHeader",
+    "CadastroAtivosRow",
+    "CaptMes",
+    "CaptaResgaAmorti",
+    "CartSegmt",
+    "Cda",
+    "CdaAplic",
+    "CdaAtivoExt",
+    "CdaBankEmitter",
+    "CdaCotas",
+    "CdaDemaisCodif",
+    "CdaDemaisNCodif",
+    "CdaDepPrazoTitIf",
+    "CdaDocument",
+    "CdaEmitter",
+    "CdaHeader",
+    "CdaInform",
+    "CdaInvExt",
+    "CdaNegoc",
+    "CdaPosFim",
+    "CdaPosFixIndex",
+    "CdaRiskRating",
+    "CdaSwap",
+    "CdaSwapAplic",
+    "CdaSwapPosFim",
+    "CdaTitAgroCredPriv",
+    "CdaTitPub",
+    "Cedent",
+    "CedentCredExiste",
+    "ClasseCotas",
+    "ClasseCotistas",
+    "ClientCount",
+    "CompmtDicred",
+    "CotasMovimento",
+    "CotistCategory",
+    "CotistasPorTipo",
+    "CredExiste",
+    "DescSerieClasse",
+    "Desemp",
+    "DesempClasse",
+    "DevSacado",
+    "Dicred",
+    "DocumentHeader",
+    "EntradaSaida",
+    "Extrato",
+    "ExtratoDocument",
+    "ExtratoHeader",
+    "ExtratoRow",
+    "Garantia",
+    "InfFundo157",
+    "InfFundo157Cotista",
+    "InfFundo157Document",
+    "InfFundo157Header",
+    "InfMensalFidc",
+    "InfMensalFidcDocument",
+    "InfMensalFidcHeader",
+    "InfMensalFidcInform",
+    "InformSacados",
+    "InformeDiario",
+    "InformeDiarioDocument",
+    "InformeDiarioHeader",
+    "InformeDiarioInform",
+    "InformeDiarioV3",
+    "InformeDiarioV3Document",
+    "InformeDiarioV3Header",
+    "InformeDiarioV3Inform",
+    "InformePortabilidade",
+    "InformePortabilidadeDocument",
+    "InformeQuadrimestral",
+    "InformeQuadrimestralDocument",
+    "InformeQuadrimestralHeader",
+    "InformeQuadrimestralInform",
+    "InformeTrimestralV1",
+    "InformeTrimestralV1Document",
+    "InformeTrimestralV1Header",
+    "InformeTrimestralV1Inform",
+    "InrMensal",
+    "InrMensalDocument",
+    "InrMensalHeader",
+    "Lamina",
+    "LaminaAntesInic2",
+    "LaminaCarencia",
+    "LaminaCompCarteira",
+    "LaminaConversao",
+    "LaminaDespesas",
+    "LaminaDocument",
+    "LaminaHeader",
+    "LaminaInforTabRentAnual",
+    "LaminaInform",
+    "LaminaInformExemploComp",
+    "LaminaListaCompCarteira",
+    "LaminaListaTabRentAnual",
+    "LaminaListaTabRentMensal",
+    "LaminaTabRentAnual",
+    "LaminaTabRentMensal",
+    "LaminaTabSimulDespesas",
+    "LaminaTabVarDesemp",
+    "LaminaTaxaAdministracao",
+    "LaminaTaxaEntrada",
+    "LaminaTaxaSaida",
+    "Liquidez",
+    "ListaCedent",
+    "ListaCedentCredExiste",
+    "ListaClasseCotas",
+    "ListaCotstCateg",
+    "ListaDevSacados",
+    "MercDerivativo",
+    "MovRecursos",
+    "NegocDicredMes",
+    "NominalRiskBlock",
+    "NominalRiskFactor",
+    "NumCotistas",
+    "NumCotistasDesc",
+    "OtcOperation",
+    "OutrasInform",
+    "OutrosAtivos",
+    "Participante",
+    "Passiv",
+    "PassivPosicoes",
+    "PassivValores",
+    "PatrimonyDistribution",
+    "Patrliq",
+    "PerfilMensal",
+    "PerfilMensalDocument",
+    "PerfilMensalOriginal",
+    "PerfilMensalOriginalClientCount",
+    "PerfilMensalOriginalDocument",
+    "PerfilMensalOriginalHeader",
+    "PerfilMensalOriginalPatrimonyDistribution",
+    "PerfilMensalOriginalRow",
+    "PerfilMensalOriginalTradingDays",
+    "PerfilMensalRow",
+    "PerformanceFeeDetails",
+    "PortabilidadeHeader",
+    "PortabilidadeInform",
+    "PrimitiveRiskFactor",
+    "PrivateCreditIssuer",
+    "QtVl",
+    "RecursosEnvMesmoInvest",
+    "RecursosEnvOutroInvest",
+    "RecursosMesmoInvest",
+    "RecursosOutroInvest",
+    "RecursosRecebMesmoInvest",
+    "RecursosRecebOutroInvest",
+    "RentClasse",
+    "RentMes",
+    "ResgMes",
+    "ResgSolic",
+    "SegmtComerc",
+    "SegmtFact",
+    "SegmtFinanc",
+    "SegmtServ",
+    "SegmtSetorPublic",
+    "SerieClasse",
+    "SignificantShareholder",
+    "Taxa",
+    "TaxaAquis",
+    "TaxaAtivRf",
+    "TaxaCdb",
+    "TaxaNegocDicredMes",
+    "TaxaSemAquis",
+    "TaxaTitpubFed",
+    "TaxaValorMobili",
+    "TransfRecursos",
+    "ValoresMob",
+    "VarOutros",
+    "VarPercValCota",
+]

layouts_cvm/_internal/__init__.py

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

layouts_cvm/_internal/config/__init__.py

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

layouts_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 layouts_cvm._internal.config.contracts.example_source import EXAMPLE_SOURCE
+from layouts_cvm._internal.utils.tabular_reader import (
+    ContractError,
+    FileContract,
+    find_file_problems,
+)
+
+
+__all__ = ["EXAMPLE_SOURCE", "ContractError", "FileContract", "find_file_problems"]

layouts_cvm/_internal/config/contracts/example_source.py

@@ -0,0 +1,25 @@
+"""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.
+
+⚠️ Before copying this file for a real source, **confirm which document is the contract and
+get the owner's sign-off** — writing a reader against the wrong spec produces a file that
+parses cleanly and carries the wrong columns, which no test here can catch. The reasoning is
+in BlueprintX's ``templates/python-common/src/config/contracts/CLAUDE.md`` (upstream; not
+copied into generated projects — blueprintx#325).
+"""
+
+from __future__ import annotations
+
+from layouts_cvm._internal.utils.tabular_reader import FileContract
+
+
+EXAMPLE_SOURCE = FileContract(
+    "Example Source",
+    "example_source",
+    ("code", "amount"),
+    (),
+)

layouts_cvm/_internal/config/ports/__init__.py

@@ -0,0 +1,7 @@
+"""Ports - the behavioural boundary interfaces of the library (hexagonal, private)."""
+
+from layouts_cvm._internal.config.ports.example_port import ExamplePort
+from layouts_cvm._internal.config.ports.submission_writer import SubmissionWriter, TDoc
+
+
+__all__ = ["ExamplePort", "SubmissionWriter", "TDoc"]

layouts_cvm/_internal/config/ports/example_port.py

@@ -0,0 +1,63 @@
+"""Reference behavioural port — copy this per real macro-section operation, then delete it.
+
+In hexagonal *ports-and-adapters* terms this ABC is a **port**: it pins the single operation
+that a family of concrete classes (the *adapters*) all implement, so callers can treat any
+adapter polymorphically and every new variant conforms to the same shape. It is private
+(``_internal``): consumers import the concrete adapters, never this port.
+
+The port is generic over ``_T`` (the value it operates on) so an adapter narrows the type
+through the type parameter — e.g. ``class CsvHandler(ExamplePort[pd.DataFrame])`` — rather than
+by re-annotating the override, keeping the concrete signature Liskov-compatible. ``_T`` is
+unbounded here; bind it (``TypeVar("_T", bound=BaseModel)``) when every adapter shares a base.
+
+The leading underscore is deliberate: an adapter parameterises the port
+(``ExamplePort[pd.DataFrame]``) and never imports the type variable by name, so ``_T`` is an
+implementation detail of this module — the same convention the typeshed stubs use. Naming it
+``T`` made it a public member this package's ``__all__`` did not export, which
+``bin/check_all_exports.py`` correctly rejects (blueprintx#246).
+"""
+
+from __future__ import annotations
+
+from abc import abstractmethod
+from typing import Generic, TypeVar
+
+from layouts_cvm._internal.utils.typing import ABCTypeCheckerMeta
+
+
+_T = TypeVar("_T")
+
+
+class ExamplePort(Generic[_T], metaclass=ABCTypeCheckerMeta):
+    """Contract for one behavioural operation shared across a macro-section's adapters.
+
+    ``ABCTypeCheckerMeta`` gives both abstract-method enforcement (a partial adapter fails at
+    instantiation) and runtime type checking of every call. Concrete adapters inherit the port
+    and its metaclass — do **not** redeclare ``metaclass`` on a subclass; Python inherits it.
+
+    Methods
+    -------
+    handle(item)
+            Perform the port's single operation on ``item`` and return the result.
+    """
+
+    @abstractmethod
+    def handle(self, item: _T) -> _T:
+        """Perform the operation on ``item`` and return the result.
+
+        Parameters
+        ----------
+        item : _T
+            The value the concrete adapter operates on.
+
+        Returns
+        -------
+        _T
+            The operation's result.
+
+        Raises
+        ------
+        NotImplementedError
+            Always — a concrete adapter must override this method.
+        """
+        raise NotImplementedError

layouts_cvm/_internal/config/ports/submission_writer.py

@@ -0,0 +1,59 @@
+"""Submission writer port — the shared contract every *envio* writer (adapter) implements.
+
+Every ``submission`` solution turns a validated schema document into a CVM-compliant
+file to send to CVM. This ABC is the **port** (hexagonal ports-and-adapters) pinning that
+single operation — :meth:`export` — so callers can treat any writer polymorphically and
+every new standard implements the same shape. It is private (``_internal``): consumers
+import the concrete writers (the adapters), never this port.
+
+The document type varies per standard, so the port is generic over ``TDoc`` (bound
+to :class:`pydantic.BaseModel`): a concrete writer conforms by parameterising it, e.g.
+``class InformeDiario(SubmissionWriter[InformeDiarioDocument])``. This narrows the
+document type through the type parameter rather than by re-annotating an override, so
+the concrete signature stays Liskov-compatible.
+
+CVM's submission standards are all XML today, so :meth:`export` produces XML; the generic
+name leaves room for a future non-XML export without changing the contract.
+"""
+
+from __future__ import annotations
+
+from abc import abstractmethod
+from typing import Generic, TypeVar
+
+from pydantic import BaseModel
+
+from layouts_cvm._internal.utils.typing import ABCTypeCheckerMeta
+
+
+TDoc = TypeVar("TDoc", bound=BaseModel)
+
+
+class SubmissionWriter(Generic[TDoc], metaclass=ABCTypeCheckerMeta):
+    """Contract for a submission (envio) writer: validated document → CVM file.
+
+    Methods
+    -------
+    export(doc, output_path)
+            Serialise a validated document to a CVM-compliant file string, optionally
+            writing it to ``output_path``.
+    """
+
+    @abstractmethod
+    def export(self, doc: TDoc, output_path: str | None = None) -> str | None:
+        """Serialise ``doc`` to a CVM-compliant file (string, or written to disk).
+
+        Parameters
+        ----------
+        doc : TDoc
+                Fully validated document model for the standard.
+        output_path : str, optional
+                Destination file path. When given, the file is written and ``None`` is
+                returned; otherwise the serialised string is returned. By default ``None``.
+
+        Returns
+        -------
+        str or None
+                The serialised content when ``output_path`` is ``None``, else ``None``.
+        """
+        raise NotImplementedError

layouts_cvm/_internal/utils/__init__.py

@@ -0,0 +1 @@
+"""Shared, project-agnostic utility helpers (copied into every Python skeleton)."""

layouts_cvm/_internal/utils/atomic_write.py

@@ -0,0 +1,95 @@
+"""Atomic file output for the submission writers.
+
+A writer's destination must always be either the previous file or the complete new one,
+never a partial write left behind by an I/O fault.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+from pathlib import Path
+import secrets
+
+from layouts_cvm._internal.utils.typing import type_checker
+
+
+@type_checker
+def atomic_write_bytes(path: str | Path, payload: bytes) -> None:
+    """Write ``payload`` to ``path`` atomically.
+
+    The bytes go to a temp file in the destination's own directory (so ``os.replace`` stays
+    on one filesystem), are flushed and fsynced, then replace the target. If the write,
+    fsync or replace fails, the temp file is removed and a pre-existing target is left
+    untouched. The directory fsync runs after the replace: if it fails, the new file is
+    already in place and ``OSError`` is still raised.
+
+    The caller therefore needs write permission on the destination's parent directory, not
+    only on an existing target file. A pre-existing target keeps its permission bits; a new
+    file gets the mode a plain ``open()`` would give (``0o666`` minus the umask).
+
+    Parameters
+    ----------
+    path : str | Path
+            Destination file path.
+    payload : bytes
+            Exact bytes to write.
+
+    Raises
+    ------
+    OSError
+            If the write, fsync or replace fails, or if the directory fsync fails after the
+            replace (the target then already holds the new payload).
+    """
+    path_dest = Path(path)
+    path_tmp = path_dest.with_name(f".{path_dest.name}.{secrets.token_hex(8)}.tmp")
+    flags = os.O_CREAT | os.O_EXCL | os.O_WRONLY | getattr(os, "O_BINARY", 0)
+    fd = os.open(path_tmp, flags, 0o666)
+    try:
+        _apply_dest_mode(path_tmp, path_dest)
+        with os.fdopen(fd, "wb") as file_tmp:
+            file_tmp.write(payload)
+            file_tmp.flush()
+            os.fsync(file_tmp.fileno())
+        os.replace(path_tmp, path_dest)
+    except BaseException:
+        with contextlib.suppress(FileNotFoundError):
+            os.unlink(path_tmp)
+        raise
+    _fsync_dir(path_dest.parent)
+
+
+@type_checker
+def _apply_dest_mode(path_tmp: Path, path_dest: Path) -> None:
+    """Give the still-empty temp file the existing destination's permission bits.
+
+    Runs before any payload byte is written, so the payload is never readable under a wider
+    mode than the final file. A missing destination leaves the ``0o666``-minus-umask default.
+
+    Parameters
+    ----------
+    path_tmp : Path
+            Temp file, opened but not yet written.
+    path_dest : Path
+            Final destination, which may not exist yet.
+    """
+    with contextlib.suppress(FileNotFoundError):
+        os.chmod(path_tmp, os.stat(path_dest).st_mode & 0o7777)
+
+
+@type_checker
+def _fsync_dir(path_dir: Path) -> None:
+    """Fsync the directory so the rename survives a crash (POSIX; no-op elsewhere).
+
+    Parameters
+    ----------
+    path_dir : Path
+            Directory holding the renamed file.
+    """
+    if os.name != "posix":
+        return
+    fd = os.open(path_dir, os.O_RDONLY)
+    try:
+        os.fsync(fd)
+    finally:
+        os.close(fd)