pyield 0.47.2__tar.gz → 0.47.4__tar.gz

{pyield-0.47.2 → pyield-0.47.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyield
-Version: 0.47.2
+Version: 0.47.4
 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
@@ -206,23 +206,22 @@ ntnf.di_spreads("30-05-2025", bps=True)
 ## Dados de Futuros
 
 ```python
-from pyield import futures
+from pyield import futures, futures_intraday
 
 # DI1 (Futuro de Depósito Interfinanceiro)
 futures("31-05-2024", "DI1")
 
-# Outros contratos disponíveis:
-# - 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
+# Outros contratos disponíveis no cache histórico:
+# - Juros: DI1, DDI, FRC, FRO, DAP
+# - Moedas: DOL, WDO
+# - Índices: IND, WIN
 futures("31-05-2024", "DAP")
 
-# Múltiplos contratos de uma vez
-futures("31-05-2024", ["DI1", "DAP"])
+# Múltiplas datas de uma vez
+futures(["29-05-2024", "31-05-2024"], "DI1")
 
 # Dados intradiários (quando o mercado estiver aberto)
-futures("16-01-2025", "DI1")  # Retorna dados ao vivo durante o horário de negociação
+futures_intraday("DI1")  # Retorna dados ao vivo durante o horário de negociação
 ```
 
 ## Tratamento de Datas

{pyield-0.47.2 → pyield-0.47.4}/README.md

@@ -162,23 +162,22 @@ ntnf.di_spreads("30-05-2025", bps=True)
 ## Dados de Futuros
 
 ```python
-from pyield import futures
+from pyield import futures, futures_intraday
 
 # DI1 (Futuro de Depósito Interfinanceiro)
 futures("31-05-2024", "DI1")
 
-# Outros contratos disponíveis:
-# - 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
+# Outros contratos disponíveis no cache histórico:
+# - Juros: DI1, DDI, FRC, FRO, DAP
+# - Moedas: DOL, WDO
+# - Índices: IND, WIN
 futures("31-05-2024", "DAP")
 
-# Múltiplos contratos de uma vez
-futures("31-05-2024", ["DI1", "DAP"])
+# Múltiplas datas de uma vez
+futures(["29-05-2024", "31-05-2024"], "DI1")
 
 # Dados intradiários (quando o mercado estiver aberto)
-futures("16-01-2025", "DI1")  # Retorna dados ao vivo durante o horário de negociação
+futures_intraday("DI1")  # Retorna dados ao vivo durante o horário de negociação
 ```
 
 ## Tratamento de Datas

pyield-0.47.4/pyield/__about__.py

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

{pyield-0.47.2 → pyield-0.47.4}/pyield/b3/price_report.py

@@ -1,34 +1,58 @@
+"""
+Exemplo de trecho do XML bruto da B3:
+    <PricRpt>
+        <TradDt>
+            <Dt>2026-04-01</Dt>
+        </TradDt>
+        <SctyId>
+            <TckrSymb>DI1F31</TckrSymb>
+        </SctyId>
+        <FinInstrmId>
+            <OthrId>
+                <Id>200000235664</Id>
+                <Tp>
+                    <Prtry>8</Prtry>
+                </Tp>
+            </OthrId>
+            <PlcOfListg>
+                <MktIdrCd>BVMF</MktIdrCd>
+            </PlcOfListg>
+        </FinInstrmId>
+        <TradDtls>
+            <TradQty>29880</TradQty>
+        </TradDtls>
+        <FinInstrmAttrbts>
+            <MktDataStrmId>E</MktDataStrmId>
+            ...
+            <MinTradLmt Ccy="BRL">12.87</MinTradLmt>
+        </FinInstrmAttrbts>
+    </PricRpt>
+"""
+
 import datetime as dt
 import io
-import logging
+import re
 import zipfile
-from functools import lru_cache
 
 import polars as pl
 import requests
 from lxml import etree
-from lxml.etree import _Element
 
 import pyield._internal.converters as cv
+from pyield._internal.cache import ttl_cache
 from pyield._internal.retry import retry_padrao
 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
 
-registro = logging.getLogger(__name__)
-
 # --- Constantes de Processamento XML ---
 NAMESPACE_B3 = "urn:bvmf.217.01.xsd"
 NAMESPACES = {"ns": NAMESPACE_B3}
 # ZIP válido do price report ~2KB; 1KB detecta arquivos "sem dados"
 MIN_TAMANHO_ZIP_BYTES = 1024
-MODELO_XPATH_TICKER = '//ns:TckrSymb[starts-with(text(), "{prefixo_ticker}")]'
-XPATH_DATA_NEGOCIACAO = ".//ns:TradDt/ns:Dt"
-XPATH_ATRIBUTOS_INSTRUMENTO = ".//ns:FinInstrmAttrbts"
-XPATH_DETALHES_NEGOCIO = ".//ns:TradDtls"
+XPATH_PRICE_REPORT = "//ns:PricRpt"
 
 # --- Mapeamento de Colunas ---
-
 # Estrutura: (id_pdf, nome_xml, tipo_polars)
 # Esta camada base preserva os nomes originais do XML da B3.
 # https://www.b3.com.br/data/files/16/70/29/9C/6219D710C8F297D7AC094EA8/Catalogo_precos_v1.3.pdf
@@ -74,10 +98,11 @@ COLUNAS_PRICE_REPORT: list[tuple[str, str, type[pl.DataType]]] = [
     ("5.32", "MinTradLmt", pl.Float64),
 ]
 
-# Mapa de tipos para cast inicial usando os nomes originais do XML.
-TIPOS_XML = {nome_xml: tipo for _, nome_xml, tipo in COLUNAS_PRICE_REPORT}
+# Schema completo: nome_xml → tipo_polars. Garante ordem e tipagem constante.
+SCHEMA_PRICE_REPORT = {nome: tipo for _, nome, tipo in COLUNAS_PRICE_REPORT}
 
 
+@ttl_cache()
 @retry_padrao
 def _baixar_zip_url(data: dt.date, relatorio_completo: bool) -> bytes:
     data_str = data.strftime("%y%m%d")
@@ -124,42 +149,51 @@ def price_report_extract(conteudo_zip: bytes) -> bytes:
             return zip_interno.read(nomes_xml[-1])
 
 
-def _extrair_dados_contrato(elemento_ticker: _Element) -> dict | None:
-    if elemento_ticker.text is None:
-        return None
-    pai = elemento_ticker.getparent()
-    if pai is None:
-        return None
-    registro_pregao = pai.getparent()
-    if registro_pregao is None:
-        return None
-    elemento_data = registro_pregao.find(XPATH_DATA_NEGOCIACAO, NAMESPACES)
-    if elemento_data is None:
-        return None
+def _extrair_dados_contrato(pric_rpt: etree._Element) -> dict | None:
+    dados = {}
+    tem_ticker = False
+    tem_data = False
 
-    dados_ticker = {"TradDt": elemento_data.text, "TckrSymb": elemento_ticker.text}
-    atributos_instr = registro_pregao.find(XPATH_ATRIBUTOS_INSTRUMENTO, NAMESPACES)
-    if atributos_instr is None:
-        return None
+    for elem in pric_rpt.iter():
+        text = elem.text
+        if not text:
+            continue
 
-    for attr in atributos_instr:
-        nome_tag = etree.QName(attr).localname
-        dados_ticker[nome_tag] = attr.text
+        tag = elem.tag
+        if tag[0] == "{":
+            tag = tag[tag.find("}") + 1 :]
 
-    detalhes_negocio = registro_pregao.find(XPATH_DETALHES_NEGOCIO, NAMESPACES)
-    if detalhes_negocio is not None:
-        for detalhe in detalhes_negocio:
-            nome_tag = etree.QName(detalhe).localname
-            dados_ticker[nome_tag] = detalhe.text
+        # 🔑 obrigatórios primeiro
+        if tag == "TckrSymb":
+            dados["TckrSymb"] = text
+            tem_ticker = True
+            continue
 
-    return dados_ticker
+        if tag == "Dt":
+            pai = elem.getparent()
+            if pai is None:
+                continue
 
+            parent = pai.tag
+            if parent[0] == "{":
+                parent = parent[parent.find("}") + 1 :]
 
-def _parsear_xml_registros(
-    xml_bytes: bytes,
-    prefixo_ticker: str,
-    comprimento_ticker: int | None = None,
-) -> list[dict]:
+            if parent == "TradDt":
+                dados["TradDt"] = text
+                tem_data = True
+            continue
+
+        # ⚡ resto
+        if tag in SCHEMA_PRICE_REPORT:
+            dados[tag] = text
+
+    if not tem_ticker or not tem_data:
+        return None
+
+    return dados
+
+
+def _parsear_xml_registros(xml_bytes: bytes) -> list[dict]:
     analisador = etree.XMLParser(
         ns_clean=True,
         remove_blank_text=True,
@@ -169,72 +203,65 @@ def _parsear_xml_registros(
         no_network=True,
         load_dtd=False,
     )
-    arquivo_xml = io.BytesIO(xml_bytes)
-    arvore = etree.parse(arquivo_xml, parser=analisador)
-    caminho_xpath = MODELO_XPATH_TICKER.format(prefixo_ticker=prefixo_ticker)
-    resultado_xpath = arvore.xpath(caminho_xpath, namespaces=NAMESPACES)
-    if not isinstance(resultado_xpath, list):
-        return []
-
-    elementos_ticker = resultado_xpath
-
-    if not elementos_ticker:
-        return []
-
-    registros = []
-    for elemento in elementos_ticker:
-        if not isinstance(elemento, etree._Element):
-            continue
-        dados_contrato = _extrair_dados_contrato(elemento)
-        if dados_contrato is not None:
-            ticker = dados_contrato["TckrSymb"]
-            if comprimento_ticker is None or len(ticker) == comprimento_ticker:
-                registros.append(dados_contrato)
+    arvore = etree.parse(io.BytesIO(xml_bytes), parser=analisador)
+    resultado = arvore.xpath(XPATH_PRICE_REPORT, namespaces=NAMESPACES)
+    elementos: list[etree._Element] = resultado  # type: ignore[assignment]
+    registros = [
+        dados
+        for pric_rpt in elementos
+        if (dados := _extrair_dados_contrato(pric_rpt)) is not None
+    ]
     return registros
 
 
 def _converter_para_df(registros: list[dict]) -> pl.DataFrame:
     df = pl.DataFrame(registros)
     # Casting usa os nomes originais do XML, que são constantes
-    tipos_coluna = {k: v for k, v in TIPOS_XML.items() if k in df.columns}
-    return df.cast(tipos_coluna, strict=False)  # type: ignore
+    tipos_coluna = {k: v for k, v in SCHEMA_PRICE_REPORT.items() if k in df.columns}
+    df = df.cast(tipos_coluna, strict=False)  # type: ignore
+    # Adiciona colunas ausentes com null e garante ordem/schema constante
+    colunas_faltantes = {
+        nome: pl.lit(None).cast(tipo)
+        for nome, tipo in SCHEMA_PRICE_REPORT.items()
+        if nome not in df.columns
+    }
+    if colunas_faltantes:
+        df = df.with_columns(**colunas_faltantes)
+    return df.select(SCHEMA_PRICE_REPORT.keys())
+
+
+def _processar_xml_extraido(xml_bytes: bytes) -> pl.DataFrame:
+    registros = _parsear_xml_registros(xml_bytes)
+    if not registros:
+        return pl.DataFrame()
+    return _converter_para_df(registros).sort("TckrSymb")
 
 
-def _processar_xml_extraido(
-    xml_bytes: bytes,
-    prefixo_ticker: str,
+def _filtrar_df(
+    df: pl.DataFrame,
+    prefixos: list[str],
     comprimento_ticker: int | None = None,
 ) -> pl.DataFrame:
-    registros = (
-        _parsear_xml_registros(xml_bytes, prefixo_ticker, comprimento_ticker)
-        if xml_bytes
-        else []
-    )
-    if not registros:
-        return pl.DataFrame()
-
-    df = _converter_para_df(registros)
+    ticker = pl.col("TckrSymb")
+    if comprimento_ticker:
+        df = df.filter(ticker.str.len_chars() == comprimento_ticker)
+    if prefixos:
+        padrao = f"^({'|'.join(re.escape(prefixo) for prefixo in prefixos)})"
+        df = df.filter(ticker.str.contains(padrao))
     return df.sort("TckrSymb")
 
 
-@lru_cache(maxsize=64)
-def _obter_xml_price_report(data: dt.date, relatorio_completo: bool) -> bytes:
+def _obter_df_price_report(data: dt.date, relatorio_completo: bool) -> pl.DataFrame:
     dados_zip = _baixar_zip_url(data, relatorio_completo)
     if not dados_zip:
-        return bytes()
-    try:
-        return price_report_extract(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 price_report_extract(dados_zip)
+        return pl.DataFrame()
+    xml_bytes = price_report_extract(dados_zip)
+    return _processar_xml_extraido(xml_bytes)
 
 
 def price_report_fetch(
     date: DateLike,
-    ticker_prefix: str | list[str],
+    ticker_prefix: str | list[str] | None = None,
     ticker_length: int | None = None,
     full_report: bool = False,
 ) -> pl.DataFrame:
@@ -259,7 +286,8 @@ def price_report_fetch(
             'YYYY-MM-DD' ou objeto datetime.date.
         ticker_prefix: Prefixo do ticker B3 (ex.: 'DI1', 'DOL',
             'CPM') ou lista de prefixos (ex.: ['DI1', 'DAP']).
-            Usado como filtro starts-with no XML.
+            Usado como filtro starts-with no XML. Se None (padrão),
+            retorna todos os ativos sem filtro.
         ticker_length: Comprimento exato do ticker para filtrar registros.
             Se None (padrão), retorna todos os tickers que casam com o
             prefixo (ex.: 6 para futuros, 13 para opções).
@@ -286,10 +314,8 @@ def price_report_fetch(
         * IntlFinVol (Float64): volume financeiro internacional.
         * OpnIntrst (Int64): contratos em aberto.
         * FinInstrmQty (Int64): quantidade negociada de instrumentos financeiros.
-                * BestBidPric (Float64): ultima melhor oferta de compra no snapshot
-                    diario; pode ser nulo.
-                * BestAskPric (Float64): ultima melhor oferta de venda no snapshot
-                    diario; pode ser nulo.
+        * BestBidPric (Float64): ultima melhor oferta de compra no snapshot diario; pode ser nulo.
+        * BestAskPric (Float64): ultima melhor oferta de venda no snapshot diario; pode ser nulo.                   diario; pode ser nulo.
         * FrstPric (Float64): preço de abertura.
         * MinPric (Float64): preço mínimo negociado.
         * MaxPric (Float64): preço máximo negociado.
@@ -333,8 +359,7 @@ def price_report_fetch(
         >>> df.is_empty()
         True
     """
-    prefixos = normalizar_codigos_contrato(ticker_prefix)
-    if any_is_empty(date) or not prefixos:
+    if any_is_empty(date):
         return pl.DataFrame()
 
     date = cv.converter_datas(date)
@@ -342,20 +367,19 @@ def price_report_fetch(
     if not data_negociacao_valida(date):
         return pl.DataFrame()
 
-    xml_bytes = _obter_xml_price_report(date, full_report)
-    dataframes = []
-    for prefixo in prefixos:
-        df = _processar_xml_extraido(xml_bytes, prefixo, ticker_length)
-        if not df.is_empty():
-            dataframes.append(df)
-    if not dataframes:
+    df = _obter_df_price_report(date, full_report)
+    if df.is_empty() or ticker_prefix is None:
+        return df
+
+    prefixos = normalizar_codigos_contrato(ticker_prefix)
+    if not prefixos:
         return pl.DataFrame()
-    return pl.concat(dataframes, how="diagonal").sort("TckrSymb")
+    return _filtrar_df(df, prefixos, ticker_length)
 
 
 def price_report_read(
     xml_bytes: bytes,
-    ticker_prefix: str | list[str],
+    ticker_prefix: str | list[str] | None = None,
     ticker_length: int | None = None,
 ) -> pl.DataFrame:
     """Lê e processa o price report da B3 a partir do conteúdo XML bruto.
@@ -367,6 +391,7 @@ def price_report_read(
         xml_bytes: Conteúdo do XML em bytes (já descomprimido).
         ticker_prefix: Prefixo do ticker B3 (ex.: 'DI1', 'DOL',
             'CPM') ou lista de prefixos (ex.: ['DI1', 'DAP']).
+            Se None (padrão), retorna todos os ativos sem filtro.
         ticker_length: Comprimento exato do ticker para filtrar registros.
             Se None (padrão), retorna todos os tickers que casam com o
             prefixo.
@@ -375,15 +400,14 @@ def price_report_read(
         pl.DataFrame: DataFrame com as mesmas colunas documentadas em
         :func:`price_report_fetch`.
     """
-    prefixos = normalizar_codigos_contrato(ticker_prefix)
-    if any_is_empty(xml_bytes) or not prefixos:
+    if any_is_empty(xml_bytes):
         return pl.DataFrame()
 
-    dataframes = []
-    for prefixo in prefixos:
-        df = _processar_xml_extraido(xml_bytes, prefixo, ticker_length)
-        if not df.is_empty():
-            dataframes.append(df)
-    if not dataframes:
+    df = _processar_xml_extraido(xml_bytes)
+    if df.is_empty() or ticker_prefix is None:
+        return df
+
+    prefixos = normalizar_codigos_contrato(ticker_prefix)
+    if not prefixos:
         return pl.DataFrame()
-    return pl.concat(dataframes, how="diagonal").sort("TckrSymb")
+    return _filtrar_df(df, prefixos, ticker_length)

pyield-0.47.2/pyield/__about__.py

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