PYield 0.46.3__tar.gz → 0.46.4__tar.gz

{pyield-0.46.3 → pyield-0.46.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyield
-Version: 0.46.3
+Version: 0.46.4
 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
@@ -71,10 +71,10 @@ yd.bday.offset("29-12-2023", 1)            # -> datetime.date(2024, 1, 2)
 
 # Curva de DI Futuro
 df = yd.futures("31-05-2024", "DI1")
-# Columns: TradeDate, TickerSymbol, ExpirationDate, BDaysToExp, SettlementRate, ...
+# Columns: data_referencia, codigo_negociacao, data_vencimento, dias_uteis, taxa_ajuste, ...
 
 # Interpolação de taxas (flat forward, convenção 252 dias úteis/ano)
-interp = yd.Interpolator("flat_forward", df["BDaysToExp"], df["SettlementRate"])
+interp = yd.Interpolator("flat_forward", df["dias_uteis"], df["taxa_ajuste"])
 interp(45)       # -> 0.04833...
 interp([30, 60]) # -> pl.Series with interpolated rates
 
@@ -200,7 +200,7 @@ ntnb.quotation("31-05-2024", "15-08-2060", 0.061878)  # -> 99.5341
 
 # Spreads de DI (bps=True multiplica por 10.000)
 ntnf.di_spreads("30-05-2025", bps=True)
-# -> DataFrame: BondType, MaturityDate, DISpread
+# -> DataFrame: titulo, data_vencimento, spread_di
 ```
 
 ## Dados de Futuros

{pyield-0.46.3 → pyield-0.46.4}/README.md

@@ -27,10 +27,10 @@ yd.bday.offset("29-12-2023", 1)            # -> datetime.date(2024, 1, 2)
 
 # Curva de DI Futuro
 df = yd.futures("31-05-2024", "DI1")
-# Columns: TradeDate, TickerSymbol, ExpirationDate, BDaysToExp, SettlementRate, ...
+# Columns: data_referencia, codigo_negociacao, data_vencimento, dias_uteis, taxa_ajuste, ...
 
 # Interpolação de taxas (flat forward, convenção 252 dias úteis/ano)
-interp = yd.Interpolator("flat_forward", df["BDaysToExp"], df["SettlementRate"])
+interp = yd.Interpolator("flat_forward", df["dias_uteis"], df["taxa_ajuste"])
 interp(45)       # -> 0.04833...
 interp([30, 60]) # -> pl.Series with interpolated rates
 
@@ -156,7 +156,7 @@ ntnb.quotation("31-05-2024", "15-08-2060", 0.061878)  # -> 99.5341
 
 # Spreads de DI (bps=True multiplica por 10.000)
 ntnf.di_spreads("30-05-2025", bps=True)
-# -> DataFrame: BondType, MaturityDate, DISpread
+# -> DataFrame: titulo, data_vencimento, spread_di
 ```
 
 ## Dados de Futuros

pyield-0.46.4/pyield/__about__.py

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

{pyield-0.46.3 → pyield-0.46.4}/pyield/_internal/data_cache.py

@@ -17,7 +17,7 @@ registro = logging.getLogger(__name__)
 # Estrutura interna única — usuário não vê isso
 class _Dataset(Enum):
     TPF = ("anbima_tpf.parquet", "data_referencia", "TPF (ANBIMA)")
-    PR = ("b3_price_report.parquet", "TradeDate", "Price Report (B3)")
+    FUTURES = ("b3_futures.parquet", "data_referencia", "Futures (B3)")
 
     def __init__(self, nome_arquivo: str, coluna_data: str, descricao: str):
         self.nome_arquivo = nome_arquivo
@@ -25,7 +25,7 @@ class _Dataset(Enum):
         self.descricao = descricao
 
 
-type IdDataset = Literal["tpf", "pr"]
+type IdDataset = Literal["tpf", "futures"]
 
 
 def _obter_chave_data_hoje() -> str:
@@ -37,7 +37,7 @@ def _validar_id_dataset(id_dataset: str) -> _Dataset:
     try:
         return _Dataset[dataset_normalizado.upper()]
     except KeyError as e:
-        msg = f"id_dataset inválido: '{id_dataset}'. Valores aceitos: 'tpf', 'pr'."
+        msg = f"id_dataset inválido: '{id_dataset}'. Valores aceitos: 'tpf', 'futures'."
         raise ValueError(msg) from e
 
 
@@ -81,7 +81,7 @@ def obter_dataset_cacheado(id_dataset: IdDataset) -> pl.DataFrame:
     Obtém um dataset pelo ID. Cache expira diariamente.
 
     Args:
-        id_dataset: "tpf" ou "pr"
+        id_dataset: "tpf" ou "futures"
     """
     df = _obter_dataset_com_ttl(id_dataset.lower(), _obter_chave_data_hoje())
     return df.clone()

{pyield-0.46.3 → pyield-0.46.4}/pyield/b3/_validar_pregao.py

@@ -2,6 +2,10 @@ import datetime as dt
 
 from pyield import bday, clock
 
+# Pregão abre às 9:00, porém os dados intraday têm atraso de 15 minutos.
+# Esperar 1 minuto adicional para garantir que estejam disponíveis (9:16h).
+HORA_INICIO_INTRADAY = dt.time(9, 16)
+
 
 def data_negociacao_valida(data_negociacao: dt.date) -> bool:
     """Valida se a data de referência é utilizável para consulta.
@@ -26,3 +30,15 @@ def data_negociacao_valida(data_negociacao: dt.date) -> bool:
         return False
 
     return True
+
+
+def intraday_disponivel() -> bool:
+    """Verifica se dados intraday estão disponíveis agora.
+
+    Critérios:
+    - Hoje deve ser um dia de pregão válido.
+    - O horário atual deve ser após o início dos dados intraday (9:16h).
+    """
+    if not data_negociacao_valida(clock.today()):
+        return False
+    return clock.now().time() >= HORA_INICIO_INTRADAY

{pyield-0.46.3 → pyield-0.46.4}/pyield/b3/di1.py

@@ -36,12 +36,19 @@ def data(
     Examples:
         >>> from pyield import di1
         >>> df = di1.data(dates="16-10-2024", month_start=True)
-        >>> {"TradeDate", "TickerSymbol", "ExpirationDate", "SettlementRate"}.issubset(
-        ...     set(df.columns)
+        >>> df.head(3).select(
+        ...     "codigo_negociacao", "data_vencimento", "dias_uteis", "taxa_ajuste"
         ... )
-        True
-        >>> df.shape[0] > 0
-        True
+        shape: (3, 4)
+        ┌───────────────────┬─────────────────┬────────────┬─────────────┐
+        │ codigo_negociacao ┆ data_vencimento ┆ dias_uteis ┆ taxa_ajuste │
+        │ ---               ┆ ---             ┆ ---        ┆ ---         │
+        │ str               ┆ date            ┆ i64        ┆ f64         │
+        ╞═══════════════════╪═════════════════╪════════════╪═════════════╡
+        │ DI1X24            ┆ 2024-11-01      ┆ 12         ┆ 0.10653     │
+        │ DI1Z24            ┆ 2024-12-01      ┆ 31         ┆ 0.1091      │
+        │ DI1F25            ┆ 2025-01-01      ┆ 52         ┆ 0.11164     │
+        └───────────────────┴─────────────────┴────────────┴─────────────┘
 
     """
     if any_is_empty(dates):
@@ -65,33 +72,29 @@ def data(
             .filter(pl.col("titulo").is_in(["LTN", "NTN-F"]))
             .unique(subset=["data_vencimento", "data_referencia"])
             .select(
-                TradeDate_tpf=pl.col("data_referencia"),
-                ExpirationDate=bday.offset_expr("data_vencimento", 0),
+                data_ref_tpf=pl.col("data_referencia"),
+                data_vencimento=bday.offset_expr("data_vencimento", 0),
             )
-            .sort("TradeDate_tpf", "ExpirationDate")
+            .sort("data_ref_tpf", "data_vencimento")
         )
 
-        # Ajustar as datas de vencimento para dias úteis, como está no DI1
-        # exp_dates = bday.offset(df_tpf["ExpirationDate"], 0)
-        # df_tpf = df_tpf.with_columns(ExpirationDate=exp_dates)
-
-        # Mapear cada TradeDate do DI para a data TPF mais próxima
+        # Mapear cada data_referencia do DI para a data TPF mais próxima
         df = df.join_asof(
-            df_tpf.select("TradeDate_tpf").unique().sort("TradeDate_tpf"),
-            left_on="TradeDate",
-            right_on="TradeDate_tpf",
+            df_tpf.select("data_ref_tpf").unique().sort("data_ref_tpf"),
+            left_on="data_referencia",
+            right_on="data_ref_tpf",
             strategy="backward",
         )
 
         # Filtrar apenas vencimentos que existem no TPF
-        df = df.join(df_tpf, on=["TradeDate_tpf", "ExpirationDate"], how="inner").drop(
-            "TradeDate_tpf"
+        df = df.join(df_tpf, on=["data_ref_tpf", "data_vencimento"], how="inner").drop(
+            "data_ref_tpf"
         )
 
     if month_start:
-        df = df.with_columns(pl.col("ExpirationDate").dt.truncate("1mo"))
+        df = df.with_columns(pl.col("data_vencimento").dt.truncate("1mo"))
 
-    return df.sort("TradeDate", "ExpirationDate")
+    return df.sort("data_referencia", "data_vencimento")
 
 
 def interpolate_rates(
@@ -145,7 +148,7 @@ def interpolate_rates(
         ...     expirations=["01-01-2027", "25-11-2027", "01-01-2030"],
         ... )
         shape: (3,)
-        Series: 'FlatFwdRate' [f64]
+        Series: 'taxa_interpolada' [f64]
         [
             0.13972
             0.134613
@@ -159,7 +162,7 @@ def interpolate_rates(
         ...     extrapolate=True,
         ... )
         shape: (2,)
-        Series: 'FlatFwdRate' [f64]
+        Series: 'taxa_interpolada' [f64]
         [
             0.13901
             0.13881
@@ -172,7 +175,7 @@ def interpolate_rates(
         ...     extrapolate=False,
         ... )
         shape: (2,)
-        Series: 'FlatFwdRate' [f64]
+        Series: 'taxa_interpolada' [f64]
         [
             0.135763
             null
@@ -182,16 +185,16 @@ def interpolate_rates(
         return pl.Series(dtype=pl.Float64)
 
     df_entrada = pl.DataFrame(
-        data={"TradeDate": dates, "ExpirationDate": expirations}
+        data={"data_referencia": dates, "data_vencimento": expirations}
     ).with_columns(
-        TradeDate=cv.converter_datas_expr("TradeDate"),
-        ExpirationDate=cv.converter_datas_expr("ExpirationDate"),
+        data_referencia=cv.converter_datas_expr("data_referencia"),
+        data_vencimento=cv.converter_datas_expr("data_vencimento"),
     )
     if df_entrada.is_empty():
         return pl.Series(dtype=pl.Float64)
 
     # Carrega dataset de taxas DI usando datas já convertidas do df_entrada
-    datas_unicas = df_entrada["TradeDate"].drop_nulls().unique().sort().to_list()
+    datas_unicas = df_entrada["data_referencia"].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():
@@ -201,22 +204,22 @@ def interpolate_rates(
     # Isso garante que saberemos a ordem exata depois
     df_entrada = df_entrada.with_row_index("_temp_idx")
 
-    # Inicializa FlatFwdRate como None
+    # Inicializa taxa_interpolada como None
     df_entrada = df_entrada.with_columns(
-        BDaysToExp=bday.count_expr("TradeDate", "ExpirationDate"),
-        FlatFwdRate=None,
+        dias_uteis=bday.count_expr("data_referencia", "data_vencimento"),
+        taxa_interpolada=None,
     )
 
     # Lista para armazenar os blocos processados
     blocos_processados = []
 
     # Itera sobre cada data de referência única
-    for data_ref in df_entrada["TradeDate"].unique():
+    for data_ref in df_entrada["data_referencia"].unique():
         # 1. Filtra apenas as linhas desta data (Particionamento)
-        df_parcial = df_entrada.filter(pl.col("TradeDate") == data_ref)
+        df_parcial = df_entrada.filter(pl.col("data_referencia") == data_ref)
 
         # 2. Busca as taxas de referência para esta data
-        df_referencia = df_ref.filter(pl.col("TradeDate") == data_ref)
+        df_referencia = df_ref.filter(pl.col("data_referencia") == data_ref)
 
         # Se não houver dados de curva, adicionamos o bloco como está (com nulos)
         # e continuamos.
@@ -227,17 +230,17 @@ def interpolate_rates(
         # Inicializa o interpolador com taxas e dias úteis conhecidos
         interpolador = interpolator.Interpolator(
             method="flat_forward",
-            known_bdays=df_referencia["BDaysToExp"],
-            known_rates=df_referencia["SettlementRate"],
+            known_bdays=df_referencia["dias_uteis"],
+            known_rates=df_referencia["taxa_ajuste"],
             extrapolate=extrapolate,
         )
 
         # 4. A mágica: map_batches passa a Series inteira para o interpolador
         # O interpolador retorna uma Series, que o Polars alinha perfeitamente
         df_parcial = df_parcial.with_columns(
-            pl.col("BDaysToExp")
+            pl.col("dias_uteis")
             .map_batches(interpolador)  # Passa Series -> Recebe Series
-            .alias("FlatFwdRate")
+            .alias("taxa_interpolada")
         )
 
         blocos_processados.append(df_parcial)
@@ -249,7 +252,7 @@ def interpolate_rates(
     # O sort("_temp_idx") restaura a ordem original dos inputs
     df_saida = pl.concat(blocos_processados).sort("_temp_idx")
 
-    return df_saida["FlatFwdRate"].fill_nan(None)
+    return df_saida["taxa_interpolada"].fill_nan(None)
 
 
 def interpolate_rate(
@@ -315,9 +318,10 @@ def interpolate_rate(
 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 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.
+    Obtém valores distintos de 'data_referencia' 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 (dt.date) para as quais dados de
@@ -328,7 +332,7 @@ def available_dates() -> pl.Series:
         >>> # Série disponível no dataset PR começa em 2018-01-02
         >>> di1.available_dates().head(5)
         shape: (5,)
-        Series: 'TradeDate' [date]
+        Series: 'data_referencia' [date]
         [
             2018-01-02
             2018-01-03

{pyield-0.46.3 → pyield-0.46.4}/pyield/b3/futures/__init__.py

@@ -7,7 +7,7 @@ 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._validar_pregao import HORA_INICIO_INTRADAY, 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.
@@ -58,7 +58,7 @@ def futures(
         Lista de datas:
 
         >>> df = futures(["29-05-2024", "31-05-2024"], "DI1")
-        >>> df["TradeDate"].unique().sort().to_list()
+        >>> df["data_referencia"].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:
@@ -125,7 +125,7 @@ def _buscar_varias_datas(
     # 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_no_cache.update(df["data_referencia"].unique().to_list())
     datas_faltantes = [d for d in datas_validas if d not in datas_no_cache]
 
     # Fallback individual apenas para datas faltantes
@@ -156,7 +156,7 @@ def _buscar_por_fonte(
             return df
         return intraday.intraday(codigos)
 
-    if horario >= intraday.HORA_INICIO_INTRADAY:
+    if horario >= HORA_INICIO_INTRADAY:
         # Intraday primeiro; historical como fallback
         df = intraday.intraday(codigos)
         if not df.is_empty():
@@ -178,7 +178,7 @@ def available_dates(contract_code: str) -> pl.Series:
         >>> from pyield.b3.futures import available_dates
         >>> available_dates("DI1").head(3)
         shape: (3,)
-        Series: 'TradeDate' [date]
+        Series: 'data_referencia' [date]
         [
             2018-01-02
             2018-01-03

{pyield-0.46.3 → pyield-0.46.4}/pyield/b3/futures/common.py

@@ -42,21 +42,21 @@ def adicionar_vencimento(
     df: pl.DataFrame, codigo_contrato: str, coluna_ticker: str
 ) -> pl.DataFrame:
     """
-    Recebe um DataFrame Polars e ADICIONA a coluna 'ExpirationDate'.
+    Recebe um DataFrame Polars e ADICIONA a coluna 'data_vencimento'.
 
     - Pega a coluna 'coluna_ticker'.
     - Extrai o código de vencimento.
     - Converte para a data "bruta", sem ajuste de feriado.
     - Garante que a data de vencimento é um dia útil.
-    - Retorna o DataFrame com a nova coluna ExpirationDate.
+    - Retorna o DataFrame com a nova coluna data_vencimento.
 
-    Assume tickers no formato padrão de futuros da B3 (ex.: DI1F25).
+    Assume códigos de negociação no formato padrão de futuros da B3 (ex.: DI1F25).
     """
     dia_vencimento = 15 if "DAP" in codigo_contrato else 1
     df = df.with_columns(
         pl.date(
             # Ano: posição 4-5 (2 dígitos) -> Int -> Soma 2000
-            # Funciona para tickers padrão de futuros (ex.: DI1F25)
+            # Funciona para códigos de negociação padrão de futuros (ex.: DI1F25)
             year=pl.col(coluna_ticker).str.slice(4, 2).cast(pl.Int32, strict=False)
             + 2000,
             # Mês: posição 3 (1 char = código do mês) -> mapeia para Int
@@ -64,9 +64,9 @@ def adicionar_vencimento(
             .str.slice(3, 1)
             .replace_strict(_MAPA_MESES, default=None, return_dtype=pl.Int8),
             day=dia_vencimento,
-        ).alias("ExpirationDate")
+        ).alias("data_vencimento")
     )
     # Garante que a data de vencimento é um dia útil
-    df = df.with_columns(ExpirationDate=bday.offset_expr("ExpirationDate", 0))
+    df = df.with_columns(data_vencimento=bday.offset_expr("data_vencimento", 0))
 
     return df