opendata-cvm 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- filings_cvm/__init__.py +22 -0
- filings_cvm/_internal/__init__.py +1 -0
- filings_cvm/_internal/config/__init__.py +1 -0
- filings_cvm/_internal/config/contracts/__init__.py +27 -0
- filings_cvm/_internal/config/contracts/example_source.py +20 -0
- filings_cvm/_internal/schemas/__init__.py +40 -0
- filings_cvm/_internal/schemas/perfil_mensal.py +466 -0
- filings_cvm/_internal/utils/__init__.py +1 -0
- filings_cvm/_internal/utils/br_identifiers.py +257 -0
- filings_cvm/_internal/utils/dtypes.py +98 -0
- filings_cvm/_internal/utils/http_downloader.py +194 -0
- filings_cvm/_internal/utils/logs.py +277 -0
- filings_cvm/_internal/utils/logs_emitter.py +61 -0
- filings_cvm/_internal/utils/retry.py +184 -0
- filings_cvm/_internal/utils/tabular_reader.py +423 -0
- filings_cvm/_internal/utils/text.py +79 -0
- filings_cvm/_internal/utils/typing/__init__.py +30 -0
- filings_cvm/_internal/utils/typing/abc_type_checker.py +16 -0
- filings_cvm/_internal/utils/typing/decorators.py +34 -0
- filings_cvm/_internal/utils/typing/protocol_type_checker.py +20 -0
- filings_cvm/_internal/utils/typing/type_checker.py +87 -0
- filings_cvm/_internal/utils/typing/validate.py +306 -0
- filings_cvm/_internal/utils/zip_extractor.py +257 -0
- filings_cvm/main.py +9 -0
- filings_cvm/submission/__init__.py +46 -0
- filings_cvm/submission/perfil_mensal.py +566 -0
- opendata_cvm-0.1.0.dist-info/METADATA +152 -0
- opendata_cvm-0.1.0.dist-info/RECORD +30 -0
- opendata_cvm-0.1.0.dist-info/WHEEL +4 -0
- opendata_cvm-0.1.0.dist-info/licenses/LICENSE +21 -0
filings_cvm/__init__.py
ADDED
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
"""filings-cvm — typed access to CVM regulatory XML file standards.
|
|
2
|
+
|
|
3
|
+
Two macro-sections organise every solution:
|
|
4
|
+
|
|
5
|
+
- ``filings_cvm.submission`` — build and serialise files to *send* to CVM (envio).
|
|
6
|
+
- ``filings_cvm.ingestion`` — parse and interpret files *received* from CVM (leitura).
|
|
7
|
+
|
|
8
|
+
See the CVM XML Standards catalog in ``CLAUDE.md`` for the full source of truth.
|
|
9
|
+
"""
|
|
10
|
+
|
|
11
|
+
from importlib.metadata import PackageNotFoundError, version
|
|
12
|
+
|
|
13
|
+
from filings_cvm.submission import PerfilMensal, PerfilMensalDocument
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
try:
|
|
17
|
+
__version__ = version("opendata-cvm")
|
|
18
|
+
except PackageNotFoundError: # pragma: no cover - source tree without an installed dist
|
|
19
|
+
__version__ = "0.0.0"
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
__all__ = ["PerfilMensal", "PerfilMensalDocument", "__version__"]
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"""Private internals of the filings-cvm package (not a public API)."""
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"""Private configuration internals (data contracts) of filings-cvm."""
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
"""Data contracts for the project's input files (config layer).
|
|
2
|
+
|
|
3
|
+
A contract is **declarative configuration** of an input's expected shape — which columns a
|
|
4
|
+
source must carry, which must hold valid CNPJs — *not* data access, so contracts live in
|
|
5
|
+
``config`` beside the other declarative config (``inputs.yaml``, ``connection_db``), imported
|
|
6
|
+
by the model loaders and the controller boundary.
|
|
7
|
+
|
|
8
|
+
Convention: **one file per source** under this package (``cadastro.py``, ``orders.py``, …),
|
|
9
|
+
each defining a single ``FileContract`` instance; this aggregator re-exports them (plus the
|
|
10
|
+
machinery from ``utils.tabular_reader``) so callers import from one place:
|
|
11
|
+
``from config.contracts import EXAMPLE_SOURCE, find_file_problems``.
|
|
12
|
+
|
|
13
|
+
``EXAMPLE_SOURCE`` is a reference instance — copy ``example_source.py`` per real source and
|
|
14
|
+
delete the example once your own contracts exist.
|
|
15
|
+
"""
|
|
16
|
+
|
|
17
|
+
from __future__ import annotations
|
|
18
|
+
|
|
19
|
+
from filings_cvm._internal.config.contracts.example_source import EXAMPLE_SOURCE
|
|
20
|
+
from filings_cvm._internal.utils.tabular_reader import (
|
|
21
|
+
ContractError,
|
|
22
|
+
FileContract,
|
|
23
|
+
find_file_problems,
|
|
24
|
+
)
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
__all__ = ["EXAMPLE_SOURCE", "ContractError", "FileContract", "find_file_problems"]
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
"""Reference data contract — copy this per real input source, then delete the example.
|
|
2
|
+
|
|
3
|
+
Declares the columns the file must carry (``tuple_required``) and the columns that must hold
|
|
4
|
+
at least one valid CNPJ (``tuple_cnpj_cols``). The model/controller passes this instance to
|
|
5
|
+
``utils.tabular_reader.read_table`` / ``read_query``, which raises ``ContractError`` on any
|
|
6
|
+
violation before types are applied.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from __future__ import annotations
|
|
10
|
+
|
|
11
|
+
from filings_cvm._internal.utils.tabular_reader import FileContract
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
# str_name (human label), str_source_key (routes notifications), tuple_required, tuple_cnpj_cols.
|
|
15
|
+
EXAMPLE_SOURCE = FileContract(
|
|
16
|
+
"Example Source",
|
|
17
|
+
"example_source",
|
|
18
|
+
("code", "amount"),
|
|
19
|
+
(),
|
|
20
|
+
)
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
"""Shared XML-standard schemas (Pydantic models) for the CVM file standards.
|
|
2
|
+
|
|
3
|
+
Direction-neutral contracts consumed by both the ``submission`` section (models →
|
|
4
|
+
XML) and the future ``ingestion`` section (XML → models). One module per CVM
|
|
5
|
+
standard. Ships in the wheel under ``_internal``; the public API is curated by the
|
|
6
|
+
``submission``/``ingestion`` packages, which re-export the names consumers need.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from filings_cvm._internal.schemas.perfil_mensal import (
|
|
10
|
+
ClientCount,
|
|
11
|
+
DocumentHeader,
|
|
12
|
+
NominalRiskBlock,
|
|
13
|
+
NominalRiskFactor,
|
|
14
|
+
OtcOperation,
|
|
15
|
+
PatrimonyDistribution,
|
|
16
|
+
PerfilMensalDocument,
|
|
17
|
+
PerfilMensalRow,
|
|
18
|
+
PerformanceFeeDetails,
|
|
19
|
+
PrimitiveRiskFactor,
|
|
20
|
+
PrivateCreditIssuer,
|
|
21
|
+
VarOutros,
|
|
22
|
+
VarPercValCota,
|
|
23
|
+
)
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
__all__ = [
|
|
27
|
+
"ClientCount",
|
|
28
|
+
"DocumentHeader",
|
|
29
|
+
"NominalRiskBlock",
|
|
30
|
+
"NominalRiskFactor",
|
|
31
|
+
"OtcOperation",
|
|
32
|
+
"PatrimonyDistribution",
|
|
33
|
+
"PerfilMensalDocument",
|
|
34
|
+
"PerfilMensalRow",
|
|
35
|
+
"PerformanceFeeDetails",
|
|
36
|
+
"PrimitiveRiskFactor",
|
|
37
|
+
"PrivateCreditIssuer",
|
|
38
|
+
"VarOutros",
|
|
39
|
+
"VarPercValCota",
|
|
40
|
+
]
|
|
@@ -0,0 +1,466 @@
|
|
|
1
|
+
"""Pydantic models for the CVM Monthly Profile (Perfil Mensal) XML standard.
|
|
2
|
+
|
|
3
|
+
This is the *shared schema* — the direction-neutral contract for one CVM XML
|
|
4
|
+
standard. The ``submission`` section builds these models and serialises them to
|
|
5
|
+
XML; the future ``ingestion`` section will parse CVM XML back into them. It ships
|
|
6
|
+
inside the wheel under ``_internal`` but is **not** part of the public API on its
|
|
7
|
+
own — the ``submission``/``ingestion`` packages re-export the names consumers need.
|
|
8
|
+
|
|
9
|
+
Per-field decimal scales mirror the CVM XML standard ``PadrãoXMLPerfil`` (V4,
|
|
10
|
+
https://cvmweb.cvm.gov.br/SWB/Sistemas/SCW/PadroesXML/PadraoXMLPerfilV4.asp).
|
|
11
|
+
Values carrying more decimal places than the standard permits are truncated toward
|
|
12
|
+
zero (``ROUND_DOWN``) instead of rounded, so a reported value is never inflated
|
|
13
|
+
past what the standard allows.
|
|
14
|
+
|
|
15
|
+
CNPJ/CPF fields are validated with this library's own check-digit validators
|
|
16
|
+
(``_internal.utils.br_identifiers``) and stored in bare, unmasked form — the shape
|
|
17
|
+
CVM expects in the XML — rather than a format-only regex.
|
|
18
|
+
"""
|
|
19
|
+
|
|
20
|
+
from collections.abc import Callable
|
|
21
|
+
from decimal import ROUND_DOWN, Decimal, InvalidOperation
|
|
22
|
+
import re
|
|
23
|
+
from typing import Annotated, Literal
|
|
24
|
+
|
|
25
|
+
from pydantic import BaseModel, BeforeValidator, Field, ValidationInfo, field_validator
|
|
26
|
+
|
|
27
|
+
from filings_cvm._internal.utils.br_identifiers import (
|
|
28
|
+
is_valid_cnpj,
|
|
29
|
+
is_valid_cpf,
|
|
30
|
+
unmask_cnpj,
|
|
31
|
+
unmask_cpf,
|
|
32
|
+
)
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
# Raw values a decimal before-validator may receive, before coercion to Decimal.
|
|
36
|
+
DecimalInput = Decimal | str | int | float | None
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
def _truncate_to_scale(decimal_places: int) -> Callable[[DecimalInput], Decimal | None]:
|
|
40
|
+
"""Build a before-validator that truncates a value to ``decimal_places`` (ROUND_DOWN).
|
|
41
|
+
|
|
42
|
+
Truncation (never rounding) is used so a value is never inflated past the scale
|
|
43
|
+
the CVM standard permits; any excess precision is discarded toward zero.
|
|
44
|
+
|
|
45
|
+
Parameters
|
|
46
|
+
----------
|
|
47
|
+
decimal_places : int
|
|
48
|
+
Number of decimal places mandated by the CVM standard for the field.
|
|
49
|
+
|
|
50
|
+
Returns
|
|
51
|
+
-------
|
|
52
|
+
Callable[[DecimalInput], Optional[Decimal]]
|
|
53
|
+
A validator callable returning the truncated ``Decimal`` (or ``None``).
|
|
54
|
+
|
|
55
|
+
Raises
|
|
56
|
+
------
|
|
57
|
+
ValueError
|
|
58
|
+
Raised by the returned validator when a value cannot be interpreted as a
|
|
59
|
+
decimal number.
|
|
60
|
+
"""
|
|
61
|
+
quantum = Decimal(1).scaleb(-decimal_places)
|
|
62
|
+
|
|
63
|
+
def _truncate(value: DecimalInput) -> Decimal | None:
|
|
64
|
+
"""Truncate a single incoming value to the bound scale.
|
|
65
|
+
|
|
66
|
+
Parameters
|
|
67
|
+
----------
|
|
68
|
+
value : DecimalInput
|
|
69
|
+
Raw value from XML parsing, CSV reload, or direct construction.
|
|
70
|
+
|
|
71
|
+
Returns
|
|
72
|
+
-------
|
|
73
|
+
Optional[Decimal]
|
|
74
|
+
Truncated value, or ``None`` when the input is ``None``.
|
|
75
|
+
|
|
76
|
+
Raises
|
|
77
|
+
------
|
|
78
|
+
ValueError
|
|
79
|
+
If the value cannot be interpreted as a decimal number.
|
|
80
|
+
"""
|
|
81
|
+
if value is None:
|
|
82
|
+
return None
|
|
83
|
+
try:
|
|
84
|
+
as_decimal = value if isinstance(value, Decimal) else Decimal(str(value))
|
|
85
|
+
except (InvalidOperation, ValueError) as exc:
|
|
86
|
+
raise ValueError(f"invalid decimal value: {value!r}") from exc
|
|
87
|
+
return as_decimal.quantize(quantum, rounding=ROUND_DOWN)
|
|
88
|
+
|
|
89
|
+
return _truncate
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
# Decimal field types with the scale pinned to the CVM Perfil standard.
|
|
93
|
+
# Fields where the standard states only the number of decimal places.
|
|
94
|
+
OneDecimalField = Annotated[
|
|
95
|
+
Decimal, BeforeValidator(_truncate_to_scale(1)), Field(decimal_places=1)
|
|
96
|
+
]
|
|
97
|
+
TwoDecimalField = Annotated[
|
|
98
|
+
Decimal, BeforeValidator(_truncate_to_scale(2)), Field(decimal_places=2)
|
|
99
|
+
]
|
|
100
|
+
FiveDecimalField = Annotated[
|
|
101
|
+
Decimal, BeforeValidator(_truncate_to_scale(5)), Field(decimal_places=5)
|
|
102
|
+
]
|
|
103
|
+
|
|
104
|
+
# Fields where the standard also bounds the integer-digit count.
|
|
105
|
+
# VAR_PERC_PL: "valor com até 10 casas inteiras e 4 decimais".
|
|
106
|
+
VarPercentPlField = Annotated[
|
|
107
|
+
Decimal, BeforeValidator(_truncate_to_scale(4)), Field(max_digits=14, decimal_places=4)
|
|
108
|
+
]
|
|
109
|
+
# PRAZ_MED_CART_TIT: "valor com até 4 casas inteiras e 4 decimais".
|
|
110
|
+
AvgTermField = Annotated[
|
|
111
|
+
Decimal, BeforeValidator(_truncate_to_scale(4)), Field(max_digits=8, decimal_places=4)
|
|
112
|
+
]
|
|
113
|
+
# PR_* patrimony distribution: "até 3 casas inteiras e 1 decimal. Valor máximo 100".
|
|
114
|
+
PercentField = Annotated[
|
|
115
|
+
Decimal,
|
|
116
|
+
BeforeValidator(_truncate_to_scale(1)),
|
|
117
|
+
Field(ge=Decimal("0"), le=Decimal("100"), max_digits=4, decimal_places=1),
|
|
118
|
+
]
|
|
119
|
+
|
|
120
|
+
|
|
121
|
+
def _validated_cnpj(value: str) -> str:
|
|
122
|
+
"""Normalise and check-digit-validate a CNPJ, returning its bare 14-char form.
|
|
123
|
+
|
|
124
|
+
Parameters
|
|
125
|
+
----------
|
|
126
|
+
value : str
|
|
127
|
+
A CNPJ in any shape (masked, padded, or bare).
|
|
128
|
+
|
|
129
|
+
Returns
|
|
130
|
+
-------
|
|
131
|
+
str
|
|
132
|
+
The unmasked (bare) CNPJ.
|
|
133
|
+
|
|
134
|
+
Raises
|
|
135
|
+
------
|
|
136
|
+
ValueError
|
|
137
|
+
If the value is not a valid CNPJ (failing check digits).
|
|
138
|
+
"""
|
|
139
|
+
if not is_valid_cnpj(value):
|
|
140
|
+
raise ValueError(f"invalid CNPJ: {value!r}")
|
|
141
|
+
return unmask_cnpj(value)
|
|
142
|
+
|
|
143
|
+
|
|
144
|
+
class DocumentHeader(BaseModel):
|
|
145
|
+
"""CAB_INFORM - document-level header block."""
|
|
146
|
+
|
|
147
|
+
cod_doc: int = 40
|
|
148
|
+
dt_compt: str
|
|
149
|
+
dt_gerac_arq: str
|
|
150
|
+
versao: str = "4.0"
|
|
151
|
+
|
|
152
|
+
@field_validator("dt_compt")
|
|
153
|
+
@classmethod
|
|
154
|
+
def _check_dt_compt(cls, v: str) -> str:
|
|
155
|
+
"""Validate dt_compt format.
|
|
156
|
+
|
|
157
|
+
Parameters
|
|
158
|
+
----------
|
|
159
|
+
v : str
|
|
160
|
+
Value to validate.
|
|
161
|
+
|
|
162
|
+
Returns
|
|
163
|
+
-------
|
|
164
|
+
str
|
|
165
|
+
Validated value.
|
|
166
|
+
|
|
167
|
+
Raises
|
|
168
|
+
------
|
|
169
|
+
ValueError
|
|
170
|
+
If value does not follow MM/AAAA format.
|
|
171
|
+
"""
|
|
172
|
+
if not re.match(r"^\d{2}/\d{4}$", v):
|
|
173
|
+
raise ValueError("dt_compt must follow MM/AAAA format.")
|
|
174
|
+
return v
|
|
175
|
+
|
|
176
|
+
@field_validator("dt_gerac_arq")
|
|
177
|
+
@classmethod
|
|
178
|
+
def _check_dt_gerac_arq(cls, v: str) -> str:
|
|
179
|
+
"""Validate dt_gerac_arq format.
|
|
180
|
+
|
|
181
|
+
Parameters
|
|
182
|
+
----------
|
|
183
|
+
v : str
|
|
184
|
+
Value to validate.
|
|
185
|
+
|
|
186
|
+
Returns
|
|
187
|
+
-------
|
|
188
|
+
str
|
|
189
|
+
Validated value.
|
|
190
|
+
|
|
191
|
+
Raises
|
|
192
|
+
------
|
|
193
|
+
ValueError
|
|
194
|
+
If value does not follow DD/MM/AAAA format.
|
|
195
|
+
"""
|
|
196
|
+
if not re.match(r"^\d{2}/\d{2}/\d{4}$", v):
|
|
197
|
+
raise ValueError("dt_gerac_arq must follow DD/MM/AAAA format.")
|
|
198
|
+
return v
|
|
199
|
+
|
|
200
|
+
|
|
201
|
+
class ClientCount(BaseModel):
|
|
202
|
+
"""NR_CLIENT - count of clients by investor type (all mandatory, non-negative)."""
|
|
203
|
+
|
|
204
|
+
nr_pf_priv_bank: int = Field(ge=0)
|
|
205
|
+
nr_pf_varj: int = Field(ge=0)
|
|
206
|
+
nr_pj_n_financ_priv_bank: int = Field(ge=0)
|
|
207
|
+
nr_pj_n_financ_varj: int = Field(ge=0)
|
|
208
|
+
nr_bnc_comerc: int = Field(ge=0)
|
|
209
|
+
nr_pj_corr_dist: int = Field(ge=0)
|
|
210
|
+
nr_pj_outr_financ: int = Field(ge=0)
|
|
211
|
+
nr_inv_n_res: int = Field(ge=0)
|
|
212
|
+
nr_ent_ab_prev_compl: int = Field(ge=0)
|
|
213
|
+
nr_ent_fc_prev_compl: int = Field(ge=0)
|
|
214
|
+
nr_reg_prev_serv_pub: int = Field(ge=0)
|
|
215
|
+
nr_soc_seg_reseg: int = Field(ge=0)
|
|
216
|
+
nr_soc_captlz_arrendm_merc: int = Field(ge=0)
|
|
217
|
+
nr_fdos_club_inv: int = Field(ge=0)
|
|
218
|
+
nr_cotst_distr_fdo: int = Field(ge=0)
|
|
219
|
+
nr_outros_n_relac: int = Field(ge=0)
|
|
220
|
+
|
|
221
|
+
|
|
222
|
+
class PatrimonyDistribution(BaseModel):
|
|
223
|
+
"""DISTR_PATRIM - patrimony percentage by client type (entire block is optional)."""
|
|
224
|
+
|
|
225
|
+
pr_pf_priv_bank: PercentField | None = None
|
|
226
|
+
pr_pf_varj: PercentField | None = None
|
|
227
|
+
pr_pj_n_financ_priv_bank: PercentField | None = None
|
|
228
|
+
pr_pj_n_financ_varj: PercentField | None = None
|
|
229
|
+
pr_bnc_comerc: PercentField | None = None
|
|
230
|
+
pr_pj_corr_dist: PercentField | None = None
|
|
231
|
+
pr_pj_outr_financ: PercentField | None = None
|
|
232
|
+
pr_inv_n_res: PercentField | None = None
|
|
233
|
+
pr_ent_ab_prev_compl: PercentField | None = None
|
|
234
|
+
pr_ent_fc_prev_compl: PercentField | None = None
|
|
235
|
+
pr_reg_prev_serv_pub: PercentField | None = None
|
|
236
|
+
pr_soc_seg_reseg: PercentField | None = None
|
|
237
|
+
pr_soc_captlz_arrendm_merc: PercentField | None = None
|
|
238
|
+
pr_fdos_club_inv: PercentField | None = None
|
|
239
|
+
pr_cotst_distr_fdo: PercentField | None = None
|
|
240
|
+
pr_outros_n_relac: PercentField | None = None
|
|
241
|
+
|
|
242
|
+
|
|
243
|
+
class PrimitiveRiskFactor(BaseModel):
|
|
244
|
+
"""FATOR_PRIMIT_RISCO - one BM&FBOVESPA primitive risk factor entry."""
|
|
245
|
+
|
|
246
|
+
nome_fator_primit_risco: Literal["IBOVESPA", "JUROS-PRE", "CUPOM CAMBIAL", "DOLAR", "OUTROS"]
|
|
247
|
+
cen_util: str = Field(max_length=150)
|
|
248
|
+
|
|
249
|
+
|
|
250
|
+
class VarPercValCota(BaseModel):
|
|
251
|
+
"""VARIACAO_PERC_VAL_COTA - stress scenario block with primitive risk factors."""
|
|
252
|
+
|
|
253
|
+
val_percent: TwoDecimalField
|
|
254
|
+
lista_fator_primit_risco: list[PrimitiveRiskFactor] = Field(max_length=5)
|
|
255
|
+
|
|
256
|
+
|
|
257
|
+
class VarOutros(BaseModel):
|
|
258
|
+
"""VARIACAO_DIAR_PERC_PATRIM_FDO_VAR_N_OUTROS - sensitivity to a non-standard risk factor."""
|
|
259
|
+
|
|
260
|
+
fator_risco_outros: str = Field(max_length=400)
|
|
261
|
+
val_percent_outros: TwoDecimalField
|
|
262
|
+
|
|
263
|
+
|
|
264
|
+
class NominalRiskFactor(BaseModel):
|
|
265
|
+
"""FATOR_RISCO_NOC - one notional derivatives risk factor (long and short legs)."""
|
|
266
|
+
|
|
267
|
+
nome_fator_noc: Literal["IBOVESPA", "JUROS-PRE", "CUPOM CAMBIAL", "DOLAR", "OUTROS"]
|
|
268
|
+
val_fator_risco_noc_long: int = Field(ge=0)
|
|
269
|
+
val_fator_risco_noc_short: int = Field(ge=0)
|
|
270
|
+
|
|
271
|
+
|
|
272
|
+
class NominalRiskBlock(BaseModel):
|
|
273
|
+
"""VALOR_NOC_TOT_CONTRAT_DERIV_MANT_FDO - OTC derivatives notional exposure block."""
|
|
274
|
+
|
|
275
|
+
val_colateral: TwoDecimalField
|
|
276
|
+
lista_fator_risco_noc: list[NominalRiskFactor] = Field(max_length=5)
|
|
277
|
+
|
|
278
|
+
|
|
279
|
+
class OtcOperation(BaseModel):
|
|
280
|
+
"""OPER_CURS_MERC_BALCAO - one top-3 OTC counterparty without central clearing."""
|
|
281
|
+
|
|
282
|
+
tp_pessoa: Literal["PF", "PJ"]
|
|
283
|
+
nr_pf_pj_comitente: str
|
|
284
|
+
parte_relacionada: Literal["S", "N"]
|
|
285
|
+
valor_parte: OneDecimalField
|
|
286
|
+
|
|
287
|
+
@field_validator("nr_pf_pj_comitente")
|
|
288
|
+
@classmethod
|
|
289
|
+
def _check_comitente_doc(cls, v: str, info: ValidationInfo) -> str:
|
|
290
|
+
"""Validate and normalise the counterparty document against its person type.
|
|
291
|
+
|
|
292
|
+
Parameters
|
|
293
|
+
----------
|
|
294
|
+
v : str
|
|
295
|
+
The counterparty document (CPF or CNPJ) in any shape.
|
|
296
|
+
info : ValidationInfo
|
|
297
|
+
Validation context; ``tp_pessoa`` (declared first) is read from it.
|
|
298
|
+
|
|
299
|
+
Returns
|
|
300
|
+
-------
|
|
301
|
+
str
|
|
302
|
+
The document in bare, unmasked form.
|
|
303
|
+
|
|
304
|
+
Raises
|
|
305
|
+
------
|
|
306
|
+
ValueError
|
|
307
|
+
If the document is not a valid CPF (PF) or CNPJ (PJ).
|
|
308
|
+
"""
|
|
309
|
+
return _validate_person_doc(info.data.get("tp_pessoa", ""), v)
|
|
310
|
+
|
|
311
|
+
|
|
312
|
+
class PrivateCreditIssuer(BaseModel):
|
|
313
|
+
"""EMISSORES_TIT_CRED_PRIV - one top-3 private credit issuer held by the fund class."""
|
|
314
|
+
|
|
315
|
+
tp_pessoa_emissor: Literal["PF", "PJ"]
|
|
316
|
+
nr_pf_pj_emissor: str
|
|
317
|
+
parte_relacionada: Literal["S", "N"]
|
|
318
|
+
valor_parte: OneDecimalField
|
|
319
|
+
|
|
320
|
+
@field_validator("nr_pf_pj_emissor")
|
|
321
|
+
@classmethod
|
|
322
|
+
def _check_emissor_doc(cls, v: str, info: ValidationInfo) -> str:
|
|
323
|
+
"""Validate and normalise the issuer document against its person type.
|
|
324
|
+
|
|
325
|
+
Parameters
|
|
326
|
+
----------
|
|
327
|
+
v : str
|
|
328
|
+
The issuer document (CPF or CNPJ) in any shape.
|
|
329
|
+
info : ValidationInfo
|
|
330
|
+
Validation context; ``tp_pessoa_emissor`` (declared first) is read from it.
|
|
331
|
+
|
|
332
|
+
Returns
|
|
333
|
+
-------
|
|
334
|
+
str
|
|
335
|
+
The document in bare, unmasked form.
|
|
336
|
+
|
|
337
|
+
Raises
|
|
338
|
+
------
|
|
339
|
+
ValueError
|
|
340
|
+
If the document is not a valid CPF (PF) or CNPJ (PJ).
|
|
341
|
+
"""
|
|
342
|
+
return _validate_person_doc(info.data.get("tp_pessoa_emissor", ""), v)
|
|
343
|
+
|
|
344
|
+
|
|
345
|
+
def _validate_person_doc(tp_pessoa: str, value: str) -> str:
|
|
346
|
+
"""Validate a document as CPF (PF) or CNPJ (PJ) and return its bare form.
|
|
347
|
+
|
|
348
|
+
Parameters
|
|
349
|
+
----------
|
|
350
|
+
tp_pessoa : str
|
|
351
|
+
``"PF"`` (natural person → CPF) or ``"PJ"`` (legal entity → CNPJ).
|
|
352
|
+
value : str
|
|
353
|
+
The document in any shape.
|
|
354
|
+
|
|
355
|
+
Returns
|
|
356
|
+
-------
|
|
357
|
+
str
|
|
358
|
+
The unmasked (bare) document.
|
|
359
|
+
|
|
360
|
+
Raises
|
|
361
|
+
------
|
|
362
|
+
ValueError
|
|
363
|
+
If the document is not valid for the given person type.
|
|
364
|
+
"""
|
|
365
|
+
if tp_pessoa == "PF":
|
|
366
|
+
if not is_valid_cpf(value):
|
|
367
|
+
raise ValueError(f"invalid CPF for PF: {value!r}")
|
|
368
|
+
return unmask_cpf(value)
|
|
369
|
+
if not is_valid_cnpj(value):
|
|
370
|
+
raise ValueError(f"invalid CNPJ for PJ: {value!r}")
|
|
371
|
+
return unmask_cnpj(value)
|
|
372
|
+
|
|
373
|
+
|
|
374
|
+
class PerformanceFeeDetails(BaseModel):
|
|
375
|
+
"""RESP_VED_REGUL_COBR_TAXA_PERFORM - date and NAV of the last performance fee charge."""
|
|
376
|
+
|
|
377
|
+
data_cota_fundo: str
|
|
378
|
+
val_cota_fundo: FiveDecimalField
|
|
379
|
+
|
|
380
|
+
@field_validator("data_cota_fundo")
|
|
381
|
+
@classmethod
|
|
382
|
+
def _check_date(cls, v: str) -> str:
|
|
383
|
+
"""Validate date format.
|
|
384
|
+
|
|
385
|
+
Parameters
|
|
386
|
+
----------
|
|
387
|
+
v : str
|
|
388
|
+
Value to validate.
|
|
389
|
+
|
|
390
|
+
Returns
|
|
391
|
+
-------
|
|
392
|
+
str
|
|
393
|
+
Validated value.
|
|
394
|
+
|
|
395
|
+
Raises
|
|
396
|
+
------
|
|
397
|
+
ValueError
|
|
398
|
+
If value does not follow DD/MM/AAAA format.
|
|
399
|
+
"""
|
|
400
|
+
if not re.match(r"^\d{2}/\d{2}/\d{4}$", v):
|
|
401
|
+
raise ValueError("data_cota_fundo must follow DD/MM/AAAA format.")
|
|
402
|
+
return v
|
|
403
|
+
|
|
404
|
+
|
|
405
|
+
class PerfilMensalRow(BaseModel):
|
|
406
|
+
"""ROW_PERFIL - one fund-class monthly profile entry."""
|
|
407
|
+
|
|
408
|
+
cnpj_fdo: str
|
|
409
|
+
nr_client: ClientCount
|
|
410
|
+
distr_patrim: PatrimonyDistribution | None = None
|
|
411
|
+
resm_teor_vt_profrd: str | None = Field(default=None, max_length=4000)
|
|
412
|
+
just_sum_vt_profrd: str | None = Field(default=None, max_length=4000)
|
|
413
|
+
var_perc_pl: VarPercentPlField | None = None
|
|
414
|
+
mod_var_utiliz: Literal["1", "2", "3"] | None = None
|
|
415
|
+
praz_med_cart_tit: AvgTermField | None = None
|
|
416
|
+
res_delib: str | None = Field(default=None, max_length=4000)
|
|
417
|
+
total_recurs_exter: TwoDecimalField
|
|
418
|
+
total_recurs_br: TwoDecimalField
|
|
419
|
+
variacao_perc_val_cota: VarPercValCota | None = None
|
|
420
|
+
var_diar_perc_cota_fdo_pior_cen_estress: TwoDecimalField | None = None
|
|
421
|
+
var_diar_perc_patrim_fdo_var_n_taxa_anual: TwoDecimalField | None = None
|
|
422
|
+
var_diar_perc_patrim_fdo_var_n_taxa_cambio: TwoDecimalField | None = None
|
|
423
|
+
var_patrim_fdo_n_preco_acoes: TwoDecimalField | None = None
|
|
424
|
+
variacao_diar_perc_patrim_fdo_var_n_outros: VarOutros | None = None
|
|
425
|
+
valor_noc_tot_contrat_deriv_mant_fdo: NominalRiskBlock | None = None
|
|
426
|
+
lista_oper_curs_merc_balcao: list[OtcOperation] | None = Field(default=None, max_length=3)
|
|
427
|
+
tot_ativos_p_relac: OneDecimalField
|
|
428
|
+
lista_emissores_tit_cred_priv: list[PrivateCreditIssuer] | None = Field(
|
|
429
|
+
default=None, max_length=3
|
|
430
|
+
)
|
|
431
|
+
tot_ativos_cred_priv: OneDecimalField
|
|
432
|
+
ved_regul_cobr_taxa_perform: Literal["S", "N"] | None = None
|
|
433
|
+
resp_ved_regul_cobr_taxa_perform: PerformanceFeeDetails | None = None
|
|
434
|
+
# MONTANTE_DISTRIB is absent from older Perfil versions; 2dp is inferred from its
|
|
435
|
+
# monetary nature and the serializer default, pending confirmation against the spec.
|
|
436
|
+
montante_distrib: TwoDecimalField | None = None
|
|
437
|
+
inf_compl_perfil: str | None = Field(default=None, max_length=500)
|
|
438
|
+
|
|
439
|
+
@field_validator("cnpj_fdo")
|
|
440
|
+
@classmethod
|
|
441
|
+
def _check_cnpj(cls, v: str) -> str:
|
|
442
|
+
"""Validate and normalise the fund-class CNPJ (check-digit aware).
|
|
443
|
+
|
|
444
|
+
Parameters
|
|
445
|
+
----------
|
|
446
|
+
v : str
|
|
447
|
+
Value to validate.
|
|
448
|
+
|
|
449
|
+
Returns
|
|
450
|
+
-------
|
|
451
|
+
str
|
|
452
|
+
The unmasked (bare) CNPJ.
|
|
453
|
+
|
|
454
|
+
Raises
|
|
455
|
+
------
|
|
456
|
+
ValueError
|
|
457
|
+
If value is not a valid CNPJ.
|
|
458
|
+
"""
|
|
459
|
+
return _validated_cnpj(v)
|
|
460
|
+
|
|
461
|
+
|
|
462
|
+
class PerfilMensalDocument(BaseModel):
|
|
463
|
+
"""DOC_ARQ - complete CVM Monthly Profile XML document."""
|
|
464
|
+
|
|
465
|
+
header: DocumentHeader
|
|
466
|
+
rows: list[PerfilMensalRow]
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"""Shared, project-agnostic utility helpers (copied into every Python skeleton)."""
|