btgsolutions-dataservices-python-client 4.3.0__tar.gz → 4.3.2__tar.gz

{btgsolutions_dataservices_python_client-4.3.0/btgsolutions_dataservices_python_client.egg-info → btgsolutions_dataservices_python_client-4.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: btgsolutions_dataservices_python_client
-Version: 4.3.0
+Version: 4.3.2
 Summary: Python package containing several classes and data for extracting and manipulating market and trading data.
 Home-page: https://github.com/BTG-Pactual-Solutions/btgsolutions-dataservices-python-client
 Author: BTG Solutions Data Services powered by BTG Pactual Solutions

{btgsolutions_dataservices_python_client-4.3.0 → btgsolutions_dataservices_python_client-4.3.2}/btgsolutions_dataservices/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "4.3.0"
+__version__ = "4.3.2"
 
 from .websocket import *
 from .rest import *

{btgsolutions_dataservices_python_client-4.3.0 → btgsolutions_dataservices_python_client-4.3.2}/btgsolutions_dataservices/rest/alternative_data_catalog.py

@@ -33,10 +33,103 @@ PUBLIC_SOURCES_CONVENTIONS: dict[str, str] = {
 
 
 PUBLIC_SOURCES_DATA_GAPS: dict[str, str] = {
+    "get_macro_indicators": (
+        "Macro-indicator rows are heterogeneous across sources. Inspect the "
+        "returned indicator, source, type/subseries, unit and date fields before "
+        "aggregating or comparing values. The metadata endpoint is discovery "
+        "help, but accepted aggregate aliases such as ipca can still return "
+        "valid rows even when a related granular code such as "
+        "ipca_contributions is also listed. Use the returned row fields to "
+        "separate aggregate IPCA/Selic observations from contribution or "
+        "category rows."
+    ),
+    "sector_taxonomy_labels": (
+        "B3 sector, subsector and segment labels are upstream taxonomy labels. "
+        "Use the exact strings returned by get_taxonomy or get_company_sector "
+        "when calling get_sector_companies; punctuation and spelling variations "
+        "can change matches."
+    ),
+    "get_company_board": (
+        "For Brazilian companies, body='board' can include Conselho Fiscal rows "
+        "alongside Conselho de Administracao rows depending on the filing. For "
+        "a board-of-directors answer, filter returned rows by governance_body "
+        "or role to keep Conselho de Administracao only. Committee responses "
+        "can include broad aggregates such as Outros Comites; do not infer "
+        "granular committee names unless they are present in returned fields."
+    ),
+    "get_financial_statements": (
+        "company_id may be omitted only for universe-level screens or rankings. "
+        "There is no dedicated latest-quarter discovery field; when a requested "
+        "quarter returns zero rows, back off to the latest filed quarter and "
+        "state which quarter was used. statement_type is a presentation/filter "
+        "such as consolidated or individual when supported; DFP/ITR are filing "
+        "source concepts and can appear in returned fields, but they are not "
+        "the right filter for cross-company consolidated rankings."
+    ),
+    "get_fund_exposures": (
+        "Fund exposure dimensions are source-dependent. For Brazilian ETFs, "
+        "issuer exposure can be based on ticker-like issuer labels and country "
+        "exposure can be empty when the source does not classify country. Use "
+        "holdings for constituent-level economic exposure and exposures for "
+        "aggregate context."
+    ),
+    "get_fund_lookthrough": (
+        "Look-through is useful when a fund holds other funds that can be "
+        "expanded. For direct-equity ETFs, look-through can return opaque "
+        "asset_key values or zero lookthrough_weight when nested weights cannot "
+        "be resolved. In those cases, use get_fund_holdings and "
+        "get_fund_exposures for the defensible exposure analysis."
+    ),
     "get_top_shareholders": (
-        "Shareholder snapshots can be empty for listed companies. Prefer "
-        "get_ownership_current, get_control_group or get_free_float for current "
-        "ownership context when this endpoint returns no rows."
+        "Top-shareholder snapshots come from the normalized ownership_snapshot "
+        "layer. For Brazilian listed companies, CVM/FRE rows are periodic "
+        "filing snapshots, often annual or quarterly reference dates. When "
+        "reference_date is omitted, the endpoint uses the latest loaded "
+        "snapshot per ownership_category; when reference_date is provided, it "
+        "must match an exact loaded snapshot date. For Brazilian ownership context, "
+        "prefer get_ownership_current, get_ownership_control_group, "
+        "get_ownership_free_float and get_ownership_official_notices when this "
+        "endpoint returns no rows. "
+        "This endpoint does not synthesize top holders from current ownership "
+        "or free-float tables. Some responses can include multiple rows for "
+        "the same holder across share classes, ownership categories, filings "
+        "or source protocols; inspect category, class, protocol/source and "
+        "reference date before aggregating percentages."
+    ),
+    "ownership_reporting_dates": (
+        "Brazilian ownership and free-float reference_date fields often come "
+        "from CVM/FRE reporting periods, fiscal-year bases or parsed IR "
+        "structures. They are reporting/reference dates, not necessarily the "
+        "calendar date when the data was loaded or a strict as-of timestamp; a "
+        "reference_date can be after the current calendar date when it denotes "
+        "a filing year/base period."
+    ),
+    "get_ownership_history": (
+        "Ownership history uses the same normalized ownership_snapshot layer as "
+        "top-shareholders and returns only loaded snapshot reference dates. "
+        "For Brazilian listed companies, CVM/FRE snapshots are periodic filing "
+        "dates rather than guaranteed calendar month-ends. It can return an "
+        "empty snapshots list when the snapshot layer has no rows for the "
+        "selected company/date/category filter. Use get_ownership_change_events "
+        "and get_ownership_official_notices for event/document timelines when "
+        "snapshots are empty; this endpoint does not synthesize history from "
+        "notice or current-ownership tables."
+    ),
+    "get_ownership_official_notices": (
+        "The response has multiple evidence blocks: official_notices, "
+        "ir_page_sources and ir_structures. start_date/end_date filter the "
+        "official_notices block; IR page/source metadata or parsed IR "
+        "structures can still be returned when that official-notice range is "
+        "empty. Use official_notices download_url values with "
+        "get_notice_summary; use ir_page_sources/ir_structures as discovery or "
+        "parser-status evidence, not as filed notice documents."
+    ),
+    "get_maximum_theoretical_margin": (
+        "discount_margin is the B3 haircut/desagio percentage value from the "
+        "maximum-theoretical-margin reference file, not a decimal fraction. "
+        "base_value is the B3 reference/base value in that file and should not "
+        "be treated as a live quote or a credit decision value. Use quotes and "
+        "liquidity endpoints separately when contextualizing the margin data."
     ),
     "get_beneficial_ownership": (
         "Coverage is UK/US oriented: UK Companies House PSC and US SEC proxy "
@@ -45,8 +138,13 @@ PUBLIC_SOURCES_DATA_GAPS: dict[str, str] = {
         "and free-float endpoints for Brazilian ownership context."
     ),
     "get_asset_institutional_holders": (
-        "Institutional-holder coverage can be sparse. get_asset_fund_holders "
-        "often has richer data for B3-listed assets."
+        "Institutional-holder coverage can be sparse for B3-listed assets and "
+        "can return zero rows for tickers that still have fund-holder or ETF "
+        "holder coverage. This endpoint reads the precomputed asset-holder "
+        "layer and ownership_snapshot fund_holder fallback; it does not run the "
+        "live fund-portfolio/ETF holding lookup used by get_asset_fund_holders. "
+        "Use get_asset_fund_holders for Brazilian assets when this endpoint is "
+        "empty."
     ),
     "get_disclosure_documents_repurchase": (
         "Share-repurchase disclosure coverage can be thin for many companies. "
@@ -62,7 +160,20 @@ PUBLIC_SOURCES_DATA_GAPS: dict[str, str] = {
     "get_dpmfi": (
         "DPMFi can be slow when queried without a snapshot or reference-month "
         "filter. Prefer snapshot_date for reproducibility and start_date/end_date "
-        "in YYYY-MM when a narrow period is known."
+        "in YYYY-MM when a narrow period is known. When snapshot_date is omitted "
+        "the latest available snapshot is used; to discover that snapshot for a "
+        "reproducible follow-up call, make a narrow latest query and inspect "
+        "the returned snapshot/partition date fields."
+    ),
+    "get_dpmfi_composition": (
+        "DPMFi PAF composition is a forward projection table. The latest "
+        "snapshot usually covers only the two reference months after the latest "
+        "official DPMFi stock observation; older or outside-window "
+        "start_date/end_date filters can return zero rows. bond_type uses PAF "
+        "categories Prefixado, IPCA, Selic or Total, not security acronyms such "
+        "as LTN, LFT, NTN-B or NTN-F. Use get_dpmfi for official stock by "
+        "security acronym/status and get_dpmfi_composition for PAF projection "
+        "composition; do not join bond_type values one-to-one across the two."
     ),
 }
 
@@ -86,7 +197,8 @@ PUBLIC_SOURCES_ENDPOINT_RELATIONSHIPS: dict[str, str] = {
     "macro_indicator_discovery": (
         "Use AlternativeDataMetadata.get_available_indicators before "
         "AlternativeDataMacroMarkets.get_macro_indicators when the requested "
-        "macro series code is uncertain."
+        "macro series code is uncertain, then inspect the returned rows because "
+        "macro endpoints can expose both aggregate and granular series."
     ),
     "asset_discovery": (
         "Use AlternativeDataMetadata.get_available_assets to discover asset or "
@@ -101,7 +213,8 @@ PUBLIC_SOURCES_ENDPOINT_RELATIONSHIPS: dict[str, str] = {
         "Use get_taxonomy or get_sectors_summary to understand available B3/CNAE "
         "classification values, get_company_sector to classify one company, and "
         "get_sector_companies to retrieve the peer set for a sector, subsector "
-        "or segment."
+        "or segment. Pass the exact returned taxonomy labels into "
+        "get_sector_companies rather than normalized or guessed strings."
     ),
     "document_summary": (
         "Use AlternativeDataCompanies.get_assemblies or "
@@ -296,13 +409,15 @@ PUBLIC_SOURCES_ENDPOINTS: dict[str, dict[str, Any]] = {
         "description": (
             "Get the complete sector/classification taxonomy for B3 or CNAE. "
             "Use B3 for exchange sector, subsector and segment hierarchy; use "
-            "CNAE for Brazilian economic activity codes."
+            "CNAE for Brazilian economic activity codes. Reuse returned labels "
+            "exactly when filtering peer companies."
         ),
         "parameters": {
             "system": "Classification system, usually 'b3' or 'cnae'.",
             "limit": "Maximum number of taxonomy rows.",
         },
         "relationships": ["sector_peer_set", "sector_market_peer_bridge"],
+        "caveats": [PUBLIC_SOURCES_DATA_GAPS["sector_taxonomy_labels"]],
     },
     "AlternativeDataMetadata.get_cnae": {
         "category": "metadata",
@@ -324,13 +439,15 @@ PUBLIC_SOURCES_ENDPOINTS: dict[str, dict[str, Any]] = {
         "description": (
             "Get sector classification for a company or listed asset. Rows "
             "include B3 sector, subsector and segment plus registered "
-            "headquarters state and municipality when available."
+            "headquarters state and municipality when available. Reuse returned "
+            "sector labels exactly when building peer sets."
         ),
         "parameters": {"identifier": "Ticker, CNPJ, CVM code, ISIN or company name."},
         "relationships": [
             "sector_peer_set", "company_resolution",
             "company_trading_bridge", "sector_market_peer_bridge",
         ],
+        "caveats": [PUBLIC_SOURCES_DATA_GAPS["sector_taxonomy_labels"]],
     },
     "AlternativeDataMetadata.get_sector_companies": {
         "category": "metadata",
@@ -339,7 +456,9 @@ PUBLIC_SOURCES_ENDPOINTS: dict[str, dict[str, Any]] = {
         "client": "AlternativeDataMetadata",
         "description": (
             "List companies classified in a B3 sector, optionally filtered by "
-            "subsector and segment. Use active_only to restrict to active companies."
+            "subsector and segment. Use active_only to restrict to active "
+            "companies. For reliable matches, pass exact labels returned by "
+            "get_taxonomy or get_company_sector."
         ),
         "parameters": {
             "sector": "B3 sector name.",
@@ -349,6 +468,7 @@ PUBLIC_SOURCES_ENDPOINTS: dict[str, dict[str, Any]] = {
             "limit": "Maximum number of companies.",
         },
         "relationships": ["sector_peer_set", "sector_market_peer_bridge"],
+        "caveats": [PUBLIC_SOURCES_DATA_GAPS["sector_taxonomy_labels"]],
     },
     "AlternativeDataMetadata.get_sectors_summary": {
         "category": "metadata",
@@ -371,7 +491,9 @@ PUBLIC_SOURCES_ENDPOINTS: dict[str, dict[str, Any]] = {
         "description": (
             "Get Brazilian macroeconomic or public fiscal time-series observations. "
             "Indicator values include selic, ipca, ipca_contributions, "
-            "ipca_categories, copom, pim, pmc, pms, pnad, gdp, comexstat and rreo."
+            "ipca_categories, copom, pim, pmc, pms, pnad, gdp, comexstat and "
+            "rreo. Returned units, date grains and row fields vary by indicator "
+            "and source."
         ),
         "parameters": {
             "indicator": "Macro indicator code.",
@@ -388,6 +510,7 @@ PUBLIC_SOURCES_ENDPOINTS: dict[str, dict[str, Any]] = {
             "offset": "Pagination offset.",
         },
         "relationships": ["macro_indicator_discovery", "macro_market_bridge"],
+        "caveats": [PUBLIC_SOURCES_DATA_GAPS["get_macro_indicators"]],
     },
     "AlternativeDataMacroMarkets.get_maximum_theoretical_margin": {
         "category": "market_data_reference",
@@ -406,13 +529,16 @@ PUBLIC_SOURCES_ENDPOINTS: dict[str, dict[str, Any]] = {
             "origin": "Optional origin market filter.",
             "start_date": "Start date in YYYY-MM-DD.",
             "end_date": "End date in YYYY-MM-DD.",
-            "min_margin": "Lower bound for discount_margin.",
-            "max_margin": "Upper bound for discount_margin.",
+            "min_margin": "Lower bound for discount_margin percentage value.",
+            "max_margin": "Upper bound for discount_margin percentage value.",
             "limit": "Maximum number of rows.",
             "offset": "Pagination offset.",
         },
         "relationships": ["asset_discovery", "company_trading_bridge"],
-        "caveats": [PUBLIC_SOURCES_EXCLUDED_ENDPOINTS["market-data/investor-categories"]],
+        "caveats": [
+            PUBLIC_SOURCES_DATA_GAPS["get_maximum_theoretical_margin"],
+            PUBLIC_SOURCES_EXCLUDED_ENDPOINTS["market-data/investor-categories"],
+        ],
     },
     "AlternativeDataMacroMarkets.get_dpmfi": {
         "category": "macro",
@@ -421,7 +547,9 @@ PUBLIC_SOURCES_ENDPOINTS: dict[str, dict[str, Any]] = {
         "client": "AlternativeDataMacroMarkets",
         "description": (
             "Get monthly stock of DPMFi, Brazilian federal domestic public debt, "
-            "by indexer such as LTN, LFT, NTN-B, NTN-F and Demais."
+            "by security acronym/indexer such as LTN, LFT, NTN-B, NTN-F and "
+            "Demais. This is the official/projection/estimated stock series, "
+            "not the PAF composition projection."
         ),
         "parameters": {
             "start_date": "Reference month start in YYYY-MM.",
@@ -439,8 +567,11 @@ PUBLIC_SOURCES_ENDPOINTS: dict[str, dict[str, Any]] = {
         "method": "GET",
         "client": "AlternativeDataMacroMarkets",
         "description": (
-            "Get DPMFi PAF composition projections: issuances, maturities and "
-            "final stock by bond type for months after the latest official data."
+            "Get DPMFi PAF composition projections: new issuances, "
+            "end-of-month outstanding stock and share of total DPMFi debt by "
+            "bond category for the forward months available in the selected "
+            "snapshot. Returned row fields are reference_date, bond_type, "
+            "emissoes, estoque_final and perc_divida."
         ),
         "parameters": {
             "start_date": "Reference month start in YYYY-MM.",
@@ -450,6 +581,7 @@ PUBLIC_SOURCES_ENDPOINTS: dict[str, dict[str, Any]] = {
             "limit": "Maximum number of rows.",
             "offset": "Pagination offset.",
         },
+        "caveats": [PUBLIC_SOURCES_DATA_GAPS["get_dpmfi_composition"]],
     },
     "AlternativeDataCompanies.get_board": {
         "category": "companies",
@@ -459,7 +591,9 @@ PUBLIC_SOURCES_ENDPOINTS: dict[str, dict[str, Any]] = {
         "description": (
             "Get members of a company's governance body. body can be board, "
             "executive or committee; committee filters a specific committee when "
-            "body='committee'."
+            "body='committee'. For Brazilian filings, body='board' can include "
+            "Conselho Fiscal rows; filter governance_body/role for Conselho de "
+            "Administracao when answering board-of-directors questions."
         ),
         "parameters": {
             "company_id": PUBLIC_SOURCES_CONVENTIONS["company_id"],
@@ -471,6 +605,7 @@ PUBLIC_SOURCES_ENDPOINTS: dict[str, dict[str, Any]] = {
             "offset": "Pagination offset.",
         },
         "relationships": ["company_resolution", "company_trading_bridge"],
+        "caveats": [PUBLIC_SOURCES_DATA_GAPS["get_company_board"]],
     },
     "AlternativeDataCompanies.get_governance_summary": {
         "category": "companies",
@@ -656,14 +791,18 @@ PUBLIC_SOURCES_ENDPOINTS: dict[str, dict[str, Any]] = {
         "description": (
             "Get company financial-statement line items from CVM filings. "
             "statement can be income_statement, balance_sheet or cash_flow; "
-            "use account_code to retrieve a specific account."
+            "use account_code to retrieve a specific account. Omit company_id "
+            "only for universe-level screens or rankings."
         ),
         "parameters": {
-            "company_id": PUBLIC_SOURCES_CONVENTIONS["company_id"],
+            "company_id": (
+                PUBLIC_SOURCES_CONVENTIONS["company_id"]
+                + " Omit only for universe-level screens or rankings."
+            ),
             "statement": "Statement type or alias, for example income_statement, balance_sheet or cash_flow.",
             "quarter": "Brazilian quarter code such as 1T24 or 4T24.",
             "reference_date": "Reference date in YYYY-MM-DD.",
-            "statement_type": "Optional filing type filter such as DFP or ITR.",
+            "statement_type": "Optional presentation/filter such as consolidated or individual when supported.",
             "account_code": "Optional account code filter.",
             "limit": "Maximum number of line items.",
             "offset": "Pagination offset.",
@@ -673,6 +812,7 @@ PUBLIC_SOURCES_ENDPOINTS: dict[str, dict[str, Any]] = {
             "company_trading_bridge", "sector_market_peer_bridge",
             "macro_market_bridge",
         ],
+        "caveats": [PUBLIC_SOURCES_DATA_GAPS["get_financial_statements"]],
     },
     "AlternativeDataCompanies.get_financial_notes": {
         "category": "companies",
@@ -811,7 +951,8 @@ PUBLIC_SOURCES_ENDPOINTS: dict[str, dict[str, Any]] = {
         "description": (
             "Get aggregate exposures for a fund or ETF by dimension. "
             "exposure_type can be all, asset_class, issuer, sector, indexer, "
-            "maturity or country."
+            "maturity or country. Use holdings for constituent-level exposure "
+            "when a dimension is sparse or source-dependent."
         ),
         "parameters": {
             "fund_id": PUBLIC_SOURCES_CONVENTIONS["fund_id"],
@@ -822,6 +963,7 @@ PUBLIC_SOURCES_ENDPOINTS: dict[str, dict[str, Any]] = {
             "fund_company_bridge", "sector_peer_set",
             "fund_market_exposure_bridge", "sector_market_peer_bridge",
         ],
+        "caveats": [PUBLIC_SOURCES_DATA_GAPS["get_fund_exposures"]],
     },
     "AlternativeDataFunds.get_history": {
         "category": "funds",
@@ -851,7 +993,8 @@ PUBLIC_SOURCES_ENDPOINTS: dict[str, dict[str, Any]] = {
         "client": "AlternativeDataFunds",
         "description": (
             "Get recursive look-through exposure for a fund or ETF. Use this to "
-            "expand nested fund holdings into underlying assets when available."
+            "expand nested fund holdings into underlying assets when available; "
+            "for direct-equity ETFs, holdings and exposures can be more useful."
         ),
         "parameters": {
             "fund_id": PUBLIC_SOURCES_CONVENTIONS["fund_id"],
@@ -859,6 +1002,7 @@ PUBLIC_SOURCES_ENDPOINTS: dict[str, dict[str, Any]] = {
             "limit": "Maximum number of look-through rows.",
         },
         "relationships": ["fund_company_bridge", "fund_market_exposure_bridge"],
+        "caveats": [PUBLIC_SOURCES_DATA_GAPS["get_fund_lookthrough"]],
     },
     "AlternativeDataFunds.get_manager_aggregate_holdings": {
         "category": "funds",
@@ -885,12 +1029,17 @@ PUBLIC_SOURCES_ENDPOINTS: dict[str, dict[str, Any]] = {
         "method": "GET",
         "client": "AlternativeDataOwnership",
         "description": (
-            "Get top shareholders for a listed company when shareholder snapshots "
-            "are loaded."
+            "Get top shareholders for a company from the normalized "
+            "ownership_snapshot layer when shareholder-level snapshots are "
+            "available. Brazilian CVM/FRE rows are periodic filing snapshots."
         ),
         "parameters": {
             "company_id": PUBLIC_SOURCES_CONVENTIONS["company_id"],
-            "reference_date": "Reference date in YYYY-MM-DD; omitted means latest snapshot.",
+            "reference_date": (
+                "Reference date in YYYY-MM-DD; omitted means latest loaded "
+                "snapshot per ownership_category. Provided values are exact "
+                "loaded snapshot dates, not as-of lookups."
+            ),
             "ownership_category": "Ownership category filter when supported.",
             "limit": "Maximum number of shareholders.",
         },
@@ -898,7 +1047,10 @@ PUBLIC_SOURCES_ENDPOINTS: dict[str, dict[str, Any]] = {
             "company_resolution", "ownership_fallback",
             "ownership_liquidity_bridge",
         ],
-        "caveats": [PUBLIC_SOURCES_DATA_GAPS["get_top_shareholders"]],
+        "caveats": [
+            PUBLIC_SOURCES_DATA_GAPS["get_top_shareholders"],
+            PUBLIC_SOURCES_DATA_GAPS["ownership_reporting_dates"],
+        ],
     },
     "AlternativeDataOwnership.get_ownership_current": {
         "category": "ownership",
@@ -914,6 +1066,7 @@ PUBLIC_SOURCES_ENDPOINTS: dict[str, dict[str, Any]] = {
             "company_resolution", "ownership_fallback",
             "ownership_liquidity_bridge",
         ],
+        "caveats": [PUBLIC_SOURCES_DATA_GAPS["ownership_reporting_dates"]],
     },
     "AlternativeDataOwnership.get_ownership_history": {
         "category": "ownership",
@@ -921,21 +1074,26 @@ PUBLIC_SOURCES_ENDPOINTS: dict[str, dict[str, Any]] = {
         "method": "GET",
         "client": "AlternativeDataOwnership",
         "description": (
-            "Get historical ownership snapshots for a company. Use "
-            "ownership_category to filter ordinary, preferred or total categories "
-            "when supported."
+            "Get historical ownership snapshots for a company from the "
+            "normalized ownership_snapshot layer. Brazilian CVM/FRE snapshots "
+            "are periodic filing dates, not guaranteed month-end series. Use "
+            "ownership_category to filter holder categories when supported."
         ),
         "parameters": {
             "company_id": PUBLIC_SOURCES_CONVENTIONS["company_id"],
             "start_date": "Start date in YYYY-MM-DD.",
             "end_date": "End date in YYYY-MM-DD.",
             "ownership_category": "Ownership category filter when supported.",
-            "limit": "Maximum number of snapshots.",
+            "limit": "Maximum number of snapshot reference dates.",
         },
         "relationships": [
             "company_resolution", "ownership_fallback",
             "ownership_liquidity_bridge",
         ],
+        "caveats": [
+            PUBLIC_SOURCES_DATA_GAPS["get_ownership_history"],
+            PUBLIC_SOURCES_DATA_GAPS["ownership_reporting_dates"],
+        ],
     },
     "AlternativeDataOwnership.get_ownership_change_events": {
         "category": "ownership",
@@ -958,6 +1116,7 @@ PUBLIC_SOURCES_ENDPOINTS: dict[str, dict[str, Any]] = {
             "company_resolution", "ownership_fallback", "document_summary",
             "ownership_liquidity_bridge", "document_market_event_bridge",
         ],
+        "caveats": [PUBLIC_SOURCES_DATA_GAPS["ownership_reporting_dates"]],
     },
     "AlternativeDataOwnership.get_ownership_official_notices": {
         "category": "ownership",
@@ -965,9 +1124,10 @@ PUBLIC_SOURCES_ENDPOINTS: dict[str, dict[str, Any]] = {
         "method": "GET",
         "client": "AlternativeDataOwnership",
         "description": (
-            "Get official CVM/IPE ownership participation notices for a company. "
-            "Use this to find filed documents and download URLs about shareholder "
-            "participation changes."
+            "Get official ownership notices and related IR evidence for a "
+            "company. The response can contain official_notices, ir_page_sources "
+            "and ir_structures; use official_notices download_url values for "
+            "document summaries."
         ),
         "parameters": {
             "company_id": PUBLIC_SOURCES_CONVENTIONS["company_id"],
@@ -980,6 +1140,10 @@ PUBLIC_SOURCES_ENDPOINTS: dict[str, dict[str, Any]] = {
             "company_resolution", "ownership_fallback", "document_summary",
             "ownership_liquidity_bridge", "document_market_event_bridge",
         ],
+        "caveats": [
+            PUBLIC_SOURCES_DATA_GAPS["get_ownership_official_notices"],
+            PUBLIC_SOURCES_DATA_GAPS["ownership_reporting_dates"],
+        ],
     },
     "AlternativeDataOwnership.get_notice_summary": {
         "category": "ownership",
@@ -1011,6 +1175,7 @@ PUBLIC_SOURCES_ENDPOINTS: dict[str, dict[str, Any]] = {
             "company_resolution", "ownership_fallback",
             "ownership_liquidity_bridge",
         ],
+        "caveats": [PUBLIC_SOURCES_DATA_GAPS["ownership_reporting_dates"]],
     },
     "AlternativeDataOwnership.get_ownership_free_float": {
         "category": "ownership",
@@ -1029,6 +1194,7 @@ PUBLIC_SOURCES_ENDPOINTS: dict[str, dict[str, Any]] = {
             "company_resolution", "ownership_fallback",
             "ownership_liquidity_bridge",
         ],
+        "caveats": [PUBLIC_SOURCES_DATA_GAPS["ownership_reporting_dates"]],
     },
     "AlternativeDataOwnership.get_shareholder_holdings": {
         "category": "ownership",
@@ -1055,8 +1221,9 @@ PUBLIC_SOURCES_ENDPOINTS: dict[str, dict[str, Any]] = {
         "method": "GET",
         "client": "AlternativeDataOwnership",
         "description": (
-            "Get institutional holders of an asset. identifier defaults to a B3 "
-            "ticker when identifier_type='b3_ticker'."
+            "Get institutional holders of an asset from the precomputed "
+            "asset-holder layer. identifier defaults to a B3 ticker when "
+            "identifier_type='b3_ticker'."
         ),
         "parameters": {
             "identifier": PUBLIC_SOURCES_CONVENTIONS["asset_identifier"],
@@ -1073,8 +1240,9 @@ PUBLIC_SOURCES_ENDPOINTS: dict[str, dict[str, Any]] = {
         "method": "GET",
         "client": "AlternativeDataOwnership",
         "description": (
-            "Get investment funds holding a given asset. identifier defaults to "
-            "a B3 ticker when identifier_type='b3_ticker'."
+            "Get investment funds or ETFs holding a given asset using fund "
+            "portfolio and ETF holding snapshots. identifier defaults to a B3 "
+            "ticker when identifier_type='b3_ticker'."
         ),
         "parameters": {
             "identifier": PUBLIC_SOURCES_CONVENTIONS["asset_identifier"],

{btgsolutions_dataservices_python_client-4.3.0 → btgsolutions_dataservices_python_client-4.3.2}/btgsolutions_dataservices/rest/alternative_data_companies.py

@@ -103,6 +103,13 @@ class AlternativeDataCompanies:
         Use get_board_changes() for appointment/departure events and
         get_governance_history() for historical snapshot series.
 
+        For Brazilian filings, ``body='board'`` can include Conselho Fiscal
+        rows alongside Conselho de Administracao rows. For a board-of-directors
+        answer, filter returned rows by governance_body or role. Committee
+        responses can include broad aggregate groups such as Outros Comites; do
+        not infer granular committee names unless they are present in returned
+        fields.
+
         Parameters
         ----------------
         company_id: str
@@ -475,7 +482,7 @@ class AlternativeDataCompanies:
 
     def get_financial_statements(
         self,
-        company_id: str,
+        company_id: Optional[str] = None,
         statement: str = "income_statement",
         quarter: Optional[str] = None,
         reference_date: Optional[str] = None,
@@ -490,11 +497,15 @@ class AlternativeDataCompanies:
         statement name or alias is uncertain. Quarter filters use Brazilian
         quarter codes such as 1T24 and 4T24.
 
+        Omit ``company_id`` only for universe-level screens or rankings; in
+        that mode, paginate with ``limit``/``offset`` and deduplicate repeated
+        filings by company and source document version before ranking.
+
         Parameters
         ----------------
         company_id: str
             Company identifier (CNPJ, CVM code, or B3 ticker).
-            Field is required. Example: 'PETR4'.
+            Field is not required for universe-level screens. Example: 'PETR4'.
         statement: str
             Statement type (e.g. 'income_statement', 'balance_sheet', 'cash_flow').
             Field is not required. Default: 'income_statement'.
@@ -505,7 +516,9 @@ class AlternativeDataCompanies:
             Reference date in YYYY-MM-DD format.
             Field is not required.
         statement_type: str
-            Statement type filter (e.g. 'DFP', 'ITR').
+            Statement presentation/filter when supported by the endpoint, such
+            as 'consolidated' or 'individual'. Some payloads also expose filing
+            source fields such as DFP/ITR separately; inspect returned columns.
             Field is not required.
         account_code: str
             Specific account code filter.

{btgsolutions_dataservices_python_client-4.3.0 → btgsolutions_dataservices_python_client-4.3.2}/btgsolutions_dataservices/rest/alternative_data_funds.py

@@ -160,6 +160,10 @@ class AlternativeDataFunds:
         issuer, sector, indexer, maturity, country).
         Use sector exposure with company sector endpoints when comparing fund
         exposure with B3 company peer groups.
+        Exposure dimensions are source-dependent: for Brazilian ETFs, issuer
+        exposure can use ticker-like labels and country exposure can be empty
+        when not classified by the source. Use holdings for constituent-level
+        economic exposure when a dimension is sparse.
 
         Parameters
         ----------------
@@ -228,6 +232,10 @@ class AlternativeDataFunds:
         positions to underlying assets when available).
         Use this after holdings when nested fund positions need to be expanded
         into underlying assets.
+        For direct-equity ETFs, look-through can return opaque asset_key values
+        or zero lookthrough_weight when nested weights cannot be resolved. In
+        those cases, use get_holdings() and get_exposures() for exposure
+        analysis.
 
         Parameters
         ----------------

{btgsolutions_dataservices_python_client-4.3.0 → btgsolutions_dataservices_python_client-4.3.2}/btgsolutions_dataservices/rest/alternative_data_macro_markets.py

@@ -76,17 +76,25 @@ class AlternativeDataMacroMarkets:
         Use AlternativeDataMetadata.get_available_indicators() first when the
         indicator code is uncertain.
 
+        Macro rows are heterogeneous across sources. Inspect returned indicator,
+        source, type/subseries, unit and date fields before aggregating values.
+        Aggregate aliases such as ``ipca`` can return valid aggregate rows even
+        when related granular series such as ``ipca_contributions`` are listed
+        separately in metadata.
+
         Parameters
         ----------------
         indicator: str
             Macro indicator code.
             Field is required. Example: 'selic'.
         start_date: str
-            Start of the query period in YYYY-MM format.
-            Field is not required. Example: '2024-01'.
+            Start of the query period in YYYY-MM-DD format when supported by
+            the indicator.
+            Field is not required. Example: '2024-01-01'.
         end_date: str
-            End of the query period in YYYY-MM format.
-            Field is not required. Example: '2024-12'.
+            End of the query period in YYYY-MM-DD format when supported by the
+            indicator.
+            Field is not required. Example: '2024-12-31'.
         year: str
             Four-digit year filter (ComexStat and RREO).
             Field is not required.
@@ -148,6 +156,10 @@ class AlternativeDataMacroMarkets:
         Use AlternativeDataMetadata.get_available_assets() first when asset or
         instrument coverage is uncertain. This is a margin reference endpoint,
         not a quote/trade feed and not the investor-categories endpoint.
+        ``discount_margin`` is returned as a percentage value from the B3
+        reference file, not as a decimal fraction. ``base_value`` is the B3
+        file's reference/base value and should not be treated as a live quote
+        or a credit decision value.
 
         Parameters
         ----------------
@@ -170,10 +182,10 @@ class AlternativeDataMacroMarkets:
             End date of the query period in YYYY-MM-DD format.
             Field is not required.
         min_margin: float
-            Lower bound filter on the discount_margin (haircut) value.
+            Lower bound filter on the discount_margin (haircut) percentage value.
             Field is not required.
         max_margin: float
-            Upper bound filter on the discount_margin (haircut) value.
+            Upper bound filter on the discount_margin (haircut) percentage value.
             Field is not required.
         limit: int
             Maximum number of results to return.
@@ -207,6 +219,13 @@ class AlternativeDataMacroMarkets:
         """
         Monthly time-series of DPMFi (domestic federal public debt) outstanding
         stock broken down by bond type (NTN-B, LFT, NTN-F, LTN, Demais).
+        This endpoint returns official/projection/estimated stock series by
+        security acronym or indexer. Use get_dpmfi_composition() for PAF
+        composition projections by broad bond category.
+
+        When ``snapshot_date`` is omitted, the latest available snapshot is
+        used. To make a reproducible follow-up call, run a narrow latest query
+        and inspect the returned snapshot/partition date fields.
 
         Parameters
         ----------------
@@ -250,9 +269,17 @@ class AlternativeDataMacroMarkets:
         offset: int = 0,
     ) -> dict:
         """
-        Monthly PAF composition by bond type: new issuances, end-of-month
-        outstanding stock, and share of total DPMFi debt (Prefixado, IPCA,
-        Selic, Total).
+        Monthly PAF composition by bond category: new issuances (``emissoes``),
+        end-of-month outstanding stock (``estoque_final``), and share of total
+        DPMFi debt (``perc_divida``) for Prefixado, IPCA, Selic and Total.
+
+        This endpoint covers the forward PAF projection months available in the
+        selected snapshot, usually the two months after the latest official
+        DPMFi stock observation. Filters outside the available reference-month
+        window return an empty but valid result. ``bond_type`` uses PAF
+        categories (Prefixado, IPCA, Selic, Total), not security acronyms such
+        as LTN, LFT, NTN-B or NTN-F. Do not join ``bond_type`` values one-to-one
+        with the security-acronym rows returned by get_dpmfi().
 
         Parameters
         ----------------

{btgsolutions_dataservices_python_client-4.3.0 → btgsolutions_dataservices_python_client-4.3.2}/btgsolutions_dataservices/rest/alternative_data_metadata.py

@@ -102,7 +102,9 @@ class AlternativeDataMetadata:
         List the available macro indicator codes for use with
         AlternativeDataMacroMarkets.get_macro_indicators().
         Use this metadata endpoint when the requested macro series code is
-        uncertain before querying observations.
+        uncertain before querying observations. Treat this as discovery help,
+        then inspect returned macro rows because aggregate aliases such as
+        ipca and related granular series such as ipca_contributions can coexist.
         """
         return self._get("available-indicators", {})
 
@@ -242,7 +244,9 @@ class AlternativeDataMetadata:
         """
         Full sector taxonomy tree (B3 or CNAE classification system).
         Use this with get_company_sector(), get_sector_companies() and
-        get_sectors_summary() to discover sector hierarchy and peer sets.
+        get_sectors_summary() to discover sector hierarchy and peer sets. B3
+        labels are upstream taxonomy labels; pass exact returned sector,
+        subsector and segment strings to get_sector_companies().
 
         Parameters
         ----------------
@@ -271,7 +275,8 @@ class AlternativeDataMetadata:
         """
         Sector classification for a company.
         Use get_sector_companies() with the returned sector/subsector/segment
-        values to retrieve peers in the same B3 classification.
+        values to retrieve peers in the same B3 classification. Reuse the exact
+        returned labels, including punctuation and spelling.
 
         Parameters
         ----------------
@@ -292,7 +297,8 @@ class AlternativeDataMetadata:
         """
         Companies belonging to a given sector, subsector, or segment.
         Use get_taxonomy(), get_sectors_summary(), or get_company_sector() first
-        to discover valid B3 sector/subsector/segment values.
+        to discover valid B3 sector/subsector/segment values. Filters should
+        use exact upstream labels; normalized or guessed strings can miss rows.
 
         Parameters
         ----------------

{btgsolutions_dataservices_python_client-4.3.0 → btgsolutions_dataservices_python_client-4.3.2}/btgsolutions_dataservices/rest/alternative_data_ownership.py

@@ -60,10 +60,23 @@ class AlternativeDataOwnership:
         limit: int = 20,
     ) -> dict:
         """
-        Top shareholders for a company.
-        Snapshot coverage can be empty. For current listed-company ownership
-        context, prefer get_ownership_current(), get_ownership_control_group()
-        or get_ownership_free_float() when this endpoint returns no rows.
+        Top shareholders for a company from the normalized ownership_snapshot
+        layer. For Brazilian listed companies, CVM/FRE rows are periodic filing
+        snapshots, often annual or quarterly reference dates. When
+        ``reference_date`` is omitted, the endpoint uses the latest loaded
+        snapshot per ownership_category; when ``reference_date`` is provided,
+        it must match a loaded snapshot date.
+
+        This endpoint does not synthesize current ownership from control/free
+        float tables; ``total=0`` means no matching rows were found in the
+        normalized snapshot layer for the selected company/date/category
+        filter. For Brazilian ownership questions, call get_ownership_current(),
+        get_ownership_control_group(), get_ownership_free_float() and
+        get_ownership_official_notices() when this endpoint returns no rows.
+        Some responses can include multiple rows for the same holder across
+        share classes, ownership categories, filings or source protocols;
+        inspect category, class, protocol/source and reference date before
+        aggregating percentages.
 
         Parameters
         ----------------
@@ -71,7 +84,9 @@ class AlternativeDataOwnership:
             Company identifier.
             Field is required. Example: 'VALE3'.
         reference_date: str
-            Reference date in YYYY-MM-DD format. Defaults to the most recent snapshot.
+            Reference date in YYYY-MM-DD format. Defaults to the latest loaded
+            snapshot per ownership_category. When provided, it is an exact
+            loaded snapshot date, not an as-of lookup.
             Field is not required.
         ownership_category: str
             Ownership category filter.
@@ -92,6 +107,8 @@ class AlternativeDataOwnership:
         Current ownership structure snapshot for a company.
         Use this as the primary current ownership summary when top-shareholder
         snapshots are empty or when a compact ownership object is sufficient.
+        Reference dates usually come from CVM/FRE reporting periods or parsed
+        IR structures and are not necessarily strict as-of timestamps.
 
         Parameters
         ----------------
@@ -110,13 +127,23 @@ class AlternativeDataOwnership:
         limit: int = 12,
     ) -> dict:
         """
-        Monthly ownership history snapshots for a company.
+        Historical ownership snapshots for a company from the same normalized
+        ownership_snapshot layer used by get_top_shareholders(). For Brazilian
+        listed companies, CVM/FRE snapshots are periodic filing dates rather
+        than guaranteed calendar month-ends. This endpoint does not synthesize
+        history from current ownership or notice tables. For Brazilian ownership
+        timelines, use get_ownership_change_events() and
+        get_ownership_official_notices() as the event/document sources when
+        snapshots are empty, and get_ownership_current(),
+        get_ownership_control_group() or get_ownership_free_float() for current
+        context. Reference dates usually come from reporting periods and can
+        denote a filing year/base period rather than the load date.
 
         Parameters
         ----------------
         company_id: str
             Company identifier.
-            Field is required. Example: 'VALE3'.
+            Field is required. Example: 'PETR4'.
         start_date: str
             Start date in YYYY-MM-DD format.
             Field is not required.
@@ -127,7 +154,7 @@ class AlternativeDataOwnership:
             Ownership category filter.
             Field is not required. Default: 'all'.
         limit: int
-            Maximum number of snapshots to return.
+            Maximum number of snapshot reference dates to return.
             Field is not required. Default: 12.
         """
         return self._get("companies/ownership-history", {
@@ -186,9 +213,18 @@ class AlternativeDataOwnership:
         limit: int = 100,
     ) -> dict:
         """
-        Official ownership notices (CVM IPE, SEC 13D/13G/13F, IR page structures).
-        Returned CVM RAD download URLs can be passed to get_notice_summary() for
-        an AI-generated document summary.
+        Official ownership notices and related IR evidence for a company.
+
+        The response can contain three list blocks:
+        ``official_notices`` (CVM/IPE ownership-related disclosures and SEC
+        13D/13G/13F summaries), ``ir_page_sources`` (candidate investor-relations
+        pages), and ``ir_structures`` (parsed IR ownership/free-float/control
+        structures, filterable by parser_status). start_date/end_date filter
+        the ``official_notices`` block; IR page/source metadata and parsed IR
+        structures are discovery/parser evidence and can still be returned when
+        the requested official-notice date range is empty. Returned CVM RAD
+        download URLs can be passed to get_notice_summary() for an AI-generated
+        document summary.
 
         Parameters
         ----------------
@@ -254,6 +290,8 @@ class AlternativeDataOwnership:
         Control group composition for a Brazilian company (CVM FRE).
         Use this for who controls the company; use get_shareholder_holdings()
         for a reverse lookup of one holder across companies.
+        Reference dates usually come from CVM/FRE reporting periods and can
+        denote a filing year/base period rather than the load date.
 
         Parameters
         ----------------
@@ -266,6 +304,9 @@ class AlternativeDataOwnership:
     def get_ownership_free_float(self, company_id: str, limit: int = 20) -> dict:
         """
         Free float breakdown for a company.
+        Reference dates usually come from CVM/FRE reporting periods or parsed
+        IR structures and can denote a filing year/base period rather than the
+        load date.
 
         Parameters
         ----------------
@@ -331,7 +372,13 @@ class AlternativeDataOwnership:
         limit: int = 50,
     ) -> dict:
         """
-        Institutional holders of a specific asset.
+        Institutional holders of a specific asset from the precomputed
+        asset-holder layer. Coverage can be sparse for B3 tickers. This
+        endpoint does not run the live fund-portfolio/ETF holding lookup used
+        by get_fund_holders(); when this endpoint returns no holders,
+        get_fund_holders() is often the richer inverse relationship for
+        Brazilian assets because it uses fund portfolio and ETF holding
+        snapshots.
 
         Parameters
         ----------------
@@ -363,9 +410,10 @@ class AlternativeDataOwnership:
         limit: int = 50,
     ) -> dict:
         """
-        Funds that hold a specific asset.
+        Funds or ETFs that hold a specific asset.
         This is the inverse relationship of fund holdings for a B3 asset and is
-        often richer than institutional-holder coverage.
+        often richer than institutional-holder coverage because it uses fund
+        portfolio and ETF holding snapshots.
 
         Parameters
         ----------------

{btgsolutions_dataservices_python_client-4.3.0 → btgsolutions_dataservices_python_client-4.3.2/btgsolutions_dataservices_python_client.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: btgsolutions_dataservices_python_client
-Version: 4.3.0
+Version: 4.3.2
 Summary: Python package containing several classes and data for extracting and manipulating market and trading data.
 Home-page: https://github.com/BTG-Pactual-Solutions/btgsolutions-dataservices-python-client
 Author: BTG Solutions Data Services powered by BTG Pactual Solutions