PYield 0.44.4__tar.gz → 0.44.5__tar.gz

{pyield-0.44.4 → pyield-0.44.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyield
-Version: 0.44.4
+Version: 0.44.5
 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
@@ -39,7 +39,7 @@ 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
+Requires-Dist: polars>=1.39.0
 Requires-Dist: python-dateutil>=2.8.0
 Requires-Dist: requests>=2.31.0
 Requires-Dist: tenacity>=9.0.0
@@ -173,13 +173,18 @@ forwards(bdays, rates)  # -> Series: [0.05, 0.070095, 0.090284]
 | Módulo | Finalidade |
 |--------|---------|
 | `bday` | Calendário de dias úteis com feriados brasileiros |
-| `futures` | Dados de futuros da B3 (DI1, DDI, FRC, DAP, DOL, WDO, IND, WIN) |
+| `futures` | Dados de futuros da B3 (DI1, DDI, DAP, DOL, WDO, IND, WIN e outros) |
+| `di1` | Curva DI1 interpolada e datas de negociação disponíveis |
 | `Interpolator` | Interpolação de taxas (flat_forward, linear) |
 | `forward` / `forwards` | Cálculo de taxas a termo |
-| `ltn`, `ntnb`, `ntnf`, `lft`, `ntnc` | Precificação e análise de títulos públicos |
+| `ltn`, `ntnb`, `ntnf`, `lft`, `ntnc` | Precificação e análise dos títulos públicos principais |
+| `ntnb1`, `ntnbprinc`, `pre` | Títulos e curvas adicionais (NTN-B1, NTN-B Principal, curva PRE) |
+| `tn.auction` / `tn.benchmarks` | Leilões e benchmarks de títulos públicos |
 | `anbima` | Dados da ANBIMA (preços de TPF, curvas de juros, índices IMA) |
-| `bc` | Indicadores do BCB (SELIC, PTAX, repos, VNA) |
+| `bc` | Indicadores do BCB (SELIC, PTAX, repos, VNA, leilões, negociações) |
+| `b3` | Dados da B3 (DI over, price reports, derivativos intradiários) |
 | `ipca` | Dados de inflação (histórico e projeções) |
+| `selic` | Opções digitais de COPOM e probabilidades implícitas |
 | `rmd` | Relatório Mensal da Dívida do Tesouro Nacional |
 | `today` / `now` | Data/hora atual no Brasil (America/Sao_Paulo) |
 
@@ -209,9 +214,16 @@ from pyield import futures
 # DI1 (Futuro de Depósito Interfinanceiro)
 futures("31-05-2024", "DI1")
 
-# Outros contratos: DDI, FRC, DAP, DOL, WDO, IND, WIN
+# Outros contratos disponíveis:
+# - 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
 futures("31-05-2024", "DAP")
 
+# Múltiplos contratos de uma vez
+futures("31-05-2024", ["DI1", "DAP"])
+
 # Dados intradiários (quando o mercado estiver aberto)
 futures("16-01-2025", "DI1")  # Retorna dados ao vivo durante o horário de negociação
 ```
@@ -221,7 +233,6 @@ futures("16-01-2025", "DI1")  # Retorna dados ao vivo durante o horário de nego
 PYield aceita entradas de data flexíveis (`DateLike`):
 - Strings: `"31-05-2024"`, `"31/05/2024"`, `"2024-05-31"`
 - `datetime.date`, `datetime.datetime`
-- `pandas.Timestamp`, `numpy.datetime64`
 
 Funções escalares retornam `datetime.date`. Funções vetorizadas retornam `polars.Series`.
 
@@ -241,9 +252,14 @@ bday.count(["01-01-2024", None], "01-02-2024")  # -> Series: [22, null]
 
 ## Migração para Polars (v0.40.0+)
 
-Todas as funções retornam **DataFrames/Series do Polars**. Para converter para Pandas:
+A partir da versão 0.40.0, todas as saídas tabulares passaram de Pandas para **Polars**. Entradas vetoriais que antes aceitavam `pd.Series` e `np.ndarray` agora aceitam apenas listas, tuplas ou `pl.Series`. Para converter:
 
 ```python
+# Entrada: converter coleções Pandas/NumPy antes de passar para o PYield
+pl_series = pl.from_pandas(pd_series)   # pd.Series → pl.Series (requer pandas)
+pl_series = pl.Series(np_array)         # np.ndarray → pl.Series (requer numpy)
+
+# Saída: converter DataFrame Polars para Pandas
 df_pandas = df.to_pandas(use_pyarrow_extension_array=True)
 ```
 
@@ -254,5 +270,5 @@ Documentação completa: [crdcj.github.io/PYield](https://crdcj.github.io/PYield
 ## Testes
 
 ```sh
-pytest pyield --doctest-modules
+pytest
 ```

{pyield-0.44.4 → pyield-0.44.5}/README.md

@@ -126,13 +126,18 @@ forwards(bdays, rates)  # -> Series: [0.05, 0.070095, 0.090284]
 | Módulo | Finalidade |
 |--------|---------|
 | `bday` | Calendário de dias úteis com feriados brasileiros |
-| `futures` | Dados de futuros da B3 (DI1, DDI, FRC, DAP, DOL, WDO, IND, WIN) |
+| `futures` | Dados de futuros da B3 (DI1, DDI, DAP, DOL, WDO, IND, WIN e outros) |
+| `di1` | Curva DI1 interpolada e datas de negociação disponíveis |
 | `Interpolator` | Interpolação de taxas (flat_forward, linear) |
 | `forward` / `forwards` | Cálculo de taxas a termo |
-| `ltn`, `ntnb`, `ntnf`, `lft`, `ntnc` | Precificação e análise de títulos públicos |
+| `ltn`, `ntnb`, `ntnf`, `lft`, `ntnc` | Precificação e análise dos títulos públicos principais |
+| `ntnb1`, `ntnbprinc`, `pre` | Títulos e curvas adicionais (NTN-B1, NTN-B Principal, curva PRE) |
+| `tn.auction` / `tn.benchmarks` | Leilões e benchmarks de títulos públicos |
 | `anbima` | Dados da ANBIMA (preços de TPF, curvas de juros, índices IMA) |
-| `bc` | Indicadores do BCB (SELIC, PTAX, repos, VNA) |
+| `bc` | Indicadores do BCB (SELIC, PTAX, repos, VNA, leilões, negociações) |
+| `b3` | Dados da B3 (DI over, price reports, derivativos intradiários) |
 | `ipca` | Dados de inflação (histórico e projeções) |
+| `selic` | Opções digitais de COPOM e probabilidades implícitas |
 | `rmd` | Relatório Mensal da Dívida do Tesouro Nacional |
 | `today` / `now` | Data/hora atual no Brasil (America/Sao_Paulo) |
 
@@ -162,9 +167,16 @@ from pyield import futures
 # DI1 (Futuro de Depósito Interfinanceiro)
 futures("31-05-2024", "DI1")
 
-# Outros contratos: DDI, FRC, DAP, DOL, WDO, IND, WIN
+# Outros contratos disponíveis:
+# - 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
 futures("31-05-2024", "DAP")
 
+# Múltiplos contratos de uma vez
+futures("31-05-2024", ["DI1", "DAP"])
+
 # Dados intradiários (quando o mercado estiver aberto)
 futures("16-01-2025", "DI1")  # Retorna dados ao vivo durante o horário de negociação
 ```
@@ -174,7 +186,6 @@ futures("16-01-2025", "DI1")  # Retorna dados ao vivo durante o horário de nego
 PYield aceita entradas de data flexíveis (`DateLike`):
 - Strings: `"31-05-2024"`, `"31/05/2024"`, `"2024-05-31"`
 - `datetime.date`, `datetime.datetime`
-- `pandas.Timestamp`, `numpy.datetime64`
 
 Funções escalares retornam `datetime.date`. Funções vetorizadas retornam `polars.Series`.
 
@@ -194,9 +205,14 @@ bday.count(["01-01-2024", None], "01-02-2024")  # -> Series: [22, null]
 
 ## Migração para Polars (v0.40.0+)
 
-Todas as funções retornam **DataFrames/Series do Polars**. Para converter para Pandas:
+A partir da versão 0.40.0, todas as saídas tabulares passaram de Pandas para **Polars**. Entradas vetoriais que antes aceitavam `pd.Series` e `np.ndarray` agora aceitam apenas listas, tuplas ou `pl.Series`. Para converter:
 
 ```python
+# Entrada: converter coleções Pandas/NumPy antes de passar para o PYield
+pl_series = pl.from_pandas(pd_series)   # pd.Series → pl.Series (requer pandas)
+pl_series = pl.Series(np_array)         # np.ndarray → pl.Series (requer numpy)
+
+# Saída: converter DataFrame Polars para Pandas
 df_pandas = df.to_pandas(use_pyarrow_extension_array=True)
 ```
 
@@ -207,5 +223,5 @@ Documentação completa: [crdcj.github.io/PYield](https://crdcj.github.io/PYield
 ## Testes
 
 ```sh
-pytest pyield --doctest-modules
+pytest
 ```

pyield-0.44.5/pyield/__about__.py

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

{pyield-0.44.4 → pyield-0.44.5}/pyield/_internal/converters.py

@@ -69,7 +69,7 @@ def converter_datas(
 
     Normaliza datas em diversos formatos para um tipo consistente:
     - Entradas escalares (str, date, datetime) retornam ``datetime.date``
-    - Coleções (list, tuple, ndarray, Series) retornam ``pl.Series`` com dtype ``Date``
+    - Coleções (list, tuple, Series) retornam ``pl.Series`` com dtype ``Date``
     - Entradas nulas retornam ``None``
 
     O parse de strings é feito por elemento com fallback entre formatos
@@ -79,7 +79,7 @@ def converter_datas(
         dates: Data(s) a converter. Aceita:
             - String nos formatos ``dd-mm-YYYY``, ``dd/mm/YYYY`` ou ``YYYY-mm-dd``
             - ``datetime.date`` ou ``datetime.datetime``
-            - Lista, tupla, ndarray ou Series de datas
+            - Lista, tupla ou Series de datas
             - ``None``
 
     Returns:

{pyield-0.44.4 → pyield-0.44.5}/pyield/anbima/tpf.py

@@ -58,14 +58,6 @@ MAPA_NOMES_COLUNAS = {csv: novo for csv, novo, _ in TPF_COLUNAS}
 logger = logging.getLogger(__name__)
 
 
-def _validar_data_nao_futura(data: dt.date):
-    """Levanta ValueError se a data for no futuro."""
-    if data > clock.today():
-        data_log = data.strftime("%d/%m/%Y")
-        msg = f"Não é possível processar dados para data futura ({data_log})."
-        raise ValueError(msg)
-
-
 def _mapear_tipo_titulo(tipo_titulo: str) -> list[str]:
     tipo_titulo = tipo_titulo.upper()
     mapa_titulos = {
@@ -189,6 +181,17 @@ def _adicionar_duracao(df_input: pl.DataFrame) -> pl.DataFrame:
     return df
 
 
+def _adicionar_prazo_medio(df: pl.DataFrame) -> pl.DataFrame:
+    # Na metodologia do Tesouro Nacional, a maturidade média é a mesma que a duração
+    df = df.with_columns(
+        pl.when(pl.col("BondType") == "LFT")
+        .then(pl.col("BDToMat") / 252)
+        .otherwise("Duration")
+        .alias("AvgMaturity")
+    )
+    return df
+
+
 def _adicionar_dv01(df_input: pl.DataFrame, data_ref: dt.date) -> pl.DataFrame:
     """Adiciona as colunas de DV01 ao DataFrame."""
     expr_duracao_mod = pl.col("Duration") / (1 + pl.col("IndicativeRate"))
@@ -224,6 +227,7 @@ def _selecionar_e_ordenar_colunas(df: pl.DataFrame) -> pl.DataFrame:
         "MaturityDate",
         "BDToMat",
         "Duration",
+        "AvgMaturity",
         "DV01",
         "DV01USD",
         "Price",
@@ -231,11 +235,11 @@ def _selecionar_e_ordenar_colunas(df: pl.DataFrame) -> pl.DataFrame:
         "AskRate",
         "IndicativeRate",
         "DIRate",
-        "StdDev",
-        "LowerBoundRateD0",
-        "UpperBoundRateD0",
-        "LowerBoundRateD1",
-        "UpperBoundRateD1",
+        # "StdDev",
+        # "LowerBoundRateD0",
+        # "UpperBoundRateD0",
+        # "LowerBoundRateD1",
+        # "UpperBoundRateD1",
         "Criteria",
     ]
     ordem_colunas = [col for col in ordem_colunas if col in df.columns]
@@ -288,6 +292,7 @@ def _buscar_dados_tpf(date: dt.date) -> pl.DataFrame:
         df = _ler_csv(csv_texto)
         df = _processar_df_bruto(df)
         df = _adicionar_duracao(df)
+        df = _adicionar_prazo_medio(df)
         df = _adicionar_dv01(df, date)
         df = _adicionar_taxa_di(df, date)
         df = _selecionar_e_ordenar_colunas(df)
@@ -355,6 +360,8 @@ def tpf_data(
         - MaturityDate: Data de vencimento do título.
         - BDToMat: Número de dias úteis entre a data de referência e o vencimento.
         - Duration: Macaulay Duration do título em anos.
+        - AvgMaturity: Prazo médio do título (em anos), conforme metodologia
+            do Tesouro Nacional.
         - DV01: Variação financeira no preço do título (em BRL) para uma
             mudança de 1 basis point (0,01%) na taxa de juros.
         - DV01USD: O mesmo que DV01, mas convertido para USD pela PTAX do dia.
@@ -385,11 +392,14 @@ def tpf_data(
     if any_is_empty(date):
         return pl.DataFrame()
     date = converter_datas(date)
-    _validar_data_nao_futura(date)
+
+    if not bday.is_business_day(date):
+        return pl.DataFrame()
+
+    if date > clock.today():
+        return pl.DataFrame()
 
     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.4 → pyield-0.44.5}/pyield/b3/di1.py

@@ -1,85 +1,10 @@
-import datetime as dt
-import logging
-
 import polars as pl
 
 import pyield._internal.converters as cv
 from pyield import b3, bday, interpolator
 from pyield._internal.data_cache import obter_dataset_cacheado
 from pyield._internal.types import ArrayLike, DateLike, any_is_collection, any_is_empty
-from pyield.b3.futures import historical as futuros_historico
-
-registro = logging.getLogger(__name__)
-
-
-def _carregar_cache_pr_di1(datas: list[dt.date]) -> pl.DataFrame:
-    """Carrega e processa DI1 a partir do dataset PR para as datas informadas."""
-    return futuros_historico.carregar_pr(datas=datas, codigo_contrato="DI1")
-
-
-def _carregar_com_intraday(datas: list[dt.date]) -> pl.DataFrame:
-    """Busca dados de DI, incluindo dados intraday para datas ausentes no cache.
-
-    Args:
-        datas: Lista de datas a buscar.
-
-    Returns:
-        DataFrame com dados de DI para as datas solicitadas.
-    """
-    # 1. Busca inicial no cache PR com as datas solicitadas pelo usuário.
-    df_cache = _carregar_cache_pr_di1(datas)
-    if df_cache.is_empty():
-        datas_cache = set()
-    else:
-        datas_cache = set(df_cache["TradeDate"].drop_nulls())
-
-    # 2. Identifica datas solicitadas que não estão no cache
-    datas_solicitadas = set(datas)
-    datas_faltantes = datas_solicitadas - datas_cache
-
-    # 3. Para cada data faltante, tenta buscar dados via API
-    dfs_concat = [df_cache] if not df_cache.is_empty() else []
-
-    for data_ref in datas_faltantes:
-        try:
-            df_faltante = b3.futures(contract_code="DI1", date=data_ref)
-
-            # Só adiciona se tiver SettlementPrice
-            if "SettlementPrice" in df_faltante.columns:
-                dfs_concat.append(df_faltante)
-            else:
-                registro.warning(
-                    "Dados para %s não contêm 'SettlementPrice'. Pulando esta data.",
-                    data_ref,
-                )
-        except Exception as e:
-            registro.error("Falha ao buscar dados para %s: %s", data_ref, e)
-
-    # 4. Retorna concatenação de todos os DataFrames disponíveis
-    if len(dfs_concat) == 0:
-        return pl.DataFrame()
-    elif len(dfs_concat) == 1:
-        return dfs_concat[0]
-    else:
-        return pl.concat(dfs_concat, how="diagonal")
-
-
-def _obter_dados(datas: DateLike | ArrayLike) -> pl.DataFrame:
-    datas_unicas = cv.converter_datas(datas)
-    if datas_unicas is None:
-        return pl.DataFrame()
-
-    if isinstance(datas_unicas, pl.Series):
-        datas_unicas = datas_unicas.drop_nulls().unique().sort().to_list()
-    else:
-        datas_unicas = [datas_unicas]
-
-    df = _carregar_com_intraday(datas_unicas)
-
-    if df.is_empty():
-        return pl.DataFrame()
-
-    return df.sort("TradeDate", "ExpirationDate")
+from pyield.b3.futures import available_dates as _listar_datas
 
 
 def data(
@@ -122,7 +47,15 @@ def data(
     if any_is_empty(dates):
         return pl.DataFrame()
 
-    df = _obter_dados(datas=dates)
+    datas_convertidas = cv.converter_datas(dates)
+    if datas_convertidas is None:
+        return pl.DataFrame()
+    if isinstance(datas_convertidas, pl.Series):
+        datas_lista = datas_convertidas.drop_nulls().unique().sort().to_list()
+    else:
+        datas_lista = [datas_convertidas]
+
+    df = b3.futures(date=datas_lista, contract_code="DI1", full_report=False)
     if df.is_empty():
         return df
 
@@ -257,9 +190,9 @@ def interpolate_rates(
     if df_entrada.is_empty():
         return pl.Series(dtype=pl.Float64)
 
-    # Carrega dataset de taxas DI filtrado pelas datas de referência fornecidas
-    # Usa datas já convertidas do DataFrame de entrada para evitar conversão dupla
-    df_ref = _obter_dados(datas=dates)
+    # Carrega dataset de taxas DI usando datas já convertidas do df_entrada
+    datas_unicas = df_entrada["TradeDate"].drop_nulls().unique().sort().to_list()
+    df_ref = b3.futures(date=datas_unicas, contract_code="DI1", full_report=False)
     # Retorna Series vazia se nenhuma taxa for encontrada
     if df_ref.is_empty():
         return pl.Series(dtype=pl.Float64)
@@ -380,25 +313,26 @@ def interpolate_rate(
     if valor is None:
         return float("nan")
 
-    return float(valor)
+    return valor
 
 
-def available_trade_dates() -> pl.Series:
-    """Retorna todas as datas de negociação disponíveis para DI1 em futures.
+def available_dates() -> pl.Series:
+    """Retorna as datas de negociação disponíveis para DI1.
 
-    Obtém valores distintos de 'TradeDate' para DI1, com base no mesmo
-    dataset PR utilizado por `futures`.
+    Obtém valores distintos de 'TradeDate' para DI1, com base no dataset histórico
+    PR da B3 (mesmo utilizado por `futures`). Inclui apenas datas com preço e taxa
+    de ajuste já definidos; o pregão do dia corrente não está incluído.
 
     Returns:
-        Series ordenada de datas de negociação únicas (dt.date) para as quais
-        dados de DI estão disponíveis.
+        Series ordenada de datas de negociação (dt.date) para as quais dados de
+        ajuste de DI estão disponíveis.
 
     Examples:
         >>> from pyield import di1
         >>> # Série disponível no dataset PR começa em 2018-01-02
-        >>> di1.available_trade_dates().head(5)
+        >>> di1.available_dates().head(5)
         shape: (5,)
-        Series: 'available_dates' [date]
+        Series: 'TradeDate' [date]
         [
             2018-01-02
             2018-01-03
@@ -407,4 +341,4 @@ def available_trade_dates() -> pl.Series:
             2018-01-08
         ]
     """
-    return futuros_historico.listar_datas_disponiveis("DI1").alias("available_dates")
+    return _listar_datas("DI1")

pyield-0.44.5/pyield/b3/futures/__init__.py

@@ -0,0 +1,191 @@
+import datetime as dt
+import logging
+
+import polars as pl
+
+import pyield._internal.converters as cv
+from pyield import clock
+from pyield._internal.types import ArrayLike, DateLike, any_is_empty, is_collection
+from pyield.b3._contracts import normalizar_codigos_contrato
+from pyield.b3._validar_pregao import data_negociacao_valida
+from pyield.b3.futures import historical, intraday
+
+# A partir desse horário, os dados consolidados (SPR/PR) já estão disponíveis.
+HORA_INICIO_CONSOLIDADO = dt.time(19, 0)
+
+logger = logging.getLogger(__name__)
+
+
+def futures(
+    date: DateLike | ArrayLike,
+    contract_code: str | list[str],
+    full_report: bool | None = None,
+) -> pl.DataFrame:
+    """Busca dados de um contrato futuro da B3 para a data de referência.
+
+    Args:
+        date: Data de referência para consulta ou coleção de datas.
+            Quando uma coleção é fornecida, os dados são buscados para cada
+            data individualmente e concatenados. Datas inválidas (feriados,
+            fins de semana, futuras) são silenciosamente ignoradas.
+        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: Controla a fonte de dados quando o dado não está no cache.
+            Se None (padrão) e a data é hoje: entre 09:16 e 19:00 prioriza
+            dados intraday; a partir das 19:00 prioriza os dados consolidados
+            (SPR → PR) com intraday como fallback.
+            Se False, usa o simplified price report (SPR, ~2 KB).
+            Se True, usa apenas o price report completo (PR, ~2 MB) —
+            indicado para processos batch noturnos.
+
+    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")
+        >>> df = futures("31-05-2024", "DAP")
+
+        Lista de datas:
+
+        >>> df = futures(["29-05-2024", "31-05-2024"], "DI1")
+        >>> df["TradeDate"].unique().sort().to_list()
+        [datetime.date(2024, 5, 29), datetime.date(2024, 5, 31)]
+
+        Véspera de Natal e Ano Novo não têm pregão:
+
+        >>> futures("24-12-2024", "DI1").is_empty()
+        True
+        >>> futures("31-12-2024", "DI1").is_empty()
+        True
+
+        Data futura e fim de semana retornam DataFrame vazio:
+
+        >>> import datetime as dt
+        >>> amanha = dt.date.today() + dt.timedelta(days=1)
+        >>> futures(amanha, "DI1").is_empty()
+        True
+        >>> futures("04-01-2025", "DI1").is_empty()  # sábado
+        True
+
+    """
+    if any_is_empty(date, contract_code):
+        return pl.DataFrame()
+
+    codigos_contrato = normalizar_codigos_contrato(contract_code)
+    if not codigos_contrato:
+        return pl.DataFrame()
+
+    if is_collection(date):
+        # date é ArrayLike neste branch
+        datas: ArrayLike = date  # type: ignore[assignment]
+        return _buscar_varias_datas(datas, codigos_contrato, full_report)
+
+    # date é escalar (DateLike) neste branch
+    data_negociacao: dt.date = cv.converter_datas(date)  # type: ignore[assignment]
+    if not data_negociacao_valida(data_negociacao):
+        return pl.DataFrame()
+
+    return _buscar_por_fonte(data_negociacao, codigos_contrato, full_report)
+
+
+def _buscar_varias_datas(
+    datas: ArrayLike,
+    codigos: list[str],
+    full_report: bool | None,
+) -> pl.DataFrame:
+    """Busca dados para múltiplas datas e concatena os resultados.
+
+    Prioriza o dataset PR cacheado (bulk). Para datas ausentes no cache,
+    busca individualmente via _buscar_por_fonte.
+    """
+    serie_datas = cv.converter_datas(datas)
+    datas_validas = [
+        d for d in serie_datas if d is not None and data_negociacao_valida(d)
+    ]
+    if not datas_validas:
+        return pl.DataFrame()
+
+    # Bulk: carrega todas as datas de uma vez do cache, por contrato
+    resultados = []
+    for codigo in codigos:
+        df_cache = historical.obter_futuros_pr(datas_validas, codigo)
+        if not df_cache.is_empty():
+            resultados.append(df_cache)
+
+    # Identifica datas que não vieram do cache
+    datas_no_cache: set[dt.date] = set()
+    for df in resultados:
+        datas_no_cache.update(df["TradeDate"].unique().to_list())
+    datas_faltantes = [d for d in datas_validas if d not in datas_no_cache]
+
+    # Fallback individual apenas para datas faltantes
+    for data in datas_faltantes:
+        df = _buscar_por_fonte(data, codigos, full_report)
+        if not df.is_empty():
+            resultados.append(df)
+
+    if not resultados:
+        return pl.DataFrame()
+    return pl.concat(resultados, how="diagonal_relaxed")
+
+
+def _buscar_por_fonte(
+    data: dt.date,
+    codigos: list[str],
+    full_report: bool | None,
+) -> pl.DataFrame:
+    """Seleciona a fonte de dados com base no horário e parâmetros."""
+    if full_report is not None or data != clock.today():
+        return historical.historical(data, codigos, full_report)
+
+    horario = clock.now().time()
+    if horario >= HORA_INICIO_CONSOLIDADO:
+        # Consolidado (SPR → PR) primeiro; intraday como fallback
+        df = historical.historical(data, codigos, full_report)
+        if not df.is_empty():
+            return df
+        return intraday.intraday(codigos)
+
+    if horario >= intraday.HORA_INICIO_INTRADAY:
+        # Intraday primeiro; historical como fallback
+        df = intraday.intraday(codigos)
+        if not df.is_empty():
+            return df
+
+    return historical.historical(data, codigos, full_report)
+
+
+def available_dates(contract_code: str) -> pl.Series:
+    """Retorna as datas de negociação disponíveis no dataset histórico PR.
+
+    Args:
+        contract_code: Código do contrato futuro na B3 (ex.: DI1, DOL).
+
+    Returns:
+        Series ordenada de datas (Date) para as quais há dados de ajuste.
+
+    Examples:
+        >>> from pyield.b3.futures import available_dates
+        >>> available_dates("DI1").head(3)
+        shape: (3,)
+        Series: 'TradeDate' [date]
+        [
+            2018-01-02
+            2018-01-03
+            2018-01-04
+        ]
+    """
+    return historical.listar_datas_disponiveis(contract_code)
+
+
+__all__ = ["available_dates", "futures"]

{pyield-0.44.4 → pyield-0.44.5}/pyield/b3/futures/historical.py

@@ -17,15 +17,16 @@ CONTRATOS_TAXA = {"DI1", "DAP", "DDI", "FRC", "FRO"}
 def historical(
     data: dt.date,
     codigo_contrato: str | list[str],
-    full_report: bool = False,
+    full_report: bool | None = None,
 ) -> pl.DataFrame:
     """Busca histórico de futuros priorizando o dataset PR cacheado.
 
     Args:
         data: Data de negociação.
         codigo_contrato: Código(s) do contrato futuro na B3.
-        full_report: Se False (padrão), usa o simplified price report
-            (SPR, ~2 KB). Se True, usa o price report completo (PR, ~2 MB).
+        full_report: Se None (padrão), tenta SPR primeiro e PR como fallback.
+            Se False, usa o simplified price report (SPR, ~2 KB).
+            Se True, usa o price report completo (PR, ~2 MB).
 
     Returns:
         DataFrame Polars com dados históricos de futuros.
@@ -78,7 +79,7 @@ def historical(
     codigos_sem_cache: list[str] = []
 
     for codigo in codigos:
-        df_cache = _carregar_pr_por_data(data, codigo)
+        df_cache = obter_futuros_pr([data], codigo)
         if df_cache.is_empty():
             codigos_sem_cache.append(codigo)
         else:
@@ -86,9 +87,7 @@ def historical(
 
     if codigos_sem_cache:
         for codigo in codigos_sem_cache:
-            df_bruto = fetch_price_report(
-                date=data, contract_code=codigo, full_report=full_report
-            )
+            df_bruto = _buscar_price_report(data, codigo, full_report)
             if df_bruto.is_empty():
                 continue
 
@@ -117,12 +116,7 @@ def historical(
     return df_resultado.sort(*colunas_ordenacao)
 
 
-def _carregar_pr_por_data(data: dt.date, codigo_contrato: str) -> pl.DataFrame:
-    """Busca o histórico de futuros no dataset PR cacheado para a data informada."""
-    return carregar_pr([data], codigo_contrato)
-
-
-def carregar_pr(datas: list[dt.date], codigo_contrato: str) -> pl.DataFrame:
+def obter_futuros_pr(datas: list[dt.date], codigo_contrato: str) -> pl.DataFrame:
     """Carrega histórico de futuros do dataset PR para uma lista de datas."""
     if not datas:
         return pl.DataFrame()
@@ -152,6 +146,22 @@ def listar_datas_disponiveis(codigo_contrato: str) -> pl.Series:
     )
 
 
+def _buscar_price_report(
+    data: dt.date, codigo: str, full_report: bool | None
+) -> pl.DataFrame:
+    """Busca o price report da B3, com fallback SPR→PR quando full_report=None."""
+    if full_report is not None:
+        return fetch_price_report(
+            date=data, contract_code=codigo, full_report=full_report
+        )
+
+    # SPR (leve) primeiro; PR (pesado) como fallback
+    df = fetch_price_report(date=data, contract_code=codigo, full_report=False)
+    if not df.is_empty():
+        return df
+    return fetch_price_report(date=data, contract_code=codigo, full_report=True)
+
+
 def _filtrar_e_renomear(
     df: pl.DataFrame, datas: list[dt.date], codigo_contrato: str
 ) -> pl.DataFrame:

{pyield-0.44.4 → pyield-0.44.5}/pyield/bc/trades_monthly.py

@@ -135,8 +135,8 @@ def _ordenar_selecionar_colunas(df: pl.DataFrame) -> pl.DataFrame:
 
 
 def tpf_monthly_trades(target_date: DateLike, extragroup: bool = False) -> pl.DataFrame:
-    """Consulta negociações mensais no mercado secundário de Títulos Públicos Federais (TPF)
-    registradas no sistema Selic do Banco Central do Brasil (BCB).
+    """Consulta negociações mensais no mercado secundário de TPF
+    registradas no sistema Selic do BCB.
 
     Baixa os dados mensais de negociação do site do BCB para o mês correspondente
     à data fornecida. Os dados são baixados como arquivo ZIP, extraídos e carregados
@@ -183,26 +183,7 @@ def tpf_monthly_trades(target_date: DateLike, extragroup: bool = False) -> pl.Da
 
     Examples:
         >>> from pyield import bc
-        >>> # Busca todas as negociações de jan/2025
-        >>> bc.tpf_monthly_trades("07-01-2025", extragroup=True)
-        shape: (1_019, 19)
-        ┌────────────────┬──────────┬───────────┬──────────────┬───┬─────────┬─────────┬─────────────────┬───────────────────┐
-        │ SettlementDate ┆ BondType ┆ SelicCode ┆ ISIN         ┆ … ┆ AvgRate ┆ MaxRate ┆ BrokerageTrades ┆ BrokerageQuantity │
-        │ ---            ┆ ---      ┆ ---       ┆ ---          ┆   ┆ ---     ┆ ---     ┆ ---             ┆ ---               │
-        │ date           ┆ str      ┆ i64       ┆ str          ┆   ┆ f64     ┆ f64     ┆ i64             ┆ i64               │
-        ╞════════════════╪══════════╪═══════════╪══════════════╪═══╪═════════╪═════════╪═════════════════╪═══════════════════╡
-        │ 2025-01-02     ┆ LFT      ┆ 210100    ┆ BRSTNCLF1RC4 ┆ … ┆ 0.0132  ┆ 0.0906  ┆ 2               ┆ 9581              │
-        │ 2025-01-02     ┆ LFT      ┆ 210100    ┆ BRSTNCLF1RD2 ┆ … ┆ 0.0561  ┆ 0.101   ┆ 11              ┆ 42823             │
-        │ 2025-01-02     ┆ LFT      ┆ 210100    ┆ BRSTNCLF1RE0 ┆ … ┆ 0.0191  ┆ 0.0405  ┆ 19              ┆ 33330             │
-        │ 2025-01-02     ┆ LFT      ┆ 210100    ┆ BRSTNCLF1RF7 ┆ … ┆ 0.0304  ┆ 0.05    ┆ 10              ┆ 14583             │
-        │ 2025-01-02     ┆ LFT      ┆ 210100    ┆ BRSTNCLF1RG5 ┆ … ┆ 0.0697  ┆ 0.0935  ┆ 12              ┆ 51776             │
-        │ …              ┆ …        ┆ …         ┆ …            ┆ … ┆ …       ┆ …       ┆ …               ┆ …                 │
-        │ 2025-01-31     ┆ NTN-F    ┆ 950199    ┆ BRSTNCNTF1P8 ┆ … ┆ null    ┆ null    ┆ 0               ┆ 0                 │
-        │ 2025-01-31     ┆ NTN-F    ┆ 950199    ┆ BRSTNCNTF1Q6 ┆ … ┆ null    ┆ null    ┆ 0               ┆ 0                 │
-        │ 2025-01-31     ┆ NTN-F    ┆ 950199    ┆ BRSTNCNTF204 ┆ … ┆ null    ┆ null    ┆ 12              ┆ 570000            │
-        │ 2025-01-31     ┆ NTN-F    ┆ 950199    ┆ BRSTNCNTF212 ┆ … ┆ null    ┆ null    ┆ 0               ┆ 0                 │
-        │ 2025-01-31     ┆ NTN-F    ┆ 950199    ┆ BRSTNCNTF238 ┆ … ┆ null    ┆ null    ┆ 4               ┆ 115000            │
-        └────────────────┴──────────┴───────────┴──────────────┴───┴─────────┴─────────┴─────────────────┴───────────────────┘
+        >>> df = bc.tpf_monthly_trades("07-01-2025", extragroup=True)
 
     """
     if any_is_empty(target_date):

{pyield-0.44.4 → pyield-0.44.5}/pyield/bday/core.py

@@ -17,6 +17,14 @@ FERIADOS_NOVOS = feriados_br.obter_feriados(opcao_feriado="new")
 DATA_TRANSICAO = BrHolidays.DATA_TRANSICAO
 
 
+def _expressao_feriados(expr_data: pl.Expr) -> pl.Expr:
+    return (
+        pl.when(expr_data < DATA_TRANSICAO)
+        .then(pl.lit(FERIADOS_ANTIGOS))
+        .otherwise(pl.lit(FERIADOS_NOVOS))
+    )
+
+
 def count_expr(start: pl.Expr | str | dt.date, end: pl.Expr | str | dt.date) -> pl.Expr:
     """Cria uma expressão Polars para contar dias úteis (com suporte a LazyFrame).
 
@@ -69,20 +77,11 @@ def count_expr(start: pl.Expr | str | dt.date, end: pl.Expr | str | dt.date) ->
     else:
         end_date = cv.converter_datas_expr(end)
 
-    return (
-        pl.when(start_date < DATA_TRANSICAO)
-        .then(
-            pl.business_day_count(
-                start=start_date, end=end_date, holidays=FERIADOS_ANTIGOS
-            )
-        )
-        .otherwise(
-            pl.business_day_count(
-                start=start_date, end=end_date, holidays=FERIADOS_NOVOS
-            )
-        )
-        .cast(pl.Int64)
-    )
+    return pl.business_day_count(
+        start=start_date,
+        end=end_date,
+        holidays=_expressao_feriados(start_date),
+    ).cast(pl.Int64)
 
 
 @overload
@@ -265,12 +264,10 @@ def offset_expr(
 
     expr_date = cv.converter_datas_expr(expr)
 
-    return (
-        pl.when(expr_date < DATA_TRANSICAO)
-        .then(expr_date.dt.add_business_days(n=n, roll=roll, holidays=FERIADOS_ANTIGOS))
-        .otherwise(
-            expr_date.dt.add_business_days(n=n, roll=roll, holidays=FERIADOS_NOVOS)
-        )
+    return expr_date.dt.add_business_days(
+        n=n,
+        roll=roll,
+        holidays=_expressao_feriados(expr_date),
     )
 
 
@@ -573,11 +570,7 @@ def is_business_day_expr(expr: pl.Expr | str) -> pl.Expr:
     """
     expr_date = cv.converter_datas_expr(expr)
 
-    return (
-        pl.when(expr_date < DATA_TRANSICAO)
-        .then(expr_date.dt.is_business_day(holidays=FERIADOS_ANTIGOS))
-        .otherwise(expr_date.dt.is_business_day(holidays=FERIADOS_NOVOS))
-    )
+    return expr_date.dt.is_business_day(holidays=_expressao_feriados(expr_date))
 
 
 @overload
@@ -617,7 +610,7 @@ def is_business_day(dates: None | DateLike | ArrayLike) -> None | bool | pl.Seri
     regime de feriados.
 
     Args:
-        dates: Data única ou coleção (list/tuple/ndarray/Polars/Pandas Series).
+        dates: Data única ou coleção (list/tuple/Polars Series).
             Pode incluir nulos que propagam. Entrada escalar nula retorna ``None``.
 
     Returns:

{pyield-0.44.4 → pyield-0.44.5}/pyproject.toml

@@ -15,7 +15,7 @@ classifiers = [
 ]
 dependencies = [
     "cachetools>=5.0.0",
-    "polars>=1.33.0",
+    "polars>=1.39.0",
     "lxml>=6.0.0",
     "python-dateutil>=2.8.0",
     "requests>=2.31.0",
@@ -32,7 +32,6 @@ Source = "https://github.com/crdcj/PYield"
 
 [dependency-groups]
 dev = [    
-    "pandas[pyarrow]",
     "python-dotenv[cli]>=1.0.0",
     "ipykernel>=6.20.0",
     "pytest>=8.0.0",
@@ -41,8 +40,6 @@ dev = [
     "mkdocs>=1.6.0",
     "mkdocs-material>=9.0.0",
     "mkdocstrings[python]>=0.24.0",
-    "mkdocs-autorefs>=1.0.0",
-    "mkdocs-git-revision-date-localized-plugin>=1.2.0",
     "types-requests>=2.31.0",
     "lxml-stubs>=0.5.0",
 ]

pyield-0.44.4/pyield/__about__.py

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

pyield-0.44.4/pyield/b3/futures/__init__.py

@@ -1,92 +0,0 @@
-import logging
-
-import polars as pl
-
-import pyield._internal.converters as cv
-from pyield import clock
-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
-
-logger = logging.getLogger(__name__)
-
-
-def futures(
-    date: DateLike,
-    contract_code: str | list[str],
-    full_report: bool | None = None,
-) -> pl.DataFrame:
-    """Busca dados de um contrato futuro da B3 para a data de referência.
-
-    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: Controla a fonte de dados quando o dado não está no cache.
-            Se None (padrão), prioriza dados intraday (para data de hoje) e
-            usa SPR como fallback — ideal para uso interativo.
-            Se False, usa o simplified price report (SPR, ~2 KB).
-            Se True, usa apenas o price report completo (PR, ~2 MB) —
-            indicado para processos batch noturnos.
-
-    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")
-        >>> df = futures("31-05-2024", "DAP")
-
-        Véspera de Natal e Ano Novo não têm pregão:
-
-        >>> futures("24-12-2024", "DI1").is_empty()
-        True
-        >>> futures("31-12-2024", "DI1").is_empty()
-        True
-
-        Data futura e fim de semana retornam DataFrame vazio:
-
-        >>> import datetime as dt
-        >>> amanha = dt.date.today() + dt.timedelta(days=1)
-        >>> futures(amanha, "DI1").is_empty()
-        True
-        >>> futures("04-01-2025", "DI1").is_empty()  # sábado
-        True
-
-    """
-    if any_is_empty(date, contract_code):
-        return pl.DataFrame()
-
-    codigos_contrato = normalizar_codigos_contrato(contract_code)
-    if not codigos_contrato:
-        return pl.DataFrame()
-
-    data_negociacao = cv.converter_datas(date)
-    if not data_negociacao_valida(data_negociacao):
-        return pl.DataFrame()
-
-    # None: tenta intraday primeiro (só hoje + horário ok)
-    if full_report is None:
-        eh_hoje = intraday.data_intraday_valida(data_negociacao)
-        if eh_hoje:
-            horario = clock.now().time()
-            if horario >= intraday.HORA_INICIO_INTRADAY:
-                df = intraday.intraday(codigos_contrato)
-                if not df.is_empty():
-                    return df
-        full_report = False
-
-    return historical.historical(data_negociacao, codigos_contrato, full_report)
-
-
-__all__ = ["futures"]