pyield 0.46.8__tar.gz → 0.47.1__tar.gz

{pyield-0.46.8 → pyield-0.47.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyield
-Version: 0.46.8
+Version: 0.47.1
 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.47.1/pyield/__about__.py

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

{pyield-0.46.8 → pyield-0.47.1}/pyield/__init__.py

@@ -11,32 +11,31 @@ from pyield.selic.cpm import data as copom_options
 from pyield.tn import lft, ltn, ntnb, ntnb1, ntnbprinc, ntnc, ntnf, pre
 
 __all__ = [
+    "Interpolator",
     "__version__",
     "anbima",
-    "bc",
     "b3",
-    "ipca",
-    "tn",
+    "bc",
     "bday",
+    "copom_options",
     "di1",
-    "forwards",
     "forward",
+    "forwards",
     "futures",
-    "copom_options",
-    "Interpolator",
-    "today",
-    "now",
     "lft",
     "ltn",
+    "now",
     "ntnb",
-    "ntnbprinc",
     "ntnb1",
+    "ntnbprinc",
     "ntnc",
     "ntnf",
+    "ipca",
     "pre",
     "rmd",
-    "bday",
     "selic",
+    "tn",
+    "today",
 ]
 
 # Configura o logger do pacote principal com um NullHandler

{pyield-0.46.8 → pyield-0.47.1}/pyield/_internal/data_cache.py

@@ -1,5 +1,4 @@
 import functools
-import io
 import logging
 from enum import Enum
 from typing import Literal
@@ -55,11 +54,8 @@ def _carregar_arquivo_github(url_arquivo: str) -> pl.DataFrame:
     # Garante que a requisição foi sucesso (200 OK), senão levanta erro
     response.raise_for_status()
 
-    # 2. Transforma os bytes em um objeto de arquivo em memória
-    file_buffer = io.BytesIO(response.content)
-
-    # 3. O Polars lê o buffer como se fosse um arquivo local
-    return pl.read_parquet(file_buffer)
+    # 2. O Polars lê o buffer como se fosse um arquivo local
+    return pl.read_parquet(response.content)
 
 
 @functools.lru_cache(maxsize=8)

pyield-0.47.1/pyield/b3/__init__.py

@@ -0,0 +1,27 @@
+from pyield.b3 import di1
+from pyield.b3.derivatives_intraday import derivatives_intraday_fetch
+from pyield.b3.di_over import di_over
+from pyield.b3.futures import (
+    futures,
+    futures_available_dates,
+    futures_enrich,
+    futures_intraday,
+)
+from pyield.b3.price_report import (
+    price_report_extract,
+    price_report_fetch,
+    price_report_read,
+)
+
+__all__ = [
+    "di_over",
+    "di1",
+    "futures",
+    "futures_available_dates",
+    "futures_enrich",
+    "futures_intraday",
+    "derivatives_intraday_fetch",
+    "price_report_extract",
+    "price_report_fetch",
+    "price_report_read",
+]

pyield-0.46.8/pyield/b3/intraday_derivatives.py → pyield-0.47.1/pyield/b3/derivatives_intraday.py

@@ -111,7 +111,7 @@ def _processar_colunas_intraday(df: pl.DataFrame) -> pl.DataFrame:
     )
 
 
-def fetch_intraday_derivatives(contract_code: str) -> pl.DataFrame:
+def derivatives_intraday_fetch(contract_code: str) -> pl.DataFrame:
     """Busca cotações intraday brutas de derivativos da B3.
 
     Faz a chamada ao endpoint ``DerivativeQuotation`` e devolve um DataFrame
@@ -160,11 +160,9 @@ def fetch_intraday_derivatives(contract_code: str) -> pl.DataFrame:
     if not dados_json:
         return pl.DataFrame()
 
-    return (
-        _converter_json_intraday(dados_json)
-        .pipe(_processar_colunas_intraday)
-        .with_columns(
-            atualizado_as=clock.now() - dt.timedelta(minutes=15),
-        )
-        .sort("codigo_negociacao")
+    df = _converter_json_intraday(dados_json)
+    df = _processar_colunas_intraday(df)
+    df = df.with_columns(
+        atualizado_as=clock.now() - dt.timedelta(minutes=15),
     )
+    return df.sort("codigo_negociacao")

{pyield-0.46.8 → pyield-0.47.1}/pyield/b3/di1.py

@@ -4,7 +4,7 @@ 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 available_dates as _listar_datas
+from pyield.b3.futures import futures_available_dates as _listar_datas
 
 
 def data(
@@ -62,7 +62,7 @@ def data(
     else:
         datas_lista = [datas_convertidas]
 
-    df = b3.futures(date=datas_lista, contract_code="DI1", full_report=False)
+    df = b3.futures(date=datas_lista, contract_code="DI1")
     if df.is_empty():
         return df
 
@@ -195,7 +195,7 @@ def interpolate_rates(
 
     # Carrega dataset de taxas DI usando datas já convertidas do df_entrada
     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)
+    df_ref = b3.futures(date=datas_unicas, contract_code="DI1")
     # Retorna Series vazia se nenhuma taxa for encontrada
     if df_ref.is_empty():
         return pl.Series(dtype=pl.Float64)

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

@@ -0,0 +1,153 @@
+import polars as pl
+
+import pyield._internal.converters as cv
+from pyield._internal.types import ArrayLike, DateLike, any_is_empty
+from pyield.b3._validar_pregao import data_negociacao_valida
+from pyield.b3.futures import historical, intraday
+
+
+def futures_enrich(
+    df: pl.DataFrame,
+    contract_code: str,
+) -> pl.DataFrame:
+    """Enriquece DataFrame bruto do Price Report (PR) da B3.
+
+    Aceita um DataFrame com colunas no schema original da B3
+    (ex.: ``TradDt``, ``TckrSymb``) ou já renomeadas para o padrão
+    PYield. Adiciona data de vencimento, dias úteis/corridos e
+    colunas derivadas (dv01, taxa_forward) conforme o contrato.
+
+    Args:
+        df: DataFrame com dados do PR da B3.
+        contract_code: Código do contrato futuro
+            (ex.: "DI1", "DOL").
+
+    Returns:
+        DataFrame Polars enriquecido e ordenado.
+    """
+    return historical.enrich(df, contract_code)
+
+
+def futures(
+    date: DateLike | ArrayLike,
+    contract_code: str,
+) -> pl.DataFrame:
+    """Busca dados de um contrato futuro da B3 para a data de referência.
+
+    Dados obtidos do dataset PR cacheado no GitHub (disponível desde 2018).
+    Para dados do pregão corrente, use ``futures_intraday``.
+
+    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. Contratos
+            disponíveis no cache histórico:
+            - Juros: DI1, DDI, FRC, FRO, DAP
+            - Moedas: DOL, WDO
+            - Índices: IND, WIN
+
+    Returns:
+        DataFrame Polars com os dados do contrato informado.
+
+    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["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:
+
+        >>> 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()
+
+    dados_convertidos = cv.converter_datas(date)
+    if isinstance(dados_convertidos, pl.Series):
+        datas_validas = []
+        for d in dados_convertidos:
+            if d is not None and data_negociacao_valida(d):
+                datas_validas.append(d)
+        return historical._buscar_do_cache(datas_validas, contract_code)
+
+    if not data_negociacao_valida(dados_convertidos):
+        return pl.DataFrame()
+
+    return historical.historical(dados_convertidos, contract_code)
+
+
+def futures_intraday(
+    contract_code: str,
+) -> pl.DataFrame:
+    """Busca dados intraday de contratos futuros da B3.
+
+    Retorna os dados mais recentes do pregão corrente, com atraso
+    aproximado de 15 minutos. Para dados históricos consolidados,
+    use ``futures``.
+
+    Args:
+        contract_code: Código do contrato futuro na B3
+            (ex.: 'DI1', 'DAP', 'DOL').
+
+    Returns:
+        DataFrame Polars com dados intraday. Retorna DataFrame vazio
+        fora do horário de pregão.
+
+    Notes:
+        As colunas com prefixo ``preco_`` aparecem para contratos cotados
+        por preço (ex.: DOL, IND). As com prefixo ``taxa_`` aparecem para
+        contratos cotados por taxa (ex.: DI1, DAP, DDI, FRC, FRO).
+    """
+    if not contract_code:
+        return pl.DataFrame()
+
+    return intraday.intraday(contract_code)
+
+
+def futures_available_dates(contract_code: str) -> pl.Series:
+    """Retorna as datas de negociação disponíveis no dataset cacheado.
+
+    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 futures_available_dates
+        >>> futures_available_dates("DI1").head(3)
+        shape: (3,)
+        Series: 'data_referencia' [date]
+        [
+            2018-01-02
+            2018-01-03
+            2018-01-04
+        ]
+    """
+    return historical.listar_datas_disponiveis(contract_code)
+
+
+__all__ = [
+    "futures",
+    "futures_available_dates",
+    "futures_intraday",
+]

{pyield-0.46.8 → pyield-0.47.1}/pyield/b3/futures/common.py

@@ -2,6 +2,10 @@ import polars as pl
 
 from pyield import bday
 
+# Lista de contratos que negociam por taxa (juros/cupom).
+# Nestes contratos, as colunas OHLC são taxas e precisam ser divididas por 100.
+CONTRATOS_TAXA = {"DI1", "DAP", "DDI", "FRC", "FRO"}
+
 _MAPA_MESES: dict[str, int] = {
     "F": 1,
     "G": 2,