PYield 0.46.6__tar.gz → 0.46.8__tar.gz

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

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

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

{pyield-0.46.6 → pyield-0.46.8}/pyield/anbima/__init__.py

@@ -1,4 +1,3 @@
-from pyield.anbima.difusao import tpf_difusao
 from pyield.anbima.ettj_intraday import intraday_ettj
 from pyield.anbima.ettj_last import last_ettj
 from pyield.anbima.ima import last_ima
@@ -13,5 +12,4 @@ __all__ = [
     "fetch_tpf",
     "last_ettj",
     "intraday_ettj",
-    "tpf_difusao",
 ]

{pyield-0.46.6 → pyield-0.46.8}/pyield/b3/futures/__init__.py

@@ -19,7 +19,7 @@ logger = logging.getLogger(__name__)
 def futures(
     date: DateLike | ArrayLike,
     contract_code: str | list[str],
-    full_report: bool | None = None,
+    full_report: bool = False,
 ) -> pl.DataFrame:
     """Busca dados de um contrato futuro da B3 para a data de referência.
 
@@ -28,29 +28,25 @@ def futures(
             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) —
+        contract_code: Código do contrato futuro na B3 ou coleção de
+            códigos. Aceita qualquer código de contrato futuro listado
+            na B3. Contratos com histórico pré-cacheado (desde 2018)
+            são retornados instantaneamente:
+            - Juros: DI1, DDI, FRC, FRO, DAP
+            - Moedas: DOL, WDO
+            - Índices: IND, WIN
+            Para os demais contratos (OC1, IAP, EUR, GBR, JAP, CNY,
+            ISP, WSP, BGI, CCM, ICF, SJC, SOY, ETH, GLD, etc.),
+            os dados são baixados diretamente da B3 a cada chamada.
+        full_report: Controla a fonte de dados quando o dado não está
+            no cache. Se False (padrão), tenta o simplified price
+            report (SPR, ~2 KB) primeiro e faz fallback para o price
+            report completo (PR, ~2 MB). Se True, usa apenas o PR —
             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")
@@ -101,7 +97,7 @@ def futures(
 def _buscar_varias_datas(
     datas: ArrayLike,
     codigos: list[str],
-    full_report: bool | None,
+    full_report: bool,
 ) -> pl.DataFrame:
     """Busca dados para múltiplas datas e concatena os resultados.
 
@@ -142,27 +138,25 @@ def _buscar_varias_datas(
 def _buscar_por_fonte(
     data: dt.date,
     codigos: list[str],
-    full_report: bool | None,
+    full_report: bool,
 ) -> 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():
+    """Seleciona a fonte de dados com base na data e horário.
+
+    Para datas passadas, usa dados consolidados (historical).
+    Para a data de hoje, depende do horário:
+    - Antes das 09:16: sem dados disponíveis (DataFrame vazio).
+    - Entre 09:16 e 19:00: dados intraday.
+    - A partir das 19:00: dados consolidados (historical).
+    """
+    if 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)
-
+        return historical.historical(data, codigos, full_report)
     if horario >= 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)
+        return intraday.intraday(codigos)
+    return pl.DataFrame()
 
 
 def available_dates(contract_code: str) -> pl.Series:

{pyield-0.46.6 → pyield-0.46.8}/pyield/b3/futures/historical.py

@@ -63,16 +63,15 @@ def _obter_pr_normalizado() -> pl.DataFrame:
 def historical(
     data: dt.date,
     codigo_contrato: str | list[str],
-    full_report: bool | None = None,
+    full_report: bool = False,
 ) -> 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 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).
+        full_report: Se False (padrão), tenta SPR primeiro e PR como
+            fallback. Se True, usa apenas o PR completo (~2 MB).
 
     Returns:
         DataFrame Polars com dados históricos de futuros.
@@ -202,16 +201,13 @@ def listar_datas_disponiveis(codigo_contrato: str) -> pl.Series:
     )
 
 
-def _buscar_price_report(
-    data: dt.date, codigo: str, full_report: bool | None
-) -> pl.DataFrame:
+def _buscar_price_report(data: dt.date, codigo: str, full_report: bool) -> 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.
+    Se full_report é True, usa apenas o PR (completo).
+    Se False, tenta o SPR (leve) primeiro e faz fallback para o PR.
     """
-    if full_report is True:
+    if full_report:
         return _normalizar_colunas_pr(
             fetch_price_report(date=data, contract_code=codigo, full_report=True)
         )

{pyield-0.46.6 → pyield-0.46.8}/pyield/b3/futures/intraday.py

@@ -87,6 +87,7 @@ def _intraday_contrato(codigo_contrato: str) -> pl.DataFrame:
 def _preprocessar_df_intraday(df: pl.DataFrame) -> pl.DataFrame:
     return (
         df.filter(pl.col("codigo_mercado") == "FUT")
+        .drop_nulls(subset=["data_vencimento"])
         .rename(
             {
                 "preco_limite_minimo": "taxa_limite_minimo",

{pyield-0.46.6 → pyield-0.46.8}/pyield/b3/intraday_derivatives.py

@@ -1,3 +1,31 @@
+"""Cotações intraday de derivativos da B3 (endpoint DerivativeQuotation).
+
+Exemplo de chamada à API:
+    https://cotacao.b3.com.br/mds/api/v1/DerivativeQuotation/DI1
+
+Exemplo de resposta JSON (resumido):
+    {"Scty": [
+        {"symb": "DI1J30",
+         "desc": "DI DE 1 DIA",
+         "asset": {"code": "DI1",
+                   "AsstSummry": {"mtrtyCode": "2030-04-01",
+                                  "opnCtrcts": 64037,
+                                  "grssAmt": 5272867.79,
+                                  "tradQty": 36,
+                                  "traddCtrctsQty": 89}},
+         "mkt": {"cd": "FUT"},
+         "SctyQtn": {"curPrc": 14.105, "opngPric": 14.22,
+                     "minPric": 14.02, "maxPric": 14.22,
+                     "avrgPric": 14.1013,
+                     "prvsDayAdjstmntPric": 14.127,
+                     "bottomLmtPric": 13.16,
+                     "topLmtPric": 15.385},
+         "buyOffer": {"price": 14.105},
+         "sellOffer": {"price": 14.13}},
+        ...
+    ]}
+"""
+
 import datetime as dt
 import logging
 
@@ -122,6 +150,8 @@ def fetch_intraday_derivatives(contract_code: str) -> pl.DataFrame:
         * preco_oferta_compra (Float64): melhor oferta de compra (opcional).
         * preco_oferta_venda (Float64): melhor oferta de venda (opcional).
         * tipo_lado (String): tipo de lado (opcional).
+        * atualizado_as (Datetime): horário aproximado a que o dado se
+          refere (horário da consulta menos 15 min de atraso da fonte).
     """
     if not intraday_disponivel():
         return pl.DataFrame()
@@ -133,9 +163,8 @@ def fetch_intraday_derivatives(contract_code: str) -> pl.DataFrame:
     return (
         _converter_json_intraday(dados_json)
         .pipe(_processar_colunas_intraday)
-        .drop_nulls(subset=["data_vencimento"])
         .with_columns(
             atualizado_as=clock.now() - dt.timedelta(minutes=15),
         )
-        .sort("codigo_mercado", "codigo_negociacao")
+        .sort("codigo_negociacao")
     )

{pyield-0.46.6 → pyield-0.46.8}/pyield/b3/price_report.py

@@ -43,7 +43,7 @@ COLUNAS_PRICE_REPORT: list[tuple[str, str, type[pl.DataType]]] = [
     ("3.01.01", "Id", pl.String),
     ("3.01.02.01", "Prtry", pl.String),
     ("3.02.01", "MktIdrCd", pl.String),
-    ("4.01", "DaysToSttlm", pl.String),
+    ("4.01", "DaysToSttlm", pl.Int64),
     ("4.02", "TradQty", pl.Int64),
     ("5.01", "MktDataStrmId", pl.String),
     ("5.02", "NtlFinVol", pl.Float64),
@@ -102,27 +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
-        xml_nomes = [n for n in nomes_externos if n.endswith(".xml")]
-        if xml_nomes:
-            xml_nomes.sort()
-            return zip_externo.read(xml_nomes[-1])
-
-        # Caso 2: ZIP aninhado — o primeiro arquivo interno é outro ZIP
-        conteudo_interno = zip_externo.read(nomes_externos[0])
-
-    with zipfile.ZipFile(io.BytesIO(conteudo_interno), "r") as zip_interno:
-        xml_nomes = [n for n in zip_interno.namelist() if n.endswith(".xml")]
-        if not xml_nomes:
-            raise ValueError("Nenhum XML encontrado no ZIP")
-        xml_nomes.sort()
-        return zip_interno.read(xml_nomes[-1])
+        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:
@@ -219,7 +210,14 @@ def _obter_xml_price_report(data: dt.date, relatorio_completo: bool) -> bytes:
     dados_zip = _baixar_zip_url(data, relatorio_completo)
     if not dados_zip:
         return bytes()
-    return _extrair_xml_de_zip(dados_zip)
+    try:
+        return _extrair_xml_de_zip(dados_zip)
+    except zipfile.BadZipFile:
+        registro.warning("ZIP corrompido na transmissão, re-baixando...")
+        dados_zip = _baixar_zip_url(data, relatorio_completo)
+        if not dados_zip:
+            return bytes()
+        return _extrair_xml_de_zip(dados_zip)
 
 
 def fetch_price_report(
@@ -264,7 +262,7 @@ def fetch_price_report(
         * Id (String): identificador do instrumento.
         * Prtry (String): tipo do identificador proprietário.
         * MktIdrCd (String): código do mercado.
-        * DaysToSttlm (String): dias para liquidação.
+        * DaysToSttlm (Int64): dias para liquidação.
         * TradQty (Int64): número de negócios.
         * MktDataStrmId (String): identificador do fluxo de dados.
         * NtlFinVol (Float64): volume financeiro nacional bruto.
@@ -303,9 +301,8 @@ def fetch_price_report(
 
     Raises:
         requests.HTTPError: Se a requisição HTTP ao endpoint falhar.
-        zipfile.BadZipFile: Se o arquivo ZIP recebido estiver corrompido.
+        zipfile.BadZipFile: Se o ZIP estiver corrompido após re-download.
         etree.XMLSyntaxError: Se o XML recebido estiver malformado.
-        Exception: Erros críticos inesperados são propagados após log.
 
     Examples:
         >>> import pyield as yd
@@ -328,25 +325,15 @@ def fetch_price_report(
     if not data_negociacao_valida(date):
         return pl.DataFrame()
 
-    try:
-        xml_bytes = _obter_xml_price_report(date, full_report)
-        dataframes = []
-        for contrato in contratos:
-            df = _processar_xml_extraido(xml_bytes, contrato)
-            if not df.is_empty():
-                dataframes.append(df)
-        if not dataframes:
-            return pl.DataFrame()
-        return pl.concat(dataframes, how="diagonal").sort("TckrSymb")
-    except (zipfile.BadZipFile, etree.XMLSyntaxError):
-        registro.exception(f"Falha ao parsear o price report de {contratos} em {date}.")
-        raise
-    except Exception:
-        tipo = "PR" if full_report else "SPR"
-        registro.exception(
-            f"ERRO CRÍTICO: Falha ao processar {contratos} {tipo} em {date}"
-        )
-        raise
+    xml_bytes = _obter_xml_price_report(date, full_report)
+    dataframes = []
+    for contrato in contratos:
+        df = _processar_xml_extraido(xml_bytes, contrato)
+        if not df.is_empty():
+            dataframes.append(df)
+    if not dataframes:
+        return pl.DataFrame()
+    return pl.concat(dataframes, how="diagonal").sort("TckrSymb")
 
 
 def read_price_report(

pyield-0.46.6/pyield/__about__.py

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

pyield-0.46.6/pyield/anbima/difusao.py

@@ -1,163 +0,0 @@
-import datetime as dt
-import logging
-
-import polars as pl
-import requests
-
-import pyield._internal.converters as cv
-from pyield import bday
-from pyield._internal.br_numbers import taxa_br
-from pyield._internal.cache import ttl_cache
-from pyield._internal.types import DateLike, any_is_empty
-
-VERSAO_API = "1.0018"
-URL_BASE = (
-    f"https://www.anbima.com.br/sistemas/taxasonline/consulta/versao/{VERSAO_API}"
-)
-
-URL_PAGINA_INICIAL = f"{URL_BASE}/taxasOnline.asp"
-URL_CONSULTA_DADOS = f"{URL_BASE}/exibedados.asp"
-URL_DOWNLOAD = f"{URL_BASE}/download_dados.asp?extensao=csv"
-
-logger = logging.getLogger(__name__)
-
-
-@ttl_cache()
-def _buscar_dados_url(data_referencia: str) -> bytes:
-    cabecalhos = {
-        "Referer": URL_PAGINA_INICIAL,
-        "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36",  # noqa
-        "Origin": "https://www.anbima.com.br",
-        "Content-Type": "application/x-www-form-urlencoded",
-    }
-    carga = {
-        "dataref": data_referencia,
-        "dtRefIdioma": data_referencia,
-        "layoutimprimir": "0",
-        "idioma": "",
-        "idresumo": "",
-        "nome": "",
-        "provedor": "",
-        "codigo": "",
-        "vencimento": "",
-        "referencia": "",
-        "dbNome": "",
-        "fldColunas": ["C2", "C17", "C18", "C19"],
-    }
-
-    # Timeouts (conexão, leitura) ajustados ao perfil de cada request:
-    # - GET inicial: página leve, apenas para estabelecer cookies de sessão.
-    # - POST consulta: dispara a query no servidor (~30s observado em uso normal).
-    # - POST download: dados já preparados pelo POST anterior, resposta rápida.
-    timeout_pagina = (10, 20)
-    timeout_consulta = (10, 120)
-    timeout_download = (10, 30)
-
-    with requests.Session() as s:
-        s.get(URL_PAGINA_INICIAL, headers=cabecalhos, timeout=timeout_pagina)
-        try:
-            response_consulta = s.post(
-                URL_CONSULTA_DADOS,
-                headers=cabecalhos,
-                data=carga,
-                timeout=timeout_consulta,
-            )
-            response_consulta.raise_for_status()
-            response_download = s.post(
-                URL_DOWNLOAD,
-                headers=cabecalhos,
-                data=carga,
-                timeout=timeout_download,
-            )
-            response_download.raise_for_status()
-            if "text/html" in response_download.headers.get("Content-Type", ""):
-                raise ValueError(
-                    "Servidor respondeu com HTML em vez de CSV para a data "
-                    f"{data_referencia}."
-                )
-            response_download.encoding = "iso-8859-1"
-            return response_download.text.encode("utf-8")
-        except requests.exceptions.RequestException as e:
-            logger.error(f"Erro ao buscar dados para a data '{data_referencia}': {e}")
-            raise
-
-
-def _ler_csv_bruto(csv_bruto: bytes) -> pl.DataFrame:
-    """Lê o CSV bruto da Anbima e devolve DataFrame com todas as colunas string."""
-    return pl.read_csv(
-        csv_bruto,
-        separator=";",
-        infer_schema=False,
-        skip_rows=1,
-    ).with_columns(pl.all().str.strip_chars())
-
-
-def _processar_csv(data_ref: dt.date, df: pl.DataFrame) -> pl.DataFrame:
-    """Converte o DataFrame bruto em DataFrame Polars estruturado."""
-
-    return (
-        df.with_columns(
-            data_vencimento=pl.col("Vencimento").str.to_date(format="%d/%m/%Y"),
-            horario=pl.when(pl.col("Provedor") == "ANBIMA 12H")
-            .then(dt.time(12, 0))
-            .otherwise(pl.col("Horário").str.to_time(format="%H:%M:%S")),
-            taxa_venda=taxa_br("Oferta Venda"),
-            taxa_compra=taxa_br("Oferta Compra"),
-        )
-        .select(
-            data_hora_referencia=pl.lit(data_ref).dt.combine(pl.col("horario")),
-            provedor=pl.col("Provedor"),
-            titulo=pl.col("Título"),
-            data_vencimento=pl.col("data_vencimento"),
-            isin=pl.col("Código ISIN"),
-            dias_uteis=bday.count_expr(data_ref, "data_vencimento"),
-            taxa_indicativa_anterior=taxa_br("Fech D-1"),
-            taxa_indicativa_superior=taxa_br("Indicativo Superior"),
-            taxa_indicativa_inferior=taxa_br("Indicativo Inferior"),
-            taxa_venda=pl.col("taxa_venda"),
-            taxa_compra=pl.col("taxa_compra"),
-            taxa_media=pl.mean_horizontal("taxa_compra", "taxa_venda"),
-            taxa_ultima=taxa_br("Última"),
-        )
-        .sort("titulo", "data_vencimento", "data_hora_referencia")
-    )
-
-
-def tpf_difusao(data_referencia: DateLike) -> pl.DataFrame:
-    """
-    Obtém a TPF Difusão da Anbima para uma data de referência específica.
-
-    Args:
-        data_referencia (DateLike): Data de referência.
-
-    Returns:
-        pl.DataFrame: DataFrame com os dados.
-
-    Raises:
-        requests.RequestException: Em falhas operacionais de rede ou HTTP.
-        ValueError: Em resposta inválida da API ou erro de parsing do CSV.
-
-    Output Columns:
-        - data_hora_referencia (Datetime): Data e hora de referência da taxa.
-        - provedor (string): Provedor dos dados.
-        - titulo (string): Nome do título (ex: LFT, LTN).
-        - data_vencimento (date): Data de vencimento do título.
-        - isin (string): código ISIN do título.
-        - dias_uteis (int): Dias úteis entre a data de referência e o vencimento.
-        - taxa_indicativa_anterior (float): Taxa indicativa de fechamento D-1 (decimal).
-        - taxa_indicativa_superior (float): Limite superior da banda indicativa (decimal).
-        - taxa_indicativa_inferior (float): Limite inferior da banda indicativa (decimal).
-        - taxa_venda (float): Taxa de oferta de venda (Ask rate) (decimal).
-        - taxa_compra (float): Taxa de oferta de compra (Bid rate) (decimal).
-        - taxa_media (float): Média entre a taxa de compra e venda (decimal).
-        - taxa_ultima (float): Última taxa negociada (decimal).
-    """
-    if any_is_empty(data_referencia):
-        return pl.DataFrame()
-    data = cv.converter_datas(data_referencia)
-    if not bday.is_business_day(data):
-        return pl.DataFrame()
-    data_str = data.strftime("%d/%m/%Y")
-    csv_bruto = _buscar_dados_url(data_str)
-    df = _ler_csv_bruto(csv_bruto)
-    return _processar_csv(data, df)