pyield 0.51.0__tar.gz → 0.51.2__tar.gz

{pyield-0.51.0 → pyield-0.51.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: pyield
-Version: 0.51.0
+Version: 0.51.2
 Summary: Polars-powered toolkit for Brazilian fixed income analysis
 Keywords: fixed-income,brazil,finance,analysis,bonds
 Author: Carlos Carvalho

{pyield-0.51.0 → pyield-0.51.2}/pyield/__init__.py

@@ -12,7 +12,7 @@ from pyield.futuro import di1
 # durante a inicialização do pacote.
 from pyield import selic, tpf
 from pyield.bc.sgs import ptax, ptax_serie
-from pyield.fwd import forward, forwards
+from pyield.fwd import forward, forwards, forwards_expr
 from pyield.interpolador import Interpolador
 from pyield.relogio import agora, hoje
 from pyield.tpf import lft, ltn, ntnb, ntnb1, ntnbprinc, ntnc, ntnf
@@ -31,6 +31,7 @@ __all__ = [
     "du",
     "forward",
     "forwards",
+    "forwards_expr",
     "futuro",
     "hoje",
     "Interpolador",

{pyield-0.51.0 → pyield-0.51.2}/pyield/_internal/converters.py

@@ -162,12 +162,12 @@ def converter_datas(
             2024-12-27
         ]
     """
-    if not types.is_collection(dates):
-        eh_escalar = True
-        serie = pl.Series(values=[dates])
-    else:
+    if types.is_array_like(dates):
         eh_escalar = False
         serie = pl.Series(values=dates)
+    else:
+        eh_escalar = True
+        serie = pl.Series(values=[dates])
 
     serie = (
         pl.DataFrame({"dates": serie}, nan_to_null=True)

{pyield-0.51.0 → pyield-0.51.2}/pyield/_internal/types.py

@@ -1,7 +1,7 @@
 import datetime as dt
 import math
-from collections.abc import Collection, Sized
-from typing import Any, TypeAlias
+from collections.abc import Sized
+from typing import Any, TypeAlias, TypeGuard
 
 import polars as pl
 
@@ -32,18 +32,18 @@ def any_is_empty(*args: Any) -> bool:
     return any(_is_empty(arg) for arg in args)
 
 
-def is_collection(arg: Any) -> bool:
-    """Verifica se o argumento é uma coleção (array-like), excluindo strings e bytes."""
-    return isinstance(arg, Collection) and not isinstance(arg, (str, bytes))
+def is_array_like(arg: Any) -> TypeGuard[ArrayLike]:
+    """Verifica se o argumento segue o contrato interno de ``ArrayLike``."""
+    return isinstance(arg, (list, tuple, pl.Series))
 
 
-def any_is_collection(*args: Any) -> bool:
-    """Verifica se algum dos argumentos fornecidos é uma coleção (array-like).
+def any_is_array_like(*args: Any) -> bool:
+    """Verifica se algum dos argumentos fornecidos é ``ArrayLike``.
 
     Args:
         *args: Uma lista variável de argumentos de qualquer tipo.
 
     Returns:
-        bool: True se algum argumento for uma coleção, caso contrário False.
+        bool: True se algum argumento for ``ArrayLike``, caso contrário False.
     """
-    return any(is_collection(arg) for arg in args)
+    return any(is_array_like(arg) for arg in args)

{pyield-0.51.0 → pyield-0.51.2}/pyield/anbima/imaq.py

@@ -11,7 +11,7 @@ import datetime as dt
 import polars as pl
 import polars.selectors as ps
 import requests
-from lxml.html import HTMLParser
+from lxml.html import HtmlElement, HTMLParser
 from lxml.html import fromstring as html_fromstring
 
 import pyield._internal.converters as cv
@@ -47,6 +47,15 @@ def _normalizar_nome_coluna(texto: str) -> str:
     return " ".join(texto.strip().split())
 
 
+def _xpath_elementos(elemento: HtmlElement, expressao: str) -> list[HtmlElement]:
+    resultado = elemento.xpath(expressao)
+    if not isinstance(resultado, list) or not all(
+        isinstance(item, HtmlElement) for item in resultado
+    ):
+        raise TypeError("XPath deveria retornar uma lista de elementos HTML.")
+    return resultado
+
+
 def _parsear_tabelas_html(html_content: bytes) -> pl.DataFrame:
     """Parseia tabelas HTML com lxml e retorna DataFrame via read_csv.
 
@@ -58,19 +67,22 @@ def _parsear_tabelas_html(html_content: bytes) -> pl.DataFrame:
     parser = HTMLParser(encoding="iso-8859-1")
     tree = html_fromstring(html_content, parser=parser)
 
-    nested_tables = tree.xpath("//table[@width='100%'][parent::td]")
+    if not isinstance(tree, HtmlElement):
+        raise TypeError("HTML deveria ser parseado como elemento HTML.")
+
+    nested_tables = _xpath_elementos(tree, "//table[@width='100%'][parent::td]")
 
     linhas = []
     nomes_colunas = None
 
-    for table in nested_tables:  # type: ignore[misc]
-        headers = table.xpath(".//thead//th")
+    for table in nested_tables:
+        headers = _xpath_elementos(table, ".//thead//th")
         if not nomes_colunas:
             nomes_colunas = [_normalizar_nome_coluna(h.text_content()) for h in headers]
 
-        data_rows = table.xpath(".//tbody//tr[td]")
+        data_rows = _xpath_elementos(table, ".//tbody//tr[td]")
         for row in data_rows:
-            cells = row.xpath(".//td")
+            cells = _xpath_elementos(row, ".//td")
             if len(cells) != len(nomes_colunas):
                 continue
             linhas.append("\t".join(c.text_content().strip() for c in cells))

{pyield-0.51.0 → pyield-0.51.2}/pyield/b3/boletim.py

@@ -97,7 +97,7 @@ COLUNAS_PRICE_REPORT: list[tuple[str, str, type[pl.DataType]]] = [
 ]
 
 # Schema completo: nome_xml → tipo_polars. Garante ordem e tipagem constante.
-SCHEMA_PRICE_REPORT = {nome: tipo for _, nome, tipo in COLUNAS_PRICE_REPORT}
+SCHEMA_PRICE_REPORT = pl.Schema({nome: tipo for _, nome, tipo in COLUNAS_PRICE_REPORT})
 
 logger = logging.getLogger(__name__)
 _SESSAO = requests.Session()
@@ -146,7 +146,32 @@ def baixar_zip(data: DateLike, boletim_completo: bool = False) -> bytes:
     return resposta.content
 
 
-def _zip_valido(conteudo_zip: bytes) -> bool:  # noqa: PLR0911
+def _zip_tem_xml_valido(conteudo_zip: bytes) -> bool:  # noqa: PLR0911
+    with zipfile.ZipFile(io.BytesIO(conteudo_zip), "r") as zip_externo:
+        nomes = zip_externo.namelist()
+        if not nomes:
+            logger.debug("ZIP externo do boletim está vazio.")
+            return False
+        if zip_externo.testzip() is not None:
+            logger.debug("ZIP externo do boletim contém arquivo corrompido.")
+            return False
+
+        conteudo_interno = zip_externo.read(nomes[0])
+        with zipfile.ZipFile(io.BytesIO(conteudo_interno), "r") as zip_interno:
+            nomes_xml = [
+                nome for nome in zip_interno.namelist() if nome.endswith(".xml")
+            ]
+            if not nomes_xml:
+                logger.debug("ZIP interno do boletim não contém XML.")
+                return False
+            if zip_interno.testzip() is not None:
+                logger.debug("ZIP interno do boletim contém arquivo corrompido.")
+                return False
+
+    return True
+
+
+def _zip_valido(conteudo_zip: bytes) -> bool:
     """Verifica se o ZIP bruto do boletim contém um XML legível."""
     tamanho_minimo = 1024  # ZIP válido ~2KB; 1KB detecta arquivos "sem dados"
     if len(conteudo_zip) < tamanho_minimo:
@@ -154,33 +179,11 @@ def _zip_valido(conteudo_zip: bytes) -> bool:  # noqa: PLR0911
         return False
 
     try:
-        with zipfile.ZipFile(io.BytesIO(conteudo_zip), "r") as zip_externo:
-            nomes = zip_externo.namelist()
-            if not nomes:
-                logger.debug("ZIP externo do boletim está vazio.")
-                return False
-            if zip_externo.testzip() is not None:
-                logger.debug("ZIP externo do boletim contém arquivo corrompido.")
-                return False
-
-            conteudo_interno = zip_externo.read(nomes[0])
-            with zipfile.ZipFile(io.BytesIO(conteudo_interno), "r") as zip_interno:
-                nomes_xml = [
-                    nome for nome in zip_interno.namelist() if nome.endswith(".xml")
-                ]
-                if not nomes_xml:
-                    logger.debug("ZIP interno do boletim não contém XML.")
-                    return False
-                if zip_interno.testzip() is not None:
-                    logger.debug("ZIP interno do boletim contém arquivo corrompido.")
-                    return False
-
+        return _zip_tem_xml_valido(conteudo_zip)
     except (zipfile.BadZipFile, KeyError, OSError, RuntimeError):
         logger.debug("ZIP do boletim inválido ou ilegível.")
         return False
 
-    return True
-
 
 def _extrair(conteudo_zip: bytes) -> bytes:
     """Extrai o XML válido do ZIP aninhado do Price Report da B3.
@@ -210,6 +213,20 @@ def _extrair(conteudo_zip: bytes) -> bytes:
             return zip_interno.read(nomes_xml[-1])
 
 
+def _xpath_elementos_xml(
+    elemento: etree._ElementTree | etree._Element,
+    expressao: str,
+    *,
+    namespaces: dict[str, str] | None = None,
+) -> list[etree._Element]:
+    resultado = elemento.xpath(expressao, namespaces=namespaces)
+    if not isinstance(resultado, list) or not all(
+        isinstance(item, etree._Element) for item in resultado
+    ):
+        raise TypeError("XPath deveria retornar uma lista de elementos XML.")
+    return [item for item in resultado if isinstance(item, etree._Element)]
+
+
 def _extrair_dados_contrato(pric_rpt: etree._Element) -> dict | None:
     dados = {}
     tem_ticker = False
@@ -266,8 +283,7 @@ def _parsear_xml_registros(xml_bytes: bytes) -> list[dict]:
         load_dtd=False,
     )
     arvore = etree.parse(io.BytesIO(xml_bytes), parser=analisador)
-    resultado = arvore.xpath("//ns:PricRpt", namespaces=namespaces)
-    elementos: list[etree._Element] = resultado  # type: ignore[assignment]
+    elementos = _xpath_elementos_xml(arvore, "//ns:PricRpt", namespaces=namespaces)
     registros = [
         dados
         for pric_rpt in elementos
@@ -282,7 +298,7 @@ def _converter_para_df(registros: list[dict]) -> pl.DataFrame:
     # (pl.DataFrame infere colunas de ~50 primeiras linhas por padrão.)
     schema_str = {nome: pl.String for nome in SCHEMA_PRICE_REPORT}
     df = pl.DataFrame(registros, schema=schema_str)
-    return df.cast(SCHEMA_PRICE_REPORT, strict=False)  # type: ignore
+    return df.cast(SCHEMA_PRICE_REPORT, strict=False)
 
 
 def _processar_xml_extraido(xml_bytes: bytes) -> pl.DataFrame:

{pyield-0.51.0 → pyield-0.51.2}/pyield/du/core.py

@@ -214,7 +214,7 @@ def contar(
         .get_column("dias_uteis")
     )
 
-    if not tp.any_is_collection(inicio, fim):
+    if not tp.any_is_array_like(inicio, fim):
         return s.item()
 
     return s
@@ -490,7 +490,7 @@ def deslocar(
         .get_column("data_ajustada")
     )
 
-    if not tp.any_is_collection(datas, deslocamento):
+    if not tp.any_is_array_like(datas, deslocamento):
         return s.item()
 
     return s
@@ -672,7 +672,7 @@ def eh_dia_util(datas: None | DateLike | ArrayLike) -> None | bool | pl.Series:
         .get_column("eh_dia_util")
     )
 
-    if not tp.any_is_collection(datas):
+    if not tp.any_is_array_like(datas):
         return s.item()
 
     return s

{pyield-0.51.0 → pyield-0.51.2}/pyield/futuro/contratos.py

@@ -4,7 +4,7 @@ from typing import overload
 import polars as pl
 
 from pyield import du
-from pyield._internal.types import ArrayLike, any_is_collection
+from pyield._internal.types import ArrayLike, any_is_array_like
 
 # Lista de contratos que negociam por taxa (juros/cupom).
 # Nestes contratos, as colunas OHLC são taxas e precisam ser divididas por 100.
@@ -80,14 +80,14 @@ def vencimento(
             null
         ]
     """
-    dados = codigo if any_is_collection(codigo) else [codigo]
+    dados = codigo if any_is_array_like(codigo) else [codigo]
     serie = (
         pl.DataFrame({"codigo": dados})
         .select(vencimento=vencimento_expr("codigo", contrato))
         .get_column("vencimento")
     )
 
-    if any_is_collection(codigo):
+    if any_is_array_like(codigo):
         return serie
 
     return serie.item()

{pyield-0.51.0 → pyield-0.51.2}/pyield/futuro/di1.py

@@ -5,16 +5,25 @@ Fonte:
     Report e usados como curva de ajuste do DI1.
 """
 
+from typing import Literal
+
 import polars as pl
 
 import pyield._internal.converters as cv
 from pyield import du
 from pyield._internal.data_cache import obter_dataset_cacheado
-from pyield._internal.types import ArrayLike, DateLike, any_is_collection, any_is_empty
+from pyield._internal.types import ArrayLike, DateLike, any_is_array_like, any_is_empty
 from pyield.futuro.historico import buscar_historico_cacheado
 from pyield.futuro.historico import datas_disponiveis as _datas_futuro
 from pyield.interpolador import Interpolador
 
+TipoTaxaDI1 = Literal["ajuste", "fechamento"]
+
+_COLUNAS_TIPO_TAXA: dict[TipoTaxaDI1, str] = {
+    "ajuste": "taxa_ajuste",
+    "fechamento": "taxa_fechamento",
+}
+
 
 def dados(
     datas: DateLike | ArrayLike,
@@ -111,6 +120,7 @@ def interpolar_taxas(
     datas_referencia: DateLike | ArrayLike,
     datas_vencimento: DateLike | ArrayLike,
     extrapolar: bool = True,
+    tipo_taxa: TipoTaxaDI1 = "ajuste",
 ) -> pl.Series:
     """Interpola taxas de DI para datas de negociação e vencimentos especificados.
 
@@ -130,6 +140,9 @@ def interpolar_taxas(
             compatível em tamanho com ``datas_referencia`` se ambos forem arrays.
         extrapolar: Se permite extrapolação além do intervalo de taxas DI
             conhecidas para uma data de negociação. Padrão: True.
+        tipo_taxa: Tipo de taxa usada como curva de referência. Use
+            ``"ajuste"`` para a taxa de ajuste ou ``"fechamento"`` para a
+            última taxa negociada. Padrão: ``"ajuste"``.
 
     Returns:
         Series contendo as taxas DI interpoladas (como floats). Valores serão
@@ -139,10 +152,13 @@ def interpolar_taxas(
     Raises:
         ValueError: Se ``datas_referencia`` e ``datas_vencimento`` forem ambos
             array-like mas tiverem tamanhos diferentes.
+        ValueError: Se ``tipo_taxa`` não for ``"ajuste"`` ou ``"fechamento"``.
 
     Notes:
-        - Todas as taxas de liquidação disponíveis são usadas para interpolação
-          flat-forward.
+        - Todas as taxas disponíveis do tipo escolhido são usadas para
+          interpolação flat-forward.
+        - ``tipo_taxa="fechamento"`` usa a última taxa negociada (last trade),
+          que pode ter menos vértices disponíveis que a curva de ajuste.
         - A função trata broadcasting de entradas escalares e array-like.
 
     Examples:
@@ -191,6 +207,10 @@ def interpolar_taxas(
             null
         ]
     """
+    coluna_taxa = _COLUNAS_TIPO_TAXA.get(tipo_taxa)
+    if coluna_taxa is None:
+        raise ValueError("tipo_taxa deve ser 'ajuste' ou 'fechamento'.")
+
     if any_is_empty(datas_referencia, datas_vencimento):
         return pl.Series(dtype=pl.Float64)
 
@@ -217,7 +237,7 @@ def interpolar_taxas(
     # Inicializa taxa_interpolada como None
     df_entrada = df_entrada.with_columns(
         dias_uteis=du.contar_expr("data_referencia", "data_vencimento"),
-        taxa_interpolada=None,
+        taxa_interpolada=pl.lit(None, dtype=pl.Float64),
     )
 
     # Lista para armazenar os blocos processados
@@ -237,10 +257,15 @@ def interpolar_taxas(
             blocos_processados.append(df_parcial)
             continue
 
+        df_curva = df_referencia.select("dias_uteis", coluna_taxa).drop_nulls()
+        if df_curva.is_empty():
+            blocos_processados.append(df_parcial)
+            continue
+
         # Inicializa o interpolador com taxas e dias úteis conhecidos
         interpolador_du = Interpolador(
-            dias_uteis=df_referencia["dias_uteis"],
-            taxas=df_referencia["taxa_ajuste"],
+            dias_uteis=df_curva["dias_uteis"],
+            taxas=df_curva[coluna_taxa],
             metodo="flat_forward",
             extrapolar=extrapolar,
         )
@@ -267,6 +292,7 @@ def interpolar_taxa(
     data_referencia: DateLike,
     data_vencimento: DateLike,
     extrapolar: bool = False,
+    tipo_taxa: TipoTaxaDI1 = "ajuste",
 ) -> float:
     """Interpola ou obtém a taxa DI para uma única data de vencimento.
 
@@ -282,6 +308,9 @@ def interpolar_taxa(
         extrapolar: Se True, permite extrapolação se o ``data_vencimento`` estiver
             fora do intervalo de vencimentos de contratos disponíveis para a
             ``data_referencia``. Padrão: False.
+        tipo_taxa: Tipo de taxa usada como curva de referência. Use
+            ``"ajuste"`` para a taxa de ajuste ou ``"fechamento"`` para a
+            última taxa negociada. Padrão: ``"ajuste"``.
 
     Returns:
         Taxa de liquidação DI exata ou interpolada para a data e vencimento
@@ -305,7 +334,7 @@ def interpolar_taxa(
         >>> di1.interpolar_taxa("25-04-2025", "01-01-2050", extrapolar=True)
         0.13881
     """
-    if any_is_collection(data_referencia, data_vencimento):
+    if any_is_array_like(data_referencia, data_vencimento):
         raise ValueError(
             "As entradas 'data_referencia' e 'data_vencimento' devem ser datas escalares."
         )
@@ -314,6 +343,7 @@ def interpolar_taxa(
         datas_referencia=data_referencia,
         datas_vencimento=data_vencimento,
         extrapolar=extrapolar,
+        tipo_taxa=tipo_taxa,
     )
     if taxa.is_empty():
         return float("nan")

{pyield-0.51.0 → pyield-0.51.2}/pyield/futuro/historico.py

@@ -10,7 +10,7 @@ from pyield._internal.data_cache import obter_dataset_cacheado
 from pyield._internal.types import ArrayLike, DateLike, any_is_empty
 from pyield.b3._validar_pregao import data_negociacao_valida
 from pyield.futuro import contratos as ct
-from pyield.fwd import forwards
+from pyield.fwd import forwards_expr
 
 # Renomeação preco_* → taxa_* para contratos cotados por taxa.
 # Bid/Ask são invertidos: BestBidPric (bid em PU) = menor taxa = venda de taxa;
@@ -128,10 +128,10 @@ def _enriquecer_dados(df: pl.DataFrame, contrato: str) -> pl.DataFrame:
 
     if contrato in {"DI1", "DAP"}:
         df = df.with_columns(
-            taxa_forward=forwards(
-                dias_uteis=df["dias_uteis"],
-                taxas=df["taxa_ajuste"],
-                agrupar_por=df["data_referencia"],
+            taxa_forward=forwards_expr(
+                dias_uteis="dias_uteis",
+                taxas="taxa_ajuste",
+                agrupar_por="data_referencia",
             )
         )
 

{pyield-0.51.0 → pyield-0.51.2}/pyield/futuro/intradia.py

@@ -6,7 +6,7 @@ from pyield._internal.br_numbers import pct_para_decimal
 from pyield.b3._validar_pregao import intradia_disponivel
 from pyield.b3.derivativos_intradia import derivativo_intradia
 from pyield.futuro.contratos import CONTRATOS_TAXA, dv01_expr
-from pyield.fwd import forwards
+from pyield.fwd import forwards_expr
 
 # Renomeação preco_* → taxa_* para contratos cotados por taxa.
 _PRECO_PARA_TAXA_INTRADIA = {
@@ -157,10 +157,12 @@ def _processar_intradia(df: pl.DataFrame, contrato: str) -> pl.DataFrame:
         df = df.with_columns(pct_para_decimal(cs.starts_with("taxa_")))
 
     if contrato in {"DI1", "DAP"}:
-        taxa_fwd = forwards(dias_uteis=df["dias_uteis"], taxas=df["taxa_ultima"])
         anos_uteis = pl.col("dias_uteis") / 252
         preco_ultimo = 100_000 / ((1 + pl.col("taxa_ultima")) ** anos_uteis)
-        df = df.with_columns(preco_ultimo=preco_ultimo.round(2), taxa_forward=taxa_fwd)
+        df = df.with_columns(
+            preco_ultimo=preco_ultimo.round(2),
+            taxa_forward=forwards_expr("dias_uteis", "taxa_ultima"),
+        )
 
     if contrato == "DI1":
         df = df.with_columns(