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.
Files changed (30) hide show
  1. filings_cvm/__init__.py +22 -0
  2. filings_cvm/_internal/__init__.py +1 -0
  3. filings_cvm/_internal/config/__init__.py +1 -0
  4. filings_cvm/_internal/config/contracts/__init__.py +27 -0
  5. filings_cvm/_internal/config/contracts/example_source.py +20 -0
  6. filings_cvm/_internal/schemas/__init__.py +40 -0
  7. filings_cvm/_internal/schemas/perfil_mensal.py +466 -0
  8. filings_cvm/_internal/utils/__init__.py +1 -0
  9. filings_cvm/_internal/utils/br_identifiers.py +257 -0
  10. filings_cvm/_internal/utils/dtypes.py +98 -0
  11. filings_cvm/_internal/utils/http_downloader.py +194 -0
  12. filings_cvm/_internal/utils/logs.py +277 -0
  13. filings_cvm/_internal/utils/logs_emitter.py +61 -0
  14. filings_cvm/_internal/utils/retry.py +184 -0
  15. filings_cvm/_internal/utils/tabular_reader.py +423 -0
  16. filings_cvm/_internal/utils/text.py +79 -0
  17. filings_cvm/_internal/utils/typing/__init__.py +30 -0
  18. filings_cvm/_internal/utils/typing/abc_type_checker.py +16 -0
  19. filings_cvm/_internal/utils/typing/decorators.py +34 -0
  20. filings_cvm/_internal/utils/typing/protocol_type_checker.py +20 -0
  21. filings_cvm/_internal/utils/typing/type_checker.py +87 -0
  22. filings_cvm/_internal/utils/typing/validate.py +306 -0
  23. filings_cvm/_internal/utils/zip_extractor.py +257 -0
  24. filings_cvm/main.py +9 -0
  25. filings_cvm/submission/__init__.py +46 -0
  26. filings_cvm/submission/perfil_mensal.py +566 -0
  27. opendata_cvm-0.1.0.dist-info/METADATA +152 -0
  28. opendata_cvm-0.1.0.dist-info/RECORD +30 -0
  29. opendata_cvm-0.1.0.dist-info/WHEEL +4 -0
  30. opendata_cvm-0.1.0.dist-info/licenses/LICENSE +21 -0
@@ -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)."""