pyield 0.49.1__tar.gz → 0.49.2__tar.gz

{pyield-0.49.1 → pyield-0.49.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: pyield
-Version: 0.49.1
+Version: 0.49.2
 Summary: A Python library for analysis of fixed income instruments in Brazil
 Keywords: fixed-income,brazil,finance,analysis,bonds
 Author: Carlos Carvalho

{pyield-0.49.1 → pyield-0.49.2}/pyield/__init__.py

@@ -3,7 +3,7 @@
 import logging
 from importlib.metadata import PackageNotFoundError, version
 
-from pyield import du, ipca
+from pyield import b3, du, ipca
 from pyield.b3.di_over import di_over
 from pyield import futuro, di1
 
@@ -24,6 +24,7 @@ except PackageNotFoundError:
 __all__ = [
     "__version__",
     "agora",
+    "b3",
     "di1",
     "di_over",
     "du",

pyield-0.49.2/pyield/b3/__init__.py

@@ -0,0 +1,7 @@
+"""APIs técnicas da B3."""
+
+from pyield.b3 import boletim as boletim
+
+__all__ = [
+    "boletim",
+]

{pyield-0.49.1 → pyield-0.49.2}/pyield/b3/boletim.py

@@ -1,38 +1,38 @@
-"""
-Exemplo de trecho do XML bruto da B3:
+"""Boletim de Negociação da B3.
+
+Este módulo expõe helpers técnicos para buscar e ler o Price Report da B3.
+As funções preservam o schema bruto da fonte e servem como base para
+camadas públicas enriquecidas, como ``futuro`` e ``selic.cpm``.
+
+Estrutura resumida de um registro do XML bruto da B3::
+
     <PricRpt>
-        <TradDt>
-            <Dt>2026-04-01</Dt>
-        </TradDt>
-        <SctyId>
-            <TckrSymb>DI1F31</TckrSymb>
-        </SctyId>
+        <TradDt><Dt>2026-04-01</Dt></TradDt>
+        <SctyId><TckrSymb>DI1F31</TckrSymb></SctyId>
         <FinInstrmId>
             <OthrId>
                 <Id>200000235664</Id>
-                <Tp>
-                    <Prtry>8</Prtry>
-                </Tp>
+                <Tp><Prtry>8</Prtry></Tp>
             </OthrId>
-            <PlcOfListg>
-                <MktIdrCd>BVMF</MktIdrCd>
-            </PlcOfListg>
+            <PlcOfListg><MktIdrCd>BVMF</MktIdrCd></PlcOfListg>
         </FinInstrmId>
-        <TradDtls>
-            <TradQty>29880</TradQty>
-        </TradDtls>
+        <TradDtls><TradQty>29880</TradQty></TradDtls>
         <FinInstrmAttrbts>
             <MktDataStrmId>E</MktDataStrmId>
             ...
             <MinTradLmt Ccy="BRL">12.87</MinTradLmt>
         </FinInstrmAttrbts>
     </PricRpt>
+
+Ref: https://www.b3.com.br/data/files/16/70/29/9C/6219D710C8F297D7AC094EA8/Catalogo_precos_v1.3.pdf
 """
 
 import datetime as dt
 import io
+import logging
 import re
 import zipfile
+from pathlib import Path
 
 import polars as pl
 import requests
@@ -45,17 +45,15 @@ from pyield._internal.types import DateLike, any_is_empty
 from pyield.b3._contratos import normalizar_contratos
 from pyield.b3._validar_pregao import data_negociacao_valida
 
-# --- 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
-XPATH_PRICE_REPORT = "//ns:PricRpt"
+__all__ = [
+    "baixar_zip",
+    "buscar",
+    "ler",
+]
 
 # --- 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
 COLUNAS_PRICE_REPORT: list[tuple[str, str, type[pl.DataType]]] = [
     ("1.00", "TradDt", pl.Date),
     ("2.01", "TckrSymb", pl.String),
@@ -101,7 +99,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}
 
-
+logger = logging.getLogger(__name__)
 _SESSAO = requests.Session()
 _SESSAO.headers["User-Agent"] = (
     "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
@@ -111,24 +109,76 @@ _SESSAO.headers["User-Agent"] = (
 
 @ttl_cache()
 @retry_padrao
-def _baixar_zip_url(data: dt.date, boletim_completo: bool) -> bytes:
+def baixar_zip(data: DateLike, boletim_completo: bool = False) -> bytes:
+    """Baixa o ZIP bruto do Boletim de Negociação da B3.
+
+    Faz o download do Price Report da B3, no formato completo (PR) ou no
+    simplified price report (SPR), e retorna apenas ZIPs estruturalmente
+    válidos para persistência como dado bruto.
+
+    Args:
+        data: Data de negociação no formato 'DD-MM-YYYY', 'DD/MM/YYYY',
+            'YYYY-MM-DD' ou objeto datetime.date.
+        boletim_completo: Se False (padrão), usa o simplified price report
+            (SPR). Se True, usa o price report completo (PR).
+
+    Returns:
+        Conteúdo do ZIP externo em bytes quando o ZIP contém um XML legível.
+        Retorna ``b""`` quando a resposta não contém um ZIP válido.
+    """
+    if any_is_empty(data):
+        return bytes()
+
+    data = cv.converter_datas(data)
     data_str = data.strftime("%y%m%d")
-    if boletim_completo:
-        url = f"https://www.b3.com.br/pesquisapregao/download?filelist=PR{data_str}.zip"
-    else:
-        url = (
-            f"https://www.b3.com.br/pesquisapregao/download?filelist=SPRD{data_str}.zip"
-        )
+    prefixo = "PR" if boletim_completo else "SPRD"
+    url = f"https://www.b3.com.br/pesquisapregao/download?filelist={prefixo}{data_str}.zip"
 
     resposta = _SESSAO.get(url, timeout=(5, 10))
     resposta.raise_for_status()
 
-    if len(resposta.content) < MIN_TAMANHO_ZIP_BYTES:
+    if not _zip_valido(resposta.content):
         return bytes()
     return resposta.content
 
 
-def boletim_negociacao_extrair(conteudo_zip: bytes) -> bytes:
+def _zip_valido(conteudo_zip: bytes) -> bool:  # noqa: PLR0911
+    """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:
+        logger.debug("ZIP do boletim ignorado: tamanho menor que o mínimo.")
+        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
+
+    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.
 
     O ZIP da B3 contém um ZIP interno, que por sua vez contém um ou
@@ -201,6 +251,7 @@ def _extrair_dados_contrato(pric_rpt: etree._Element) -> dict | None:
 
 
 def _parsear_xml_registros(xml_bytes: bytes) -> list[dict]:
+    namespaces = {"ns": "urn:bvmf.217.01.xsd"}
     analisador = etree.XMLParser(
         ns_clean=True,
         remove_blank_text=True,
@@ -211,7 +262,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(XPATH_PRICE_REPORT, namespaces=NAMESPACES)
+    resultado = arvore.xpath("//ns:PricRpt", namespaces=namespaces)
     elementos: list[etree._Element] = resultado  # type: ignore[assignment]
     registros = [
         dados
@@ -251,25 +302,26 @@ def _filtrar_df(
     return df.sort("TckrSymb")
 
 
-def _obter_df_boletim_negociacao(data: dt.date, boletim_completo: bool) -> pl.DataFrame:
-    dados_zip = _baixar_zip_url(data, boletim_completo)
+def _obter_df_boletim(data: dt.date, boletim_completo: bool) -> pl.DataFrame:
+    dados_zip = baixar_zip(data, boletim_completo)
     if not dados_zip:
         return pl.DataFrame()
-    xml_bytes = boletim_negociacao_extrair(dados_zip)
+    xml_bytes = _extrair(dados_zip)
     return _processar_xml_extraido(xml_bytes)
 
 
-def boletim_negociacao(
+def buscar(
     data: DateLike,
     prefixo_ticker: str | list[str] | None = None,
     comprimento_ticker: int | None = None,
     boletim_completo: bool = False,
 ) -> pl.DataFrame:
-    """Busca e processa o Boletim de Negociacao da B3 no site oficial.
+    """Busca e processa o Boletim de Negociação da B3 no site oficial.
 
-    Faz o download do ZIP com XML, extrai os dados do contrato e devolve um
-    DataFrame Polars com os dados brutos do XML e colunas no padrão
-    original da B3 (nomes em inglês das tags XML).
+    Faz o download do Price Report da B3, no formato completo (PR) ou no
+    simplified price report (SPR), extrai o XML do ZIP publicado em
+    ``pesquisapregao`` e devolve um DataFrame Polars com dados brutos e
+    colunas no padrão original da B3 (nomes em inglês das tags XML).
 
     O DataFrame retornado **não** contém colunas calculadas
     (dias_uteis, dias_corridos, dv01, taxa_forward)
@@ -353,14 +405,14 @@ def boletim_negociacao(
         etree.XMLSyntaxError: Se o XML recebido estiver malformado.
 
     Examples:
-        >>> from pyield.b3.boletim import boletim_negociacao
-        >>> df = boletim_negociacao("26-04-2024", "DI1")
+        >>> import pyield as yd
+        >>> df = yd.b3.boletim.buscar("26-04-2024", "DI1")
 
         >>> # Múltiplos contratos de uma vez
-        >>> df = boletim_negociacao("26-04-2024", ["DI1", "DAP"])
+        >>> df = yd.b3.boletim.buscar("26-04-2024", ["DI1", "DAP"])
 
         >>> # Feriado ou fim de semana (retorna DataFrame vazio)
-        >>> df = boletim_negociacao("25-12-2023", "DI1")  # Véspera de Natal
+        >>> df = yd.b3.boletim.buscar("25-12-2023", "DI1")
         >>> df.is_empty()
         True
     """
@@ -372,7 +424,7 @@ def boletim_negociacao(
     if not data_negociacao_valida(data):
         return pl.DataFrame()
 
-    df = _obter_df_boletim_negociacao(data, boletim_completo)
+    df = _obter_df_boletim(data, boletim_completo)
     if df.is_empty() or prefixo_ticker is None:
         return df
 
@@ -382,21 +434,23 @@ def boletim_negociacao(
     return _filtrar_df(df, prefixos, comprimento_ticker)
 
 
-def boletim_negociacao_ler(
-    xml_bytes: bytes,
+def ler(
+    fonte: bytes | Path,
     prefixo_ticker: str | list[str] | None = None,
     comprimento_ticker: int | None = None,
 ) -> pl.DataFrame:
-    """Lê e processa o price report da B3 a partir do conteúdo XML bruto.
+    """Lê e processa o price report da B3 a partir do dado bruto.
 
-    Mesma saída de :func:`boletim_negociacao`, mas recebe o XML já
-    descomprimido em vez de baixar da rede.
+    Mesma saída de :func:`buscar`, mas recebe o dado bruto em vez de
+    baixar da rede. Aceita o ZIP externo como ``bytes`` ou ``Path``
+    (caminho para o arquivo ZIP), e também XML descomprimido como ``bytes``.
 
-    Por operar diretamente sobre o XML bruto, esta função preserva a
+    Por operar diretamente sobre o dado bruto, esta função preserva a
     terminologia da fonte para filtros de `TckrSymb`.
 
     Args:
-        xml_bytes: Conteúdo do XML em bytes (já descomprimido).
+        fonte: ZIP externo em bytes, caminho (``Path``) para um arquivo ZIP
+            no disco, ou XML já descomprimido em bytes.
         prefixo_ticker: 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.
@@ -406,11 +460,15 @@ def boletim_negociacao_ler(
 
     Returns:
         pl.DataFrame: DataFrame com as mesmas colunas documentadas em
-        :func:`boletim_negociacao`.
+        :func:`buscar`.
     """
-    if any_is_empty(xml_bytes):
+    conteudo = fonte.read_bytes() if isinstance(fonte, Path) else fonte
+
+    if any_is_empty(conteudo):
         return pl.DataFrame()
 
+    xml_bytes = _extrair(conteudo) if conteudo[:4] == b"PK\x03\x04" else conteudo
+
     df = _processar_xml_extraido(xml_bytes)
     if df.is_empty() or prefixo_ticker is None:
         return df

{pyield-0.49.1 → pyield-0.49.2}/pyield/selic/cpm.py

@@ -41,7 +41,7 @@ import pyield._internal.converters as cv
 from pyield import du
 from pyield._internal.retry import retry_padrao
 from pyield._internal.types import DateLike
-from pyield.b3.boletim import boletim_negociacao
+from pyield.b3 import boletim
 
 logger = logging.getLogger(__name__)
 
@@ -271,7 +271,7 @@ def data(date: DateLike) -> pl.DataFrame:
         return _empty_schema()
 
     try:
-        df = boletim_negociacao(trade_date, prefixo_ticker="CPM")
+        df = boletim.buscar(trade_date, prefixo_ticker="CPM")
     except Exception:
         logger.exception("CPM: falha ao baixar SPR para %s.", trade_date)
         return _empty_schema()

{pyield-0.49.1 → pyield-0.49.2}/pyproject.toml

@@ -18,7 +18,7 @@ dependencies = [
     "requests>=2.31.0",    
     "fastexcel>=0.19.0",
 ]
-version = "0.49.1"
+version = "0.49.2"
 
 [project.urls]
 Homepage = "https://github.com/crdcj/PYield"

pyield-0.49.1/pyield/b3/__init__.py

@@ -1 +0,0 @@
-