PYield 0.43.8__tar.gz → 0.44.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyield
-Version: 0.43.8
+Version: 0.44.0
 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

pyield-0.44.0/pyield/__about__.py

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

{pyield-0.43.8 → pyield-0.44.0}/pyield/__init__.py

@@ -7,6 +7,7 @@ from pyield.clock import now, today
 from pyield.fwd import forward, forwards
 from pyield.interpolator import Interpolator
 from pyield.rmd import rmd
+from pyield.selic.cpm import data as copom_options
 from pyield.tn import lft, ltn, ntnb, ntnb1, ntnbprinc, ntnc, ntnf, pre
 
 __all__ = [
@@ -21,6 +22,7 @@ __all__ = [
     "forwards",
     "forward",
     "futures",
+    "copom_options",
     "Interpolator",
     "today",
     "now",

{pyield-0.43.8 → pyield-0.44.0}/pyield/_internal/data_cache.py

@@ -16,8 +16,8 @@ registro = logging.getLogger(__name__)
 
 # Estrutura interna única — usuário não vê isso
 class _Dataset(Enum):
-    DI1 = ("b3_di.parquet", "TradeDate", "Futuro de DI (B3)")
     TPF = ("anbima_tpf.parquet", "ReferenceDate", "TPF (ANBIMA)")
+    PR = ("b3_price_report.parquet", "TradeDate", "Price Report (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["di1", "tpf"]
+type IdDataset = Literal["tpf", "pr"]
 
 
 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: 'di1', 'tpf'."
+        msg = f"id_dataset inválido: '{id_dataset}'. Valores aceitos: 'tpf', 'pr'."
         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: "di1" ou "tpf"
+        id_dataset: "tpf" ou "pr"
     """
     df = _obter_dataset_com_ttl(id_dataset.lower(), _obter_chave_data_hoje())
     return df.clone()

{pyield-0.43.8 → pyield-0.44.0}/pyield/b3/__init__.py

@@ -1,9 +1,11 @@
 from pyield.b3 import di1
 from pyield.b3.di_over import di_over
 from pyield.b3.futures import futures
+from pyield.b3.intraday_derivatives import fetch_intraday_derivatives
 from pyield.b3.price_report import fetch_price_report, read_price_report
 
 __all__ = [
+    "fetch_intraday_derivatives",
     "di_over",
     "futures",
     "fetch_price_report",

pyield-0.44.0/pyield/b3/_contracts.py

@@ -0,0 +1,56 @@
+from collections.abc import Sequence
+
+import polars as pl
+
+from pyield._internal.types import any_is_empty
+
+
+def normalizar_codigo_contrato(contract_code: str | object) -> str:
+    """Normaliza um código de contrato único para caixa alta.
+
+    Args:
+        contract_code: Código único de contrato.
+
+    Returns:
+        str: Código normalizado em caixa alta ou string vazia se vazio.
+    """
+    if any_is_empty(contract_code):
+        return ""
+
+    codigo = str(contract_code).strip().upper()
+    return codigo
+
+
+def normalizar_codigos_contrato(
+    contract_code: str | Sequence[str] | pl.Series,
+) -> list[str]:
+    """Normaliza códigos de contrato para lista única em caixa alta.
+
+    Remove valores vazios e duplicados, preservando a ordem de entrada.
+
+    Args:
+        contract_code: Código único ou coleção de códigos de contrato.
+
+    Returns:
+        list[str]: Lista normalizada de códigos em caixa alta.
+    """
+    if isinstance(contract_code, str):
+        codigo = normalizar_codigo_contrato(contract_code)
+        return [codigo] if codigo else []
+
+    if isinstance(contract_code, pl.Series):
+        valores = contract_code.to_list()
+    else:
+        valores = list(contract_code)
+
+    codigos_unicos: list[str] = []
+    codigos_vistos: set[str] = set()
+    for valor in valores:
+        codigo = normalizar_codigo_contrato(valor)
+        if not codigo:
+            continue
+        if codigo not in codigos_vistos:
+            codigos_vistos.add(codigo)
+            codigos_unicos.append(codigo)
+
+    return codigos_unicos

pyield-0.44.0/pyield/b3/_validar_pregao.py

@@ -0,0 +1,36 @@
+import datetime as dt
+import logging
+
+from pyield import bday, clock
+
+registro = logging.getLogger(__name__)
+
+
+def data_negociacao_valida(data_negociacao: dt.date) -> bool:
+    """Valida se a data de referência é utilizável para consulta.
+
+    Critérios:
+    - Deve ser um dia útil brasileiro.
+    - Não pode estar no futuro (maior que a data corrente no Brasil).
+
+    Retorna True se válida, False caso contrário (e loga um aviso).
+    """
+    if data_negociacao > clock.today():
+        registro.warning(f"A data informada {data_negociacao} está no futuro.")
+        return False
+    if not bday.is_business_day(data_negociacao):
+        registro.warning(f"A data informada {data_negociacao} não é dia útil.")
+        return False
+
+    # Não tem pregão na véspera de Natal e Ano Novo
+    datas_fechadas_especiais = {  # Datas especiais
+        dt.date(data_negociacao.year, 12, 24),  # Véspera de Natal
+        dt.date(data_negociacao.year, 12, 31),  # Véspera de Ano Novo
+    }
+    if data_negociacao in datas_fechadas_especiais:
+        registro.warning(
+            f"Não há pregão na véspera de Natal e de Ano Novo: {data_negociacao}"
+        )
+        return False
+
+    return True

{pyield-0.43.8 → pyield-0.44.0}/pyield/b3/di1.py

@@ -7,10 +7,16 @@ 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.
 
@@ -20,12 +26,15 @@ def _carregar_com_intraday(datas: list[dt.date]) -> pl.DataFrame:
     Returns:
         DataFrame com dados de DI para as datas solicitadas.
     """
-    # 1. Busca inicial no cache com as datas solicitadas pelo usuário.
-    df_cache = obter_dataset_cacheado("di1").filter(pl.col("TradeDate").is_in(datas))
+    # 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_cache = set(df_cache["TradeDate"].unique())
     datas_faltantes = datas_solicitadas - datas_cache
 
     # 3. Para cada data faltante, tenta buscar dados via API
@@ -48,7 +57,7 @@ def _carregar_com_intraday(datas: list[dt.date]) -> pl.DataFrame:
 
     # 4. Retorna concatenação de todos os DataFrames disponíveis
     if len(dfs_concat) == 0:
-        return pl.DataFrame()  # Retorna DataFrame vazio se nada foi encontrado
+        return pl.DataFrame()
     elif len(dfs_concat) == 1:
         return dfs_concat[0]
     else:
@@ -56,19 +65,19 @@ def _carregar_com_intraday(datas: list[dt.date]) -> pl.DataFrame:
 
 
 def _obter_dados(datas: DateLike | ArrayLike) -> pl.DataFrame:
-    df_datas = (
-        pl.DataFrame({"TradeDate": datas})
-        .with_columns(TradeDate=cv.converter_datas_expr("TradeDate"))
-        .drop_nulls(subset=["TradeDate"])
-        .select(pl.col("TradeDate").unique().sort())
-    )
-
-    if df_datas.is_empty():
+    datas_unicas = cv.converter_datas(datas)
+    if datas_unicas is None:
         return pl.DataFrame()
 
-    lista_datas = df_datas.get_column("TradeDate").to_list()
+    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)
 
-    df = _carregar_com_intraday(lista_datas)
+    if df.is_empty():
+        return pl.DataFrame()
 
     return df.sort("TradeDate", "ExpirationDate")
 
@@ -102,31 +111,20 @@ def data(
     Examples:
         >>> from pyield import di1
         >>> df = di1.data(dates="16-10-2024", month_start=True)
-        >>> df
-        shape: (38, 22)
-        ┌────────────┬────────────────┬──────────────┬───────────┬───┬─────────┬───────────┬────────────────┬─────────────┐
-        │ TradeDate  ┆ ExpirationDate ┆ TickerSymbol ┆ DaysToExp ┆ … ┆ MaxRate ┆ CloseRate ┆ SettlementRate ┆ ForwardRate │
-        │ ---        ┆ ---            ┆ ---          ┆ ---       ┆   ┆ ---     ┆ ---       ┆ ---            ┆ ---         │
-        │ date       ┆ date           ┆ str          ┆ i64       ┆   ┆ f64     ┆ f64       ┆ f64            ┆ f64         │
-        ╞════════════╪════════════════╪══════════════╪═══════════╪═══╪═════════╪═══════════╪════════════════╪═════════════╡
-        │ 2024-10-16 ┆ 2024-11-01     ┆ DI1X24       ┆ 16        ┆ … ┆ 0.10656 ┆ 0.10652   ┆ 0.10653        ┆ 0.10653     │
-        │ 2024-10-16 ┆ 2024-12-01     ┆ DI1Z24       ┆ 47        ┆ … ┆ 0.10914 ┆ 0.10914   ┆ 0.1091         ┆ 0.110726    │
-        │ 2024-10-16 ┆ 2025-01-01     ┆ DI1F25       ┆ 78        ┆ … ┆ 0.11174 ┆ 0.11164   ┆ 0.11164        ┆ 0.1154      │
-        │ 2024-10-16 ┆ 2025-02-01     ┆ DI1G25       ┆ 110       ┆ … ┆ 0.1137  ┆ 0.11365   ┆ 0.11362        ┆ 0.118314    │
-        │ 2024-10-16 ┆ 2025-03-01     ┆ DI1H25       ┆ 140       ┆ … ┆ 0.11595 ┆ 0.11565   ┆ 0.1157         ┆ 0.12343     │
-        │ …          ┆ …              ┆ …            ┆ …         ┆ … ┆ …       ┆ …         ┆ …              ┆ …           │
-        │ 2024-10-16 ┆ 2035-01-01     ┆ DI1F35       ┆ 3730      ┆ … ┆ 0.1267  ┆ 0.1264    ┆ 0.1265         ┆ 0.124455    │
-        │ 2024-10-16 ┆ 2036-01-01     ┆ DI1F36       ┆ 4095      ┆ … ┆ null    ┆ null      ┆ 0.1263         ┆ 0.124249    │
-        │ 2024-10-16 ┆ 2037-01-01     ┆ DI1F37       ┆ 4461      ┆ … ┆ null    ┆ null      ┆ 0.1263         ┆ 0.1263      │
-        │ 2024-10-16 ┆ 2038-01-01     ┆ DI1F38       ┆ 4828      ┆ … ┆ null    ┆ null      ┆ 0.1263         ┆ 0.1263      │
-        │ 2024-10-16 ┆ 2039-01-01     ┆ DI1F39       ┆ 5192      ┆ … ┆ null    ┆ null      ┆ 0.1263         ┆ 0.1263      │
-        └────────────┴────────────────┴──────────────┴───────────┴───┴─────────┴───────────┴────────────────┴─────────────┘
+        >>> {"TradeDate", "TickerSymbol", "ExpirationDate", "SettlementRate"}.issubset(
+        ...     set(df.columns)
+        ... )
+        True
+        >>> df.shape[0] > 0
+        True
 
     """
     if any_is_empty(dates):
         return pl.DataFrame()
 
     df = _obter_dados(datas=dates)
+    if df.is_empty():
+        return df
 
     if pre_filter:
         df_tpf = (
@@ -386,10 +384,10 @@ def interpolate_rate(
 
 
 def available_trade_dates() -> pl.Series:
-    """Retorna todas as datas de negociação disponíveis (completas) no dataset de DI.
+    """Retorna todas as datas de negociação disponíveis para DI1 em futures.
 
-    Obtém valores distintos de 'TradeDate' presentes no cache de dados históricos
-    de futuros de DI, ordenados cronologicamente.
+    Obtém valores distintos de 'TradeDate' para DI1, com base no mesmo
+    dataset PR utilizado por `futures`.
 
     Returns:
         Series ordenada de datas de negociação únicas (dt.date) para as quais
@@ -397,23 +395,16 @@ def available_trade_dates() -> pl.Series:
 
     Examples:
         >>> from pyield import di1
-        >>> # Série de futuros de DI começa em 1995-01-02
+        >>> # Série disponível no dataset PR começa em 2018-01-02
         >>> di1.available_trade_dates().head(5)
         shape: (5,)
         Series: 'available_dates' [date]
         [
-            1995-01-02
-            1995-01-03
-            1995-01-04
-            1995-01-05
-            1995-01-06
+            2018-01-02
+            2018-01-03
+            2018-01-04
+            2018-01-05
+            2018-01-08
         ]
     """
-    datas_disponiveis = (
-        obter_dataset_cacheado("di1")
-        .get_column("TradeDate")
-        .unique()
-        .sort()
-        .alias("available_dates")
-    )
-    return datas_disponiveis
+    return futuros_historico.listar_datas_disponiveis("DI1").alias("available_dates")

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

@@ -0,0 +1,128 @@
+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.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__)
+
+
+def _buscar_intraday_ou_historico(
+    data_negociacao,
+    codigos_contrato: list[str],
+    full_report: bool,
+) -> pl.DataFrame:
+    horario_atual = clock.now().time()
+    if horario_atual < intraday.HORA_INICIO_INTRADAY:
+        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
+
+    dataframes_intraday = [intraday.intraday(codigo) for codigo in codigos_contrato]
+    dataframes_intraday = [df for df in dataframes_intraday if not df.is_empty()]
+    if not dataframes_intraday:
+        return pl.DataFrame()
+    if len(dataframes_intraday) == 1:
+        return dataframes_intraday[0]
+    return pl.concat(dataframes_intraday, how="diagonal_relaxed").sort("TickerSymbol")
+
+
+def futures(
+    date: DateLike,
+    contract_code: OpcoesContrato | str | Sequence[OpcoesContrato | str] | pl.Series,
+    full_report: bool = False,
+) -> 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.
+        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.
+            Relevante apenas quando o dado não está no cache.
+
+    Returns:
+        DataFrame Polars com os dados do contrato informado.
+
+    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:
+
+        >>> 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()
+
+    if intraday.data_intraday_valida(data_negociacao):
+        return _buscar_intraday_ou_historico(
+            data_negociacao=data_negociacao,
+            codigos_contrato=codigos_contrato,
+            full_report=full_report,
+        )
+
+    return historical.historical(data_negociacao, codigos_contrato, full_report)
+
+
+__all__ = ["futures"]

pyield-0.44.0/pyield/b3/futures/common.py

@@ -0,0 +1,72 @@
+import polars as pl
+
+from pyield import bday
+
+_MAPA_MESES: dict[str, int] = {
+    "F": 1,
+    "G": 2,
+    "H": 3,
+    "J": 4,
+    "K": 5,
+    "M": 6,
+    "N": 7,
+    "Q": 8,
+    "U": 9,
+    "V": 10,
+    "X": 11,
+    "Z": 12,
+}
+
+
+def expr_dv01(
+    coluna_dias_uteis: str,
+    coluna_taxa: str,
+    coluna_preco: str,
+) -> pl.Expr:
+    """Retorna a expressão Polars para cálculo de DV01.
+
+    Fórmula:
+    DV01 = (Duration / (1 + taxa)) * preço * 0,0001
+
+    Onde:
+    - Duration = dias_uteis / 252
+    - taxa deve estar em formato decimal (ex.: 0.145)
+    - preço é o PU do contrato.
+    """
+    duracao = pl.col(coluna_dias_uteis) / 252
+    duracao_modificada = duracao / (1 + pl.col(coluna_taxa))
+    return 0.0001 * duracao_modificada * pl.col(coluna_preco)
+
+
+def adicionar_vencimento(
+    df: pl.DataFrame, codigo_contrato: str, coluna_ticker: str
+) -> pl.DataFrame:
+    """
+    Recebe um DataFrame Polars e ADICIONA a coluna 'ExpirationDate'.
+
+    - 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.
+
+    Assume tickers 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)
+            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
+            month=pl.col(coluna_ticker)
+            .str.slice(3, 1)
+            .replace_strict(_MAPA_MESES, default=None, return_dtype=pl.Int8),
+            day=dia_vencimento,
+        ).alias("ExpirationDate")
+    )
+    # Garante que a data de vencimento é um dia útil
+    df = df.with_columns(ExpirationDate=bday.offset_expr("ExpirationDate", 0))
+
+    return df