PYield 0.46.7__tar.gz → 0.47.0__tar.gz

{pyield-0.46.7 → pyield-0.47.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyield
-Version: 0.46.7
+Version: 0.47.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.47.0/pyield/__about__.py

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

{pyield-0.46.7 → pyield-0.47.0}/pyield/__init__.py

@@ -2,7 +2,7 @@ import logging
 
 from pyield import anbima, b3, bc, bday, ipca, selic, tn
 from pyield.__about__ import __version__
-from pyield.b3 import di1, futures
+from pyield.b3 import di1, futures, futures_intraday
 from pyield.clock import now, today
 from pyield.fwd import forward, forwards
 from pyield.interpolator import Interpolator
@@ -37,6 +37,7 @@ __all__ = [
     "rmd",
     "bday",
     "selic",
+    "futures_intraday",
 ]
 
 # Configura o logger do pacote principal com um NullHandler

{pyield-0.46.7 → pyield-0.47.0}/pyield/b3/__init__.py

@@ -1,6 +1,6 @@
 from pyield.b3 import di1
 from pyield.b3.di_over import di_over
-from pyield.b3.futures import futures
+from pyield.b3.futures import futures, futures_intraday
 from pyield.b3.intraday_derivatives import fetch_intraday_derivatives
 from pyield.b3.price_report import fetch_price_report, read_price_report
 
@@ -8,6 +8,7 @@ __all__ = [
     "fetch_intraday_derivatives",
     "di_over",
     "futures",
+    "futures_intraday",
     "fetch_price_report",
     "read_price_report",
     "di1",

{pyield-0.46.7 → pyield-0.47.0}/pyield/b3/di1.py

@@ -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.46.7 → pyield-0.47.0}/pyield/b3/futures/__init__.py

@@ -1,56 +1,37 @@
 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 HORA_INICIO_INTRADAY, data_negociacao_valida
+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.
 
+    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 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.
+        contract_code: Código do contrato futuro na B3 ou coleção de
+            códigos. 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.
 
-    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")
@@ -88,26 +69,21 @@ def futures(
     if is_collection(date):
         # date é ArrayLike neste branch
         datas: ArrayLike = date  # type: ignore[assignment]
-        return _buscar_varias_datas(datas, codigos_contrato, full_report)
+        return _buscar_varias_datas(datas, codigos_contrato)
 
     # 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)
+    return historical.historical(data_negociacao, codigos_contrato)
 
 
 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.
-    """
+    """Busca dados para múltiplas datas do dataset PR cacheado."""
     serie_datas = cv.converter_datas(datas)
     datas_validas = [
         d for d in serie_datas if d is not None and data_negociacao_valida(d)
@@ -115,54 +91,65 @@ def _buscar_varias_datas(
     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["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
-    for data in datas_faltantes:
-        df = _buscar_por_fonte(data, codigos, full_report)
-        if not df.is_empty():
-            resultados.append(df)
+    resultados = [
+        df
+        for codigo in codigos
+        if not (df := historical._obter_futuros_pr(datas_validas, codigo)).is_empty()
+    ]
 
     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,
+def futures_intraday(
+    contract_code: str | list[str],
 ) -> 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)
+    """Busca dados intraday de contratos futuros da B3.
 
-    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)
+    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 ou lista de
+            códigos (ex.: 'DI1', ['DI1', 'DAP']).
 
-    if horario >= HORA_INICIO_INTRADAY:
-        # Intraday primeiro; historical como fallback
-        df = intraday.intraday(codigos)
-        if not df.is_empty():
-            return df
+    Returns:
+        DataFrame Polars com dados intraday. Retorna DataFrame vazio
+        fora do horário de pregão.
+
+    Output Columns:
+        * data_referencia (Date): data de negociação.
+        * atualizado_as (Datetime): horário a que o dado se refere
+          (com atraso de ~15 min).
+        * codigo_negociacao (String): código de negociação na B3.
+        * data_vencimento (Date): data de vencimento do contrato.
+        * dias_uteis (Int64): dias úteis até o vencimento.
+        * dias_corridos (Int64): dias corridos até o vencimento.
+        * contratos_abertos (Int64): contratos em aberto.
+        * numero_negocios (Int64): número de negócios.
+        * volume_negociado (Int64): quantidade de contratos negociados.
+        * volume_financeiro (Float64): volume financeiro bruto.
+        * dv01 (Float64): variação no preço para 1bp (apenas DI1).
+        * preco_ultimo (Float64): último preço (apenas DI1/DAP).
+        * taxa_ajuste_anterior (Float64): taxa de ajuste do dia anterior.
+        * taxa_limite_minimo (Float64): limite mínimo de variação.
+        * taxa_limite_maximo (Float64): limite máximo de variação.
+        * taxa_abertura (Float64): taxa de abertura.
+        * taxa_minima (Float64): taxa mínima negociada.
+        * taxa_media (Float64): taxa média negociada.
+        * taxa_maxima (Float64): taxa máxima negociada.
+        * taxa_oferta_compra (Float64): melhor oferta de compra.
+        * taxa_oferta_venda (Float64): melhor oferta de venda.
+        * taxa_ultima (Float64): última taxa negociada.
+        * taxa_forward (Float64): taxa a termo (apenas DI1/DAP).
+    """
+    codigos = normalizar_codigos_contrato(contract_code)
+    if not codigos:
+        return pl.DataFrame()
 
-    return historical.historical(data, codigos, full_report)
+    return intraday.intraday(codigos)
 
 
 def available_dates(contract_code: str) -> pl.Series:
@@ -188,4 +175,4 @@ def available_dates(contract_code: str) -> pl.Series:
     return historical.listar_datas_disponiveis(contract_code)
 
 
-__all__ = ["available_dates", "futures"]
+__all__ = ["available_dates", "futures", "futures_intraday"]

{pyield-0.46.7 → pyield-0.47.0}/pyield/b3/futures/historical.py

@@ -6,7 +6,6 @@ from pyield import bday
 from pyield._internal.data_cache import obter_dataset_cacheado
 from pyield.b3._contracts import normalizar_codigos_contrato
 from pyield.b3.futures.common import adicionar_vencimento, expr_dv01
-from pyield.b3.price_report import fetch_price_report
 from pyield.fwd import forwards
 
 # Lista de contratos que negociam por taxa (juros/cupom).
@@ -63,16 +62,12 @@ def _obter_pr_normalizado() -> pl.DataFrame:
 def historical(
     data: dt.date,
     codigo_contrato: str | list[str],
-    full_report: bool | None = None,
 ) -> pl.DataFrame:
-    """Busca histórico de futuros priorizando o dataset PR cacheado.
+    """Busca histórico de futuros no dataset PR cacheado.
 
     Args:
         data: Data de negociação.
         codigo_contrato: Código(s) do contrato futuro na B3.
-        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.
@@ -115,6 +110,9 @@ def historical(
         * taxa_forward (Float64): taxa a termo (apenas DI1/DAP).
 
     Notes:
+        Usa exclusivamente o dataset PR cacheado no GitHub. Contratos
+        disponíveis: DI1, DDI, FRC, FRO, DAP, DOL, WDO, IND, WIN.
+
         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). Nem todas as colunas
@@ -131,28 +129,11 @@ def historical(
     if not codigos:
         return pl.DataFrame()
 
-    dataframes: list[pl.DataFrame] = []
-    codigos_sem_cache: list[str] = []
-
-    for codigo in codigos:
-        df_cache = _obter_futuros_pr([data], codigo)
-        if df_cache.is_empty():
-            codigos_sem_cache.append(codigo)
-        else:
-            dataframes.append(df_cache)
-
-    if codigos_sem_cache:
-        for codigo in codigos_sem_cache:
-            df_bruto = _buscar_price_report(data, codigo, full_report)
-            if df_bruto.is_empty():
-                continue
-
-            df_bruto = adicionar_vencimento(df_bruto, codigo, "codigo_negociacao")
-            df = _enriquecer_dados(df_bruto, codigo)
-            df_saida = _selecionar_colunas_saida(df)
-            if "data_vencimento" in df_saida.columns:
-                df_saida = df_saida.sort("data_vencimento")
-            dataframes.append(df_saida)
+    dataframes = [
+        df
+        for codigo in codigos
+        if not (df := _obter_futuros_pr([data], codigo)).is_empty()
+    ]
 
     if not dataframes:
         return pl.DataFrame()
@@ -202,31 +183,6 @@ 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 é True, usa apenas o PR (completo).
-    Nos demais casos (None ou False), tenta o SPR (leve) primeiro
-    e faz fallback para o PR se o SPR estiver vazio.
-    """
-    if full_report is True:
-        return _normalizar_colunas_pr(
-            fetch_price_report(date=data, contract_code=codigo, full_report=True)
-        )
-
-    # SPR (leve) primeiro; PR (pesado) como fallback
-    df = _normalizar_colunas_pr(
-        fetch_price_report(date=data, contract_code=codigo, full_report=False)
-    )
-    if not df.is_empty():
-        return df
-    return _normalizar_colunas_pr(
-        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.46.7 → pyield-0.47.0}/pyield/b3/price_report.py

@@ -102,30 +102,18 @@ def _baixar_zip_url(data: dt.date, relatorio_completo: bool) -> bytes:
 
 
 def _extrair_xml_de_zip(conteudo_zip: bytes) -> bytes:
-    """Extrai o XML de um ZIP, suportando ZIP aninhado (ZIP→ZIP→XML) ou simples (ZIP→XML)."""
+    """Extrai o XML do ZIP aninhado da B3 (ZIP externo → ZIP interno → XML)."""
     with zipfile.ZipFile(io.BytesIO(conteudo_zip), "r") as zip_externo:
-        nomes_externos = zip_externo.namelist()
-        if not nomes_externos:
+        nomes = zip_externo.namelist()
+        if not nomes:
             raise ValueError("ZIP externo está vazio")
 
-        # Caso 1: ZIP contém XML diretamente
-        nomes_xml = sorted(n for n in nomes_externos if n.endswith(".xml"))
-        if nomes_xml:
-            return zip_externo.read(nomes_xml[-1])
-
-        # Caso 2: ZIP aninhado — busca o primeiro ZIP interno válido
-        for nome in nomes_externos:
-            conteudo_interno = zip_externo.read(nome)
-            if conteudo_interno[:4] != b"PK\x03\x04":
-                continue
-            with zipfile.ZipFile(io.BytesIO(conteudo_interno), "r") as zip_interno:
-                nomes_xml = sorted(
-                    n for n in zip_interno.namelist() if n.endswith(".xml")
-                )
-                if nomes_xml:
-                    return zip_interno.read(nomes_xml[-1])
-
-    raise ValueError("Nenhum XML encontrado no ZIP")
+        conteudo_interno = zip_externo.read(nomes[0])
+        with zipfile.ZipFile(io.BytesIO(conteudo_interno), "r") as zip_interno:
+            nomes_xml = sorted(n for n in zip_interno.namelist() if n.endswith(".xml"))
+            if not nomes_xml:
+                raise ValueError("Nenhum XML encontrado no ZIP interno")
+            return zip_interno.read(nomes_xml[-1])
 
 
 def _ticker_valido_para_contrato(ticker: str, codigo_contrato: str) -> bool:

pyield-0.46.7/pyield/__about__.py

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