PYield 0.44.0__tar.gz → 0.44.2__tar.gz

{pyield-0.44.0 → pyield-0.44.2}/.gitignore

@@ -18,4 +18,6 @@ dev/
 site/
 
 # Test data
-tests/data/
+tests/data/
+
+cgen.py

{pyield-0.44.0 → pyield-0.44.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyield
-Version: 0.44.0
+Version: 0.44.2
 Summary: A Python library for analysis of fixed income instruments in Brazil
 Project-URL: Homepage, https://github.com/crdcj/PYield
 Project-URL: Documentation, https://crdcj.github.io/PYield
@@ -36,6 +36,7 @@ Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Office/Business :: Financial :: Investment
 Requires-Python: >=3.12
+Requires-Dist: cachetools>=5.0.0
 Requires-Dist: fastexcel>=0.19.0
 Requires-Dist: lxml>=6.0.0
 Requires-Dist: polars>=1.33.0

pyield-0.44.2/pyield/__about__.py

@@ -0,0 +1 @@
+__version__ = "0.44.2"

{pyield-0.44.0 → pyield-0.44.2}/pyield/anbima/difusao.py

@@ -18,31 +18,31 @@ URL_PAGINA_INICIAL = f"{URL_BASE}/taxasOnline.asp"
 URL_CONSULTA_DADOS = f"{URL_BASE}/exibedados.asp"
 URL_DOWNLOAD = f"{URL_BASE}/download_dados.asp?extensao=csv"
 
-MAPA_COLUNAS = {
-    "Título": ("titulo", pl.String),
-    "Vencimento": ("data_vencimento", pl.String),
-    "Código ISIN": ("codigo_isin", pl.String),
-    "Provedor": ("provedor", pl.String),
-    "Edital": ("edital", pl.String),
-    "Horário": ("horario", pl.String),
-    "Prazo": ("prazo", pl.Int64),
-    "Lote": ("lote", pl.String),
-    "Fech D-1": ("taxa_indicativa_anterior", pl.Float64),
-    "Indicativo Superior": ("taxa_limite_superior", pl.Float64),
-    "Máxima": ("taxa_maxima", pl.Float64),
-    "Média": ("taxa_media", pl.Float64),
-    "Mínima": ("taxa_minima", pl.Float64),
-    "Indicativo Inferior": ("taxa_limite_inferior", pl.Float64),
-    "Última": ("taxa_ultima", pl.Float64),
-    "Oferta Compra": ("taxa_compra", pl.Float64),
-    "Oferta Venda": ("taxa_venda", pl.Float64),
-    "Nº de Negócios": ("num_negocios", pl.Int64),
-    "Quantidade Negociada": ("quantidade_negociada", pl.Int64),
-    "Volume Negociado (R$)": ("volume_negociado", pl.Float64),
-}
-
-ESQUEMA_API = {col: dtype for col, (_alias, dtype) in MAPA_COLUNAS.items()}
-ALIAS_COLUNAS = {col: alias for col, (alias, _dtype) in MAPA_COLUNAS.items()}
+MAPA_COLUNAS = [
+    ("Título", "titulo", pl.String),
+    ("Vencimento", "data_vencimento", pl.String),
+    ("Código ISIN", "codigo_isin", pl.String),
+    ("Provedor", "provedor", pl.String),
+    ("Edital", "edital", pl.String),
+    ("Horário", "horario", pl.String),
+    ("Prazo", "prazo", pl.Int64),
+    ("Lote", "lote", pl.String),
+    ("Fech D-1", "taxa_indicativa_anterior", pl.Float64),
+    ("Indicativo Superior", "taxa_limite_superior", pl.Float64),
+    ("Máxima", "taxa_maxima", pl.Float64),
+    ("Média", "taxa_media", pl.Float64),
+    ("Mínima", "taxa_minima", pl.Float64),
+    ("Indicativo Inferior", "taxa_limite_inferior", pl.Float64),
+    ("Última", "taxa_ultima", pl.Float64),
+    ("Oferta Compra", "taxa_compra", pl.Float64),
+    ("Oferta Venda", "taxa_venda", pl.Float64),
+    ("Nº de Negócios", "num_negocios", pl.Int64),
+    ("Quantidade Negociada", "quantidade_negociada", pl.Int64),
+    ("Volume Negociado (R$)", "volume_negociado", pl.Float64),
+]
+
+ESQUEMA_API = {csv: tipo for csv, _, tipo in MAPA_COLUNAS}
+ALIAS_COLUNAS = {csv: novo for csv, novo, _ in MAPA_COLUNAS}
 
 # Colunas não selecionadas estão vazias na API.
 ORDEM_COLUNAS_FINAL = [
@@ -211,9 +211,10 @@ def tpf_difusao(data_referencia: DateLike) -> pl.DataFrame:
         - taxa_ultima (float): Última taxa negociada (decimal).
     """
     if any_is_empty(data_referencia):
-        logger.warning("Nenhuma data fornecida. Retornando DataFrame vazio.")
         return pl.DataFrame()
     data = cv.converter_datas(data_referencia)
+    if not bday.is_business_day(data):
+        return pl.DataFrame()
     data_str = data.strftime("%d/%m/%Y")
     csv_data = _buscar_dados_url(data_str)
 

{pyield-0.44.0 → pyield-0.44.2}/pyield/anbima/ettj_intraday.py

@@ -2,6 +2,7 @@ import datetime as dt
 import logging
 from io import StringIO
 
+import cachetools
 import polars as pl
 import requests
 
@@ -18,6 +19,7 @@ URL_ETTJ_INTRADAY = (
 CASAS_DECIMAIS = 6
 
 
+@cachetools.cached(cache=cachetools.TTLCache(maxsize=16, ttl=60))
 @retry_padrao
 def _buscar_texto_intraday() -> str:
     carga_requisicao = {"Dt_Ref": "", "saida": "csv"}

{pyield-0.44.0 → pyield-0.44.2}/pyield/anbima/ettj_last.py

@@ -2,6 +2,7 @@ import datetime as dt
 import logging
 from io import StringIO
 
+import cachetools
 import polars as pl
 import requests
 
@@ -15,6 +16,7 @@ URL_ULTIMA_ETTJ = "https://www.anbima.com.br/informacoes/est-termo/CZ-down.asp"
 CASAS_DECIMAIS = 6
 
 
+@cachetools.cached(cache=cachetools.TTLCache(maxsize=16, ttl=60))
 @retry_padrao
 def _buscar_texto_ultima_ettj() -> str:
     """Busca o texto bruto da curva de juros na ANBIMA."""

{pyield-0.44.0 → pyield-0.44.2}/pyield/anbima/ima.py

@@ -2,6 +2,7 @@ import io
 import logging
 from typing import Literal
 
+import cachetools
 import polars as pl
 import requests
 
@@ -24,33 +25,33 @@ TiposIMA = Literal[
 
 # Única fonte de verdade para colunas do CSV: (novo_nome, tipo)
 # Colunas com None no nome são descartadas após a leitura.
-IMA_COLUNAS = {
-    "2": (None, pl.Int64),
-    "Data de Referência": ("Date", pl.String),
-    "INDICE": ("IMAType", pl.String),
-    "Títulos": ("BondType", pl.String),
-    "Data de Vencimento": ("Maturity", pl.String),
-    "Código SELIC": ("SelicCode", pl.Int64),
-    "Código ISIN": ("ISIN", pl.String),
-    "Taxa Indicativa (% a.a.)": ("IndicativeRate", pl.Float64),
-    "PU (R$)": ("Price", pl.Float64),
-    "PU de Juros (R$)": ("InterestPrice", pl.Float64),
-    "Quantidade (1.000 títulos)": ("MarketQuantity", pl.Float64),
-    "Quantidade Teórica (1.000 títulos)": ("TheoreticalQuantity", pl.Float64),
-    "Carteira a Mercado (R$ mil)": ("MarketValue", pl.Float64),
-    "Peso (%)": ("Weight", pl.Float64),
-    "Prazo (d.u.)": ("BDToMat", pl.Int64),
-    "Duration (d.u.)": ("Duration", pl.Int64),
-    "Número de Operações *": ("NumberOfOperations", pl.Int64),
-    "Quant. Negociada (1.000 títulos) *": ("NegotiatedQuantity", pl.Float64),
-    "Valor Negociado (R$ mil) *": ("NegotiatedValue", pl.Float64),
-    "PMR": ("PMR", pl.Float64),
-    "Convexidade": ("Convexity", pl.Float64),
-}
+IMA_COLUNAS = [
+    ("2", None, pl.Int64),
+    ("Data de Referência", "Date", pl.String),
+    ("INDICE", "IMAType", pl.String),
+    ("Títulos", "BondType", pl.String),
+    ("Data de Vencimento", "Maturity", pl.String),
+    ("Código SELIC", "SelicCode", pl.Int64),
+    ("Código ISIN", "ISIN", pl.String),
+    ("Taxa Indicativa (% a.a.)", "IndicativeRate", pl.Float64),
+    ("PU (R$)", "Price", pl.Float64),
+    ("PU de Juros (R$)", "InterestPrice", pl.Float64),
+    ("Quantidade (1.000 títulos)", "MarketQuantity", pl.Float64),
+    ("Quantidade Teórica (1.000 títulos)", "TheoreticalQuantity", pl.Float64),
+    ("Carteira a Mercado (R$ mil)", "MarketValue", pl.Float64),
+    ("Peso (%)", "Weight", pl.Float64),
+    ("Prazo (d.u.)", "BDToMat", pl.Int64),
+    ("Duration (d.u.)", "Duration", pl.Int64),
+    ("Número de Operações *", "NumberOfOperations", pl.Int64),
+    ("Quant. Negociada (1.000 títulos) *", "NegotiatedQuantity", pl.Float64),
+    ("Valor Negociado (R$ mil) *", "NegotiatedValue", pl.Float64),
+    ("PMR", "PMR", pl.Float64),
+    ("Convexidade", "Convexity", pl.Float64),
+]
 
 # Derivados automaticamente
-ESQUEMA_IMA = {k: v[1] for k, v in IMA_COLUNAS.items()}
-MAPA_COLUNAS_IMA = {k: v[0] for k, v in IMA_COLUNAS.items() if v[0] is not None}
+ESQUEMA_IMA = {csv: tipo for csv, _, tipo in IMA_COLUNAS}
+MAPA_COLUNAS_IMA = {csv: novo for csv, novo, _ in IMA_COLUNAS if novo is not None}
 
 ORDEM_COLUNAS_FINAL = [
     "Date",
@@ -81,6 +82,7 @@ ORDEM_COLUNAS_FINAL = [
 URL_ULTIMO_IMA = "https://www.anbima.com.br/informacoes/ima/arqs/ima_completo.txt"
 
 
+@cachetools.cached(cache=cachetools.TTLCache(maxsize=16, ttl=60))
 @retry_padrao
 def _buscar_texto_ultimo_ima() -> str:
     resposta = requests.get(URL_ULTIMO_IMA, timeout=3)

{pyield-0.44.0 → pyield-0.44.2}/pyield/anbima/imaq.py

@@ -17,27 +17,28 @@ from lxml.html import HTMLParser
 from lxml.html import fromstring as html_fromstring
 
 import pyield._internal.converters as cv
-from pyield.anbima.tpf import tpf_data
+from pyield import bday
 from pyield._internal.types import DateLike, any_is_empty
+from pyield.anbima.tpf import tpf_data
 
 logger = logging.getLogger(__name__)
 
 URL_IMA = "https://www.anbima.com.br/informacoes/ima/ima-quantidade-mercado.asp"
 
-MAPA_COLUNAS = {
-    "Título": ("BondType", pl.String),
-    "Codigo Selic": ("SelicCode", pl.Int64),
-    "Código ISIN": ("ISIN", pl.String),
-    "Data de Vencimento": ("MaturityDate", pl.String),
-    "Quantidade em Mercado (1.000 Títulos)": ("MarketQuantity", pl.Float64),
-    "PU (R$)": ("Price", pl.Float64),
-    "Valor de Mercado (R$ Mil)": ("MarketValue", pl.Float64),
-    "Variação da Quantidade (1.000 Títulos)": ("QuantityVariation", pl.Float64),
-    "Status do Titulo": ("BondStatus", pl.String),
-}
-
-ALIAS_COLUNAS = {col: alias for col, (alias, _) in MAPA_COLUNAS.items()}
-ESQUEMA_DADOS = {alias: dtype for _, (alias, dtype) in MAPA_COLUNAS.items()}
+MAPA_COLUNAS = [
+    ("Título", "BondType", pl.String),
+    ("Codigo Selic", "SelicCode", pl.Int64),
+    ("Código ISIN", "ISIN", pl.String),
+    ("Data de Vencimento", "MaturityDate", pl.String),
+    ("Quantidade em Mercado (1.000 Títulos)", "MarketQuantity", pl.Float64),
+    ("PU (R$)", "Price", pl.Float64),
+    ("Valor de Mercado (R$ Mil)", "MarketValue", pl.Float64),
+    ("Variação da Quantidade (1.000 Títulos)", "QuantityVariation", pl.Float64),
+    ("Status do Titulo", "BondStatus", pl.String),
+]
+
+ALIAS_COLUNAS = {html: novo for html, novo, _ in MAPA_COLUNAS}
+ESQUEMA_DADOS = {novo: tipo for _, novo, tipo in MAPA_COLUNAS}
 
 COLUNAS_INT = [
     "MarketQuantity",
@@ -246,9 +247,10 @@ def imaq(date: DateLike) -> pl.DataFrame:
         True
     """
     if any_is_empty(date):
-        logger.warning("Nenhuma data informada. Retornando DataFrame vazio.")
         return pl.DataFrame()
     data = cv.converter_datas(date)
+    if not bday.is_business_day(data):
+        return pl.DataFrame()
     data_str = data.strftime("%d/%m/%Y")
     try:
         url_content = _buscar_conteudo_url(data)

{pyield-0.44.0 → pyield-0.44.2}/pyield/anbima/tpf.py

@@ -9,15 +9,15 @@ import requests
 from requests.exceptions import HTTPError, RequestException
 
 from pyield import bday, clock
-from pyield.b3 import di1
-from pyield.bc.ptax_api import ptax
 from pyield._internal.converters import converter_datas
 from pyield._internal.data_cache import obter_dataset_cacheado
 from pyield._internal.retry import retry_padrao
+from pyield._internal.types import DateLike, any_is_empty
+from pyield.b3 import di1
+from pyield.bc.ptax_api import ptax
 from pyield.tn.ntnb import duration as duration_b
 from pyield.tn.ntnc import duration as duration_c
 from pyield.tn.ntnf import duration as duration_f
-from pyield._internal.types import DateLike, any_is_empty
 
 BOND_TYPES = Literal["LFT", "NTN-B", "NTN-C", "LTN", "NTN-F", "PRE"]
 
@@ -31,29 +31,29 @@ DATA_MUDANCA_FORMATO = dt.date(2014, 5, 13)
 
 DIAS_RETENCAO_PUBLICA = 5
 
-# Única fonte de verdade para colunas do CSV: (novo_nome, tipo)
+# Única fonte de verdade para colunas do CSV: (nome_csv, nome_novo, tipo)
 # Colunas de data são lidas como String e convertidas em _processar_df_bruto
-TPF_COLUNAS = {
-    "Titulo": ("BondType", pl.String),
-    "Data Referencia": ("ReferenceDate", pl.String),
-    "Codigo SELIC": ("SelicCode", pl.Int64),
-    "Data Base/Emissao": ("IssueBaseDate", pl.String),
-    "Data Vencimento": ("MaturityDate", pl.String),
-    "Tx. Compra": ("BidRate", pl.Float64),
-    "Tx. Venda": ("AskRate", pl.Float64),
-    "Tx. Indicativas": ("IndicativeRate", pl.Float64),
-    "PU": ("Price", pl.Float64),
-    "Desvio padrao": ("StdDev", pl.Float64),
-    "Interv. Ind. Inf. (D0)": ("LowerBoundRateD0", pl.Float64),
-    "Interv. Ind. Sup. (D0)": ("UpperBoundRateD0", pl.Float64),
-    "Interv. Ind. Inf. (D+1)": ("LowerBoundRateD1", pl.Float64),
-    "Interv. Ind. Sup. (D+1)": ("UpperBoundRateD1", pl.Float64),
-    "Criterio": ("Criteria", pl.String),
-}
+TPF_COLUNAS = [
+    ("Titulo", "BondType", pl.String),
+    ("Data Referencia", "ReferenceDate", pl.String),
+    ("Codigo SELIC", "SelicCode", pl.Int64),
+    ("Data Base/Emissao", "IssueBaseDate", pl.String),
+    ("Data Vencimento", "MaturityDate", pl.String),
+    ("Tx. Compra", "BidRate", pl.Float64),
+    ("Tx. Venda", "AskRate", pl.Float64),
+    ("Tx. Indicativas", "IndicativeRate", pl.Float64),
+    ("PU", "Price", pl.Float64),
+    ("Desvio padrao", "StdDev", pl.Float64),
+    ("Interv. Ind. Inf. (D0)", "LowerBoundRateD0", pl.Float64),
+    ("Interv. Ind. Sup. (D0)", "UpperBoundRateD0", pl.Float64),
+    ("Interv. Ind. Inf. (D+1)", "LowerBoundRateD1", pl.Float64),
+    ("Interv. Ind. Sup. (D+1)", "UpperBoundRateD1", pl.Float64),
+    ("Criterio", "Criteria", pl.String),
+]
 
 # Derivados automaticamente
-ESQUEMA_TPF = {k: v[1] for k, v in TPF_COLUNAS.items()}
-MAPA_NOMES_COLUNAS = {k: v[0] for k, v in TPF_COLUNAS.items()}
+ESQUEMA_TPF = {csv: tipo for csv, _, tipo in TPF_COLUNAS}
+MAPA_NOMES_COLUNAS = {csv: novo for csv, novo, _ in TPF_COLUNAS}
 
 logger = logging.getLogger(__name__)
 
@@ -345,25 +345,7 @@ def tpf_data(
 
     Examples:
         >>> from pyield import anbima
-        >>> anbima.tpf_data(date="22-08-2025")
-        shape: (49, 14)
-        ┌───────────────┬──────────┬───────────┬───────────────┬───┬───────────┬───────────┬────────────────┬──────────┐
-        │ ReferenceDate ┆ BondType ┆ SelicCode ┆ IssueBaseDate ┆ … ┆ BidRate   ┆ AskRate   ┆ IndicativeRate ┆ DIRate   │
-        │ ---           ┆ ---      ┆ ---       ┆ ---           ┆   ┆ ---       ┆ ---       ┆ ---            ┆ ---      │
-        │ date          ┆ str      ┆ i64       ┆ date          ┆   ┆ f64       ┆ f64       ┆ f64            ┆ f64      │
-        ╞═══════════════╪══════════╪═══════════╪═══════════════╪═══╪═══════════╪═══════════╪════════════════╪══════════╡
-        │ 2025-08-22    ┆ LFT      ┆ 210100    ┆ 2000-07-01    ┆ … ┆ 0.000198  ┆ 0.0001    ┆ 0.000165       ┆ 0.14906  │
-        │ 2025-08-22    ┆ LFT      ┆ 210100    ┆ 2000-07-01    ┆ … ┆ -0.000053 ┆ -0.000156 ┆ -0.000116      ┆ 0.14843  │
-        │ 2025-08-22    ┆ LFT      ┆ 210100    ┆ 2000-07-01    ┆ … ┆ -0.000053 ┆ -0.000143 ┆ -0.000107      ┆ 0.1436   │
-        │ 2025-08-22    ┆ LFT      ┆ 210100    ┆ 2000-07-01    ┆ … ┆ 0.000309  ┆ 0.000292  ┆ 0.000302       ┆ 0.138189 │
-        │ 2025-08-22    ┆ LFT      ┆ 210100    ┆ 2000-07-01    ┆ … ┆ 0.000421  ┆ 0.000399  ┆ 0.000411       ┆ 0.134548 │
-        │ …             ┆ …        ┆ …         ┆ …             ┆ … ┆ …         ┆ …         ┆ …              ┆ …        │
-        │ 2025-08-22    ┆ NTN-F    ┆ 950199    ┆ 2016-01-15    ┆ … ┆ 0.139379  ┆ 0.139163  ┆ 0.139268       ┆ 0.13959  │
-        │ 2025-08-22    ┆ NTN-F    ┆ 950199    ┆ 2018-01-05    ┆ … ┆ 0.134252  ┆ 0.134018  ┆ 0.13414        ┆ 0.1327   │
-        │ 2025-08-22    ┆ NTN-F    ┆ 950199    ┆ 2020-01-10    ┆ … ┆ 0.13846   ┆ 0.138355  ┆ 0.13841        ┆ 0.13626  │
-        │ 2025-08-22    ┆ NTN-F    ┆ 950199    ┆ 2022-01-07    ┆ … ┆ 0.139503  ┆ 0.139321  ┆ 0.139398       ┆ 0.13807  │
-        │ 2025-08-22    ┆ NTN-F    ┆ 950199    ┆ 2024-01-05    ┆ … ┆ 0.140673  ┆ 0.140566  ┆ 0.140633       ┆ 0.13845  │
-        └───────────────┴──────────┴───────────┴───────────────┴───┴───────────┴───────────┴────────────────┴──────────┘
+        >>> df = anbima.tpf_data(date="06-02-2026")
 
     Data columns:
         - BondType: Tipo do título público (e.g., 'LTN', 'NTN-B').
@@ -399,13 +381,15 @@ def tpf_data(
             datas com mais de 5 dias úteis. O acesso ao histórico completo
             requer uma conexão à rede RTM. Sem ela, a consulta para datas
             antigas retornará um DataFrame vazio.
-    """  # noqa
+    """
     if any_is_empty(date):
         return pl.DataFrame()
     date = converter_datas(date)
     _validar_data_nao_futura(date)
 
     if fetch_from_source:
+        if not bday.is_business_day(date):
+            return pl.DataFrame()
         # Tenta buscar os dados diretamente da fonte (ANBIMA)
         df = _buscar_dados_tpf(date)
     else:

{pyield-0.44.0 → pyield-0.44.2}/pyield/b3/futures/__init__.py

@@ -1,28 +1,15 @@
 import logging
-from collections.abc import Sequence
-from typing import Literal
 
 import polars as pl
 
 import pyield._internal.converters as cv
 from pyield import clock
+from pyield._internal.retry import DadoIndisponivelError
 from pyield._internal.types import DateLike, any_is_empty
 from pyield.b3._contracts import normalizar_codigos_contrato
 from pyield.b3._validar_pregao import data_negociacao_valida
 from pyield.b3.futures import historical, intraday
 
-OpcoesContrato = Literal[
-    "DI1",
-    "DDI",
-    "FRC",
-    "FRO",
-    "DAP",
-    "DOL",
-    "WDO",
-    "IND",
-    "WIN",
-]
-
 logger = logging.getLogger(__name__)
 
 
@@ -36,12 +23,17 @@ def _buscar_intraday_ou_historico(
         return pl.DataFrame()
 
     if horario_atual >= intraday.HORA_FIM_INTRADAY:
-        df_historico = historical.historical(
-            data_negociacao, codigos_contrato, full_report
-        )
-        if not df_historico.is_empty():
-            logger.info("Dados consolidados disponíveis. Usando histórico.")
-            return df_historico
+        for tentativa_full_report in (full_report, not full_report):
+            try:
+                df_historico = historical.historical(
+                    data_negociacao, codigos_contrato, tentativa_full_report
+                )
+            except DadoIndisponivelError:
+                continue
+            if not df_historico.is_empty():
+                logger.info("Dados consolidados disponíveis. Usando histórico.")
+                return df_historico
+        logger.info("Histórico consolidado indisponível. Tentando intraday.")
 
     dataframes_intraday = [intraday.intraday(codigo) for codigo in codigos_contrato]
     dataframes_intraday = [df for df in dataframes_intraday if not df.is_empty()]
@@ -54,7 +46,7 @@ def _buscar_intraday_ou_historico(
 
 def futures(
     date: DateLike,
-    contract_code: OpcoesContrato | str | Sequence[OpcoesContrato | str] | pl.Series,
+    contract_code: str | list[str],
     full_report: bool = False,
 ) -> pl.DataFrame:
     """Busca dados de um contrato futuro da B3 para a data de referência.
@@ -62,6 +54,11 @@ def futures(
     Args:
         date: Data de referência para consulta.
         contract_code: Código do contrato futuro na B3 ou coleção de códigos.
+            Exemplos de códigos válidos:
+            - Juros: DI1, DDI, OC1, DAP, IAP
+            - Moedas: DOL, WDO, EUR, GBR, JAP, CNY
+            - Índices: IND, WIN, ISP, WSP
+            - Commodities: BGI, CCM, ICF, CNL, SJC, SOY, ETH, GLD
         full_report: Se False (padrão), usa o simplified price report (SPR),
             arquivo leve (~2 KB) com apenas preços de ajuste. Se True, usa o
             price report completo (PR, ~2 MB) com todos os dados de negociação.
@@ -70,22 +67,15 @@ def futures(
     Returns:
         DataFrame Polars com os dados do contrato informado.
 
+    Notes:
+        Os contratos DI1, DDI, FRC, FRO, DAP, DOL, WDO, IND e WIN possuem
+        histórico pré-cacheado (desde 2018) e são retornados instantaneamente.
+        Para os demais contratos, os dados são baixados diretamente da B3 a
+        cada chamada, o que pode ser mais lento.
+
     Examples:
         >>> df = futures("31-05-2024", "DI1")
-        >>> {"TradeDate", "TickerSymbol", "ExpirationDate", "SettlementRate"}.issubset(
-        ...     set(df.columns)
-        ... )
-        True
-        >>> df.shape[0] > 0
-        True
-
         >>> df = futures("31-05-2024", "DAP")
-        >>> {"TradeDate", "TickerSymbol", "ExpirationDate", "SettlementRate"}.issubset(
-        ...     set(df.columns)
-        ... )
-        True
-        >>> df.shape[0] > 0
-        True
 
         Véspera de Natal e Ano Novo não têm pregão:
 

{pyield-0.44.0 → pyield-0.44.2}/pyield/b3/futures/historical.py

@@ -1,5 +1,4 @@
 import datetime as dt
-from collections.abc import Sequence
 
 import polars as pl
 
@@ -17,7 +16,7 @@ CONTRATOS_TAXA = {"DI1", "DAP", "DDI", "FRC", "FRO"}
 
 def historical(
     data: dt.date,
-    codigo_contrato: str | Sequence[str] | pl.Series,
+    codigo_contrato: str | list[str],
     full_report: bool = False,
 ) -> pl.DataFrame:
     """Busca histórico de futuros priorizando o dataset PR cacheado.

{pyield-0.44.0 → pyield-0.44.2}/pyield/b3/intraday_derivatives.py

@@ -1,5 +1,6 @@
 import logging
 
+import cachetools
 import polars as pl
 import requests
 
@@ -49,6 +50,7 @@ def _mapa_renomeacao_intraday() -> dict[str, str]:
     return {nome_orig: nome_novo for nome_orig, nome_novo, _ in COLUNAS_INTRADAY}
 
 
+@cachetools.cached(cache=cachetools.TTLCache(maxsize=16, ttl=15))
 @retry_padrao
 def _buscar_json_intraday(codigo_contrato: str) -> list[dict]:
     url = f"{URL_BASE_INTRADAY}/{codigo_contrato}"

{pyield-0.44.0 → pyield-0.44.2}/pyield/b3/price_report.py

@@ -12,7 +12,7 @@ from lxml.etree import _Element
 import pyield._internal.converters as cv
 from pyield._internal.retry import DadoIndisponivelError, retry_padrao
 from pyield._internal.types import DateLike, any_is_empty
-from pyield.b3._contracts import normalizar_codigo_contrato
+from pyield.b3._contracts import normalizar_codigos_contrato
 from pyield.b3._validar_pregao import data_negociacao_valida
 
 registro = logging.getLogger(__name__)
@@ -236,7 +236,7 @@ def _obter_xml_price_report(data: dt.date, relatorio_completo: bool) -> bytes:
 
 def fetch_price_report(
     date: DateLike,
-    contract_code: str,
+    contract_code: str | list[str],
     full_report: bool = False,
 ) -> pl.DataFrame:
     """Busca e processa o price report da B3 no site oficial.
@@ -257,8 +257,8 @@ def fetch_price_report(
     Args:
         date: Data de negociação no formato 'DD-MM-YYYY', 'DD/MM/YYYY',
             'YYYY-MM-DD' ou objeto datetime.date.
-        contract_code: Código B3 (ex.: 'DI1', 'DOL', 'DAP', 'FRC', 'DDI',
-            'WDO', 'IND', 'WIN'). Os 3 primeiros caracteres são usados no XML.
+        contract_code: Código B3 único ou lista de códigos (ex.: 'DI1',
+            ['DI1', 'DAP']). Os 3 primeiros caracteres são usados no XML.
         full_report: Se False (padrão), usa o simplified price report (SPR),
             arquivo leve (~2 KB) com apenas preços de ajuste. Se True, usa o
             price report completo (PR, ~2 MB) com todos os dados de negociação.
@@ -311,7 +311,6 @@ def fetch_price_report(
         - MinLimitValue (Float64): Limite mínimo de variação.
 
     Raises:
-        ValueError: Se full_report não for bool.
         DadoIndisponivelError: Se a data for válida, mas o endpoint não fornecer
             arquivo para a data consultada.
         requests.HTTPError: Se a requisição HTTP ao endpoint falhar.
@@ -322,18 +321,17 @@ def fetch_price_report(
     Examples:
         >>> import pyield as yd
         >>> df = yd.b3.fetch_price_report("26-04-2024", "DI1")
-        >>> df.is_empty() or {"TradeDate", "TickerSymbol", "CloseValue"}.issubset(
-        ...     set(df.columns)
-        ... )
-        True
+
+        >>> # Múltiplos contratos de uma vez
+        >>> df = yd.b3.fetch_price_report("26-04-2024", ["DI1", "DAP"])
 
         >>> # Feriado ou fim de semana (retorna DataFrame vazio)
         >>> df = yd.b3.fetch_price_report("25-12-2023", "DI1")  # Véspera de Natal
         >>> df.is_empty()
         True
     """
-    contrato = normalizar_codigo_contrato(contract_code)
-    if any_is_empty(date) or not contrato:
+    contratos = normalizar_codigos_contrato(contract_code)
+    if any_is_empty(date) or not contratos:
         return pl.DataFrame()
 
     date = cv.converter_datas(date)
@@ -343,21 +341,28 @@ def fetch_price_report(
 
     try:
         xml_bytes = _obter_xml_price_report(date, full_report)
-        return _processar_xml_extraido(xml_bytes, contrato)
+        dataframes = []
+        for contrato in contratos:
+            df = _processar_xml_extraido(xml_bytes, contrato)
+            if not df.is_empty():
+                dataframes.append(df)
+        if not dataframes:
+            return pl.DataFrame()
+        return pl.concat(dataframes).sort("TickerSymbol")
     except (zipfile.BadZipFile, etree.XMLSyntaxError):
-        registro.exception(f"Falha ao parsear o price report de {contrato} em {date}.")
+        registro.exception(f"Falha ao parsear o price report de {contratos} em {date}.")
         raise
     except Exception:
         tipo = "PR" if full_report else "SPR"
         registro.exception(
-            f"ERRO CRÍTICO: Falha ao processar {contrato} {tipo} em {date}"
+            f"ERRO CRÍTICO: Falha ao processar {contratos} {tipo} em {date}"
         )
         raise
 
 
 def read_price_report(
     xml_bytes: bytes,
-    contract_code: str,
+    contract_code: str | list[str],
 ) -> pl.DataFrame:
     """Lê e processa o price report da B3 a partir do conteúdo XML bruto.
 
@@ -369,7 +374,8 @@ def read_price_report(
 
     Args:
         xml_bytes: Conteúdo do XML em bytes (já descomprimido).
-        contract_code: Código B3 do contrato.
+        contract_code: Código B3 único ou lista de códigos (ex.: 'DI1',
+            ['DI1', 'DAP']).
 
     Returns:
         pl.DataFrame: DataFrame com colunas tipadas e renomeadas, ordenado por
@@ -416,8 +422,15 @@ def read_price_report(
         - MaxLimitValue (Float64): Limite máximo de variação.
         - MinLimitValue (Float64): Limite mínimo de variação.
     """
-    contrato = normalizar_codigo_contrato(contract_code)
-    if any_is_empty(xml_bytes) or not contrato:
+    contratos = normalizar_codigos_contrato(contract_code)
+    if any_is_empty(xml_bytes) or not contratos:
         return pl.DataFrame()
 
-    return _processar_xml_extraido(xml_bytes, contrato)
+    dataframes = []
+    for contrato in contratos:
+        df = _processar_xml_extraido(xml_bytes, contrato)
+        if not df.is_empty():
+            dataframes.append(df)
+    if not dataframes:
+        return pl.DataFrame()
+    return pl.concat(dataframes).sort("TickerSymbol")