pyield 0.52.2__tar.gz → 0.53.1__tar.gz

{pyield-0.52.2 → pyield-0.53.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: pyield
-Version: 0.52.2
+Version: 0.53.1
 Summary: Polars-powered toolkit for Brazilian fixed income analysis
 Keywords: fixed-income,brazil,finance,analysis,bonds
 Author: Carlos Carvalho
@@ -113,7 +113,7 @@ documentação.
 | `yd.forwards(...)` | função | Curva de taxas a termo |  |
 | `yd.futuro` | módulo | Contratos futuros da B3 | `di1`, `historico`, `intradia`, `datas_disponiveis`, `vencimento`, `enriquecer`, `vencimento_expr` |
 | `yd.di1` | módulo | Curva DI1 e interpolação | `dados`, `interpolar_taxas`, `interpolar_taxa`, `datas_disponiveis` |
-| `yd.tpf` | módulo | Títulos públicos federais | `taxas`, `vencimentos`, `estoque`, `leiloes`, `benchmarks`, `curva_pre`, `premio_pre`, `rmd`, `secundario_mensal`, `secundario_intradia` |
+| `yd.tpf` | módulo | Títulos públicos federais | `taxas`, `vencimentos`, `estoque`, `leiloes`, `benchmarks`, `curva_pre`, `premio_pre`, `rmd`, `secundario` |
 | `yd.lft` | módulo | LFT | `dados`, `vencimentos`, `cotacao`, `pu`, `taxa`, `vna`, `rentabilidade`, `rentabilidade_expr` |
 | `yd.ltn` | módulo | LTN | `dados`, `vencimentos`, `pu`, `taxa`, `duration_expr`, `dv01`, `dv01_expr`, `rentabilidade`, `rentabilidade_expr`, `taxas_forward` |
 | `yd.ntnb` | módulo | NTN-B | `dados`, `vencimentos`, `datas_pagamento`, `fluxos_caixa`, `cotacao`, `pu`, `taxa`, `taxas_zero`, `duration`, `duration_expr`, `dv01`, `dv01_expr`, `implicitas`, `curva` |
@@ -305,7 +305,7 @@ fonte indisponível) retornam DataFrame vazio ou `nan`, sem lançar exceção:
 import pyield as yd
 
 yd.futuro.historico("01-01-2030", "DI1").is_empty()  # -> True
-yd.tpf.secundario_mensal("01-01-2030").is_empty()    # -> True
+yd.tpf.secundario.mensal("01-01-2030").is_empty()    # -> True
 yd.ptax("25-12-2025")                                # -> nan
 ```
 

{pyield-0.52.2 → pyield-0.53.1}/README.md

@@ -69,7 +69,7 @@ documentação.
 | `yd.forwards(...)` | função | Curva de taxas a termo |  |
 | `yd.futuro` | módulo | Contratos futuros da B3 | `di1`, `historico`, `intradia`, `datas_disponiveis`, `vencimento`, `enriquecer`, `vencimento_expr` |
 | `yd.di1` | módulo | Curva DI1 e interpolação | `dados`, `interpolar_taxas`, `interpolar_taxa`, `datas_disponiveis` |
-| `yd.tpf` | módulo | Títulos públicos federais | `taxas`, `vencimentos`, `estoque`, `leiloes`, `benchmarks`, `curva_pre`, `premio_pre`, `rmd`, `secundario_mensal`, `secundario_intradia` |
+| `yd.tpf` | módulo | Títulos públicos federais | `taxas`, `vencimentos`, `estoque`, `leiloes`, `benchmarks`, `curva_pre`, `premio_pre`, `rmd`, `secundario` |
 | `yd.lft` | módulo | LFT | `dados`, `vencimentos`, `cotacao`, `pu`, `taxa`, `vna`, `rentabilidade`, `rentabilidade_expr` |
 | `yd.ltn` | módulo | LTN | `dados`, `vencimentos`, `pu`, `taxa`, `duration_expr`, `dv01`, `dv01_expr`, `rentabilidade`, `rentabilidade_expr`, `taxas_forward` |
 | `yd.ntnb` | módulo | NTN-B | `dados`, `vencimentos`, `datas_pagamento`, `fluxos_caixa`, `cotacao`, `pu`, `taxa`, `taxas_zero`, `duration`, `duration_expr`, `dv01`, `dv01_expr`, `implicitas`, `curva` |
@@ -261,7 +261,7 @@ fonte indisponível) retornam DataFrame vazio ou `nan`, sem lançar exceção:
 import pyield as yd
 
 yd.futuro.historico("01-01-2030", "DI1").is_empty()  # -> True
-yd.tpf.secundario_mensal("01-01-2030").is_empty()    # -> True
+yd.tpf.secundario.mensal("01-01-2030").is_empty()    # -> True
 yd.ptax("25-12-2025")                                # -> nan
 ```
 

{pyield-0.52.2 → pyield-0.53.1}/pyield/_internal/converters.py

@@ -52,14 +52,15 @@ def converter_datas_expr(expr: pl.Expr | str) -> pl.Expr:
         expr = pl.col(expr)
 
     # Fallback por linha: o primeiro valor não-nulo vence.
-    # Se o elemento já for Date, o cast resolve no 1o termo.
+    # Datas e datetimes Python chegam ao Polars como strings ISO.
     # Se o elemento for null, ele permanece null em todos os termos.
     expr_str = expr.cast(pl.String, strict=False).str.strip_chars()
     return pl.coalesce(
-        expr.cast(pl.Date, strict=False),
         expr_str.str.to_date(format="%d-%m-%Y", strict=False),
         expr_str.str.to_date(format="%d/%m/%Y", strict=False),
         expr_str.str.to_date(format="%Y-%m-%d", strict=False),
+        expr_str.str.to_date(format="%Y-%m-%d %H:%M:%S", strict=False),
+        expr_str.str.to_date(format="%Y-%m-%d %H:%M:%S%.f", strict=False),
     )
 
 

{pyield-0.52.2 → pyield-0.53.1}/pyield/b3/boletim.py

@@ -298,6 +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)
+    df = df.with_columns(TradDt=pl.col("TradDt").str.to_date("%Y-%m-%d"))
     return df.cast(SCHEMA_PRICE_REPORT, strict=False)
 
 

{pyield-0.52.2 → pyield-0.53.1}/pyield/b3/derivativos_intradia.py

@@ -103,8 +103,15 @@ def _converter_json_intradia(dados_json: list[dict]) -> pl.DataFrame:
 def _processar_colunas_intradia(df: pl.DataFrame) -> pl.DataFrame:
     colunas_disponiveis = [col for col in MAPEAMENTO if col in df.columns]
     tipos_disponiveis = pl.Schema({col: TIPOS[col] for col in colunas_disponiveis})
+    coluna_vencimento = "asset.AsstSummry.mtrtyCode"
+    exprs_data = []
+    if coluna_vencimento in colunas_disponiveis:
+        exprs_data.append(
+            pl.col(coluna_vencimento).str.to_date("%Y-%m-%d", strict=False)
+        )
     return (
         df.select(colunas_disponiveis)
+        .with_columns(exprs_data)
         .cast(tipos_disponiveis, strict=False)
         .rename(MAPEAMENTO, strict=False)
     )

{pyield-0.52.2 → pyield-0.53.1}/pyield/tpf/__init__.py

@@ -2,8 +2,7 @@
 
 from pyield.anbima.imaq import estoque
 from pyield.anbima.mercado_secundario import TipoTPF, taxas, vencimentos
-from pyield.bc.tpf_intradia import secundario_intradia
-from pyield.bc.tpf_mensal import secundario_mensal
+from pyield.tpf import secundario
 from pyield.tpf._titulos import lft, ltn, ntnb, ntnb1, ntnbprinc, ntnc, ntnf
 from pyield.tpf.benchmark import benchmarks
 from pyield.tpf.leiloes import leiloes
@@ -26,8 +25,7 @@ __all__ = [
     "ntnf",
     "premio_pre",
     "rmd",
-    "secundario_intradia",
-    "secundario_mensal",
+    "secundario",
     "taxas",
     "vencimentos",
 ]

pyield-0.53.1/pyield/tpf/secundario/__init__.py

@@ -0,0 +1,19 @@
+"""Negociações do mercado secundário de TPFs no sistema Selic do BCB."""
+
+from pyield.tpf.secundario._intradia import intradia as intradia
+from pyield.tpf.secundario._mensal import baixar_zip as baixar_zip
+from pyield.tpf.secundario._mensal import ler_zip as ler_zip
+from pyield.tpf.secundario._mensal import mensal as mensal
+from pyield.tpf.secundario._mensal import (
+    nome_arquivo_mensal as nome_arquivo_mensal,
+)
+from pyield.tpf.secundario._mensal import zip_para_silver as zip_para_silver
+
+__all__ = [
+    "baixar_zip",
+    "intradia",
+    "ler_zip",
+    "mensal",
+    "nome_arquivo_mensal",
+    "zip_para_silver",
+]

pyield-0.52.2/pyield/bc/tpf_intradia.py → pyield-0.53.1/pyield/tpf/secundario/_intradia.py

@@ -1,7 +1,4 @@
-"""
-Busca dados intradiários de negociações secundárias da dívida pública federal.
-https://www.bcb.gov.br/htms/selic/selicprecos.asp?frame=1
-"""
+"""Dados intradia do mercado secundário de TPFs no sistema Selic do BCB."""
 
 import datetime as dt
 
@@ -13,30 +10,26 @@ from pyield._internal.br_numbers import float_br, inteiro_br, taxa_br
 from pyield._internal.cache import ttl_cache
 from pyield._internal.retry import retry_padrao
 
-HORA_INICIO_TEMPO_REAL = dt.time(9, 0, 0)
-HORA_FIM_TEMPO_REAL = dt.time(22, 0, 0)
 URL_BASE_TEMPO_REAL = (
     "https://www3.bcb.gov.br/novoselic/rest/precosNegociacao/pub/download/estatisticas/"
 )
 
+HORA_INICIO_TEMPO_REAL = dt.time(9, 0, 0)
+HORA_FIM_TEMPO_REAL = dt.time(22, 0, 0)
+
 
 @ttl_cache()
 @retry_padrao
-def _buscar_csv() -> bytes:
-    """
-    Exemplo de URL do CSV com dados intradiários:
-        https://www3.bcb.gov.br/novoselic/rest/precosNegociacao/pub/download/estatisticas/02-06-2025
-    """
+def _buscar_csv_intradia() -> bytes:
     hoje = relogio.hoje()
     data_formatada = hoje.strftime("%d-%m-%Y")
     url = f"{URL_BASE_TEMPO_REAL}{data_formatada}"
-    r = requests.get(url, timeout=30)  # API costuma levar ~10s
-    r.raise_for_status()
-    return r.content
+    resposta = requests.get(url, timeout=30)  # API costuma levar ~10s
+    resposta.raise_for_status()
+    return resposta.content
 
 
-def _parsear_df(dados: bytes) -> pl.DataFrame:
-    """Lê CSV como strings."""
+def _parsear_csv_intradia(dados: bytes) -> pl.DataFrame:
     return pl.read_csv(
         dados,
         separator=";",
@@ -45,8 +38,7 @@ def _parsear_df(dados: bytes) -> pl.DataFrame:
     ).rename(lambda c: c.strip())
 
 
-def _processar_df(df: pl.DataFrame) -> pl.DataFrame:
-    """Filtra registros, converte tipos e reordena colunas."""
+def _processar_df_intradia(df: pl.DataFrame) -> pl.DataFrame:
     agora = relogio.agora()
     return df.filter(pl.col("//1") == "1").select(
         data_hora_consulta=agora,
@@ -84,7 +76,6 @@ def _processar_df(df: pl.DataFrame) -> pl.DataFrame:
 
 
 def _mercado_selic_aberto() -> bool:
-    """Verifica se o mercado SELIC está aberto no momento."""
     agora = relogio.agora()
     hoje = agora.date()
     hora = agora.time()
@@ -94,7 +85,7 @@ def _mercado_selic_aberto() -> bool:
     return eh_dia_util and eh_horario
 
 
-def secundario_intradia() -> pl.DataFrame:
+def intradia() -> pl.DataFrame:
     """Busca dados intradia do mercado secundário de TPFs.
 
     Fonte: Banco Central do Brasil, sistema SELIC. Os dados ficam disponíveis
@@ -138,11 +129,11 @@ def secundario_intradia() -> pl.DataFrame:
         * termo_quantidade_corretagem (Int64): títulos a termo via corretagem.
 
     Examples:
-        >>> df = yd.tpf.secundario_intradia()  # doctest: +SKIP
+        >>> df = yd.tpf.secundario.intradia()  # doctest: +SKIP
     """
     if not _mercado_selic_aberto():
         return pl.DataFrame()
 
-    texto_bruto = _buscar_csv()
-    df = _parsear_df(texto_bruto)
-    return _processar_df(df)
+    texto_bruto = _buscar_csv_intradia()
+    df = _parsear_csv_intradia(texto_bruto)
+    return _processar_df_intradia(df)

pyield-0.53.1/pyield/tpf/secundario/_mensal.py

@@ -0,0 +1,310 @@
+"""Dados mensais do mercado secundário de TPFs no sistema Selic do BCB."""
+
+import datetime as dt
+import io
+import os
+import zipfile as zf
+from pathlib import Path
+
+import polars as pl
+import polars.selectors as ps
+import requests
+
+from pyield import relogio
+from pyield._internal.br_numbers import float_br
+from pyield._internal.cache import ttl_cache
+from pyield._internal.converters import converter_datas
+from pyield._internal.retry import retry_padrao
+from pyield._internal.types import DateLike, any_is_empty
+
+URL_BASE_MENSAL = "https://www4.bcb.gov.br/pom/demab/negociacoes/download"
+CHAVES_ORDENACAO = ["data_liquidacao", "titulo", "data_vencimento"]
+COLUNAS_MINIMAS_CSV = 2
+
+type CaminhoArquivo = str | os.PathLike[str]
+
+
+def _tipo_arquivo(extragrupo: bool) -> str:
+    return "E" if extragrupo else "T"
+
+
+def _data_mensal(data: DateLike) -> dt.date:
+    data_alvo = converter_datas(data)
+    if not isinstance(data_alvo, dt.date):
+        msg = "data deve ser escalar para consultas mensais do secundário de TPFs"
+        raise ValueError(msg)
+    return data_alvo
+
+
+def nome_arquivo_mensal(data: DateLike, extragrupo: bool = False) -> str:
+    """Retorna o nome do arquivo ZIP mensal do secundário no BCB/SELIC.
+
+    Args:
+        data: Data de referência. Apenas ano e mês definem o arquivo.
+        extragrupo: Se verdadeiro, retorna o nome do arquivo extragrupo.
+
+    Returns:
+        Nome do arquivo ZIP mensal publicado pelo BCB.
+
+    Examples:
+        >>> yd.tpf.secundario.nome_arquivo_mensal("07-06-2026")
+        'NegT202606.ZIP'
+        >>> yd.tpf.secundario.nome_arquivo_mensal("07-01-2025", extragrupo=True)
+        'NegE202501.ZIP'
+    """
+    data_alvo = _data_mensal(data)
+    return f"Neg{_tipo_arquivo(extragrupo)}{data_alvo:%Y%m}.ZIP"
+
+
+@ttl_cache()
+@retry_padrao
+def _baixar_url_zip(url_arquivo: str) -> bytes:
+    resposta = requests.get(url_arquivo, allow_redirects=True, timeout=60)
+    resposta.raise_for_status()
+    return resposta.content
+
+
+def baixar_zip(data: DateLike, extragrupo: bool = False) -> bytes:
+    """Baixa o ZIP bruto mensal de negociações secundárias de TPFs.
+
+    Fonte: Banco Central do Brasil, sistema SELIC. A fonte publica um arquivo
+    por mês; por isso, apenas o ano e o mês de ``data`` são usados.
+
+    A função valida a estrutura mínima do ZIP antes de retornar os bytes, para
+    evitar que pipelines de ingestão salvem bronze vazio, corrompido ou sem CSV
+    plausível.
+
+    Args:
+        data: Data de referência. Apenas ano e mês definem o arquivo.
+        extragrupo: Se verdadeiro, baixa o arquivo extragrupo.
+
+    Returns:
+        Bytes validados do arquivo ZIP mensal publicado pelo BCB.
+
+    Raises:
+        requests.HTTPError: Se o arquivo não estiver disponível no BCB ou a
+            resposta HTTP indicar erro.
+        ValueError: Se o conteúdo baixado não for um ZIP bruto plausível.
+
+    Examples:
+        >>> conteudo = yd.tpf.secundario.baixar_zip("07-01-2025")  # doctest: +SKIP
+    """
+    arquivo = nome_arquivo_mensal(data, extragrupo)
+    conteudo_zip = _baixar_url_zip(f"{URL_BASE_MENSAL}/{arquivo}")
+    _validar_zip(conteudo_zip, arquivo)
+    return conteudo_zip
+
+
+def _extrair_csv_zip(conteudo_zip: bytes) -> bytes:
+    try:
+        arquivo_zip = zf.ZipFile(io.BytesIO(conteudo_zip), "r")
+    except zf.BadZipFile as exc:
+        msg = "ZIP inválido ou ilegível"
+        raise ValueError(msg) from exc
+
+    with arquivo_zip:
+        nomes = arquivo_zip.namelist()
+        if not nomes:
+            raise ValueError("ZIP vazio")
+
+        arquivo_corrompido = arquivo_zip.testzip()
+        if arquivo_corrompido is not None:
+            msg = f"ZIP contém arquivo corrompido: {arquivo_corrompido}"
+            raise ValueError(msg)
+
+        return arquivo_zip.read(nomes[0])
+
+
+def _validar_zip(conteudo_zip: bytes, nome: str | None = None) -> None:
+    rotulo = f"{nome}: " if nome else ""
+    try:
+        conteudo_csv = _extrair_csv_zip(conteudo_zip)
+    except ValueError as exc:
+        msg = f"{rotulo}{exc}"
+        raise ValueError(msg) from exc
+
+    df_amostra = pl.read_csv(
+        conteudo_csv,
+        encoding="latin1",
+        separator=";",
+        infer_schema=False,
+        null_values="",
+        n_rows=1,
+    )
+
+    if len(df_amostra.columns) < COLUNAS_MINIMAS_CSV:
+        msg = f"{rotulo}CSV não parece estar separado por ponto e vírgula"
+        raise ValueError(msg)
+
+
+def _parsear_csv_mensal(conteudo_csv: bytes) -> pl.DataFrame:
+    return pl.read_csv(
+        conteudo_csv,
+        encoding="latin1",
+        separator=";",
+        infer_schema=False,
+        null_values="",
+    )
+
+
+def _processar_df_mensal(df: pl.DataFrame) -> pl.DataFrame:
+    operacoes_corretagem = (
+        pl.col("NUM OPER COM CORRETAGEM").cast(pl.Int64)
+        if "NUM OPER COM CORRETAGEM" in df.columns
+        else pl.lit(None, dtype=pl.Int64)
+    )
+    quantidade_corretagem = (
+        pl.col("QUANT NEG COM CORRETAGEM").cast(pl.Int64)
+        if "QUANT NEG COM CORRETAGEM" in df.columns
+        else pl.lit(None, dtype=pl.Int64)
+    )
+
+    return (
+        df.with_columns(ps.string().str.strip_chars())
+        .with_columns(
+            quantidade=pl.col("QUANT NEGOCIADA").cast(pl.Int64),
+            pu_medio=float_br("PU MED"),
+        )
+        .select(
+            data_liquidacao=pl.col("DATA MOV").str.to_date("%d/%m/%Y", strict=False),
+            titulo=pl.col("SIGLA"),
+            codigo_selic=pl.col("CODIGO").cast(pl.Int64),
+            isin=pl.col("CODIGO ISIN"),
+            data_emissao=pl.col("EMISSAO").str.to_date("%d/%m/%Y", strict=False),
+            data_vencimento=pl.col("VENCIMENTO").str.to_date("%d/%m/%Y", strict=False),
+            operacoes=pl.col("NUM DE OPER").cast(pl.Int64),
+            quantidade=pl.col("quantidade"),
+            pu_minimo=float_br("PU MIN"),
+            pu_medio=pl.col("pu_medio"),
+            pu_maximo=float_br("PU MAX"),
+            pu_lastro=float_br("PU LASTRO"),
+            valor_par=float_br("VALOR PAR"),
+            taxa_minima=float_br("TAXA MIN"),
+            taxa_media=float_br("TAXA MED"),
+            taxa_maxima=float_br("TAXA MAX"),
+            operacoes_corretagem=operacoes_corretagem,
+            quantidade_corretagem=quantidade_corretagem,
+        )
+        .sort(CHAVES_ORDENACAO)
+    )
+
+
+def zip_para_silver(conteudo_zip: bytes) -> pl.DataFrame:
+    """Converte o ZIP mensal bruto do secundário de TPFs em silver.
+
+    Fonte: Banco Central do Brasil, sistema SELIC. Esta função representa a
+    etapa bronze -> silver: extrai o CSV interno, limpa os campos, converte
+    tipos e retorna o schema Polars canônico usado pela PYield. Ela não faz
+    enriquecimento para camada ouro.
+
+    Args:
+        conteudo_zip: Bytes do arquivo ZIP bruto mensal.
+
+    Returns:
+        DataFrame Polars com dados mensais do mercado secundário.
+
+    Output Columns:
+        * data_liquidacao (Date): data de liquidação da negociação.
+        * titulo (String): sigla do título público.
+        * codigo_selic (Int64): código único no sistema SELIC.
+        * isin (String): código ISIN.
+        * data_emissao (Date): data de emissão do título.
+        * data_vencimento (Date): data de vencimento do título.
+        * operacoes (Int64): número total de operações.
+        * quantidade (Int64): quantidade total negociada.
+        * pu_minimo (Float64): preço unitário mínimo.
+        * pu_medio (Float64): preço unitário médio.
+        * pu_maximo (Float64): preço unitário máximo.
+        * pu_lastro (Float64): preço unitário de lastro.
+        * valor_par (Float64): valor par do título.
+        * taxa_minima (Float64): taxa mínima.
+        * taxa_media (Float64): taxa média.
+        * taxa_maxima (Float64): taxa máxima.
+        * operacoes_corretagem (Int64): operações com corretagem.
+        * quantidade_corretagem (Int64): quantidade com corretagem.
+
+    Notes:
+        O schema silver é estável para concatenação entre meses. Em layouts
+        antigos da fonte que não trazem corretagem, ``operacoes_corretagem`` e
+        ``quantidade_corretagem`` são retornadas como nulas.
+
+    Examples:
+        >>> conteudo = yd.tpf.secundario.baixar_zip("07-01-2025")  # doctest: +SKIP
+        >>> df = yd.tpf.secundario.zip_para_silver(conteudo)  # doctest: +SKIP
+    """
+    conteudo_csv = _extrair_csv_zip(conteudo_zip)
+    return _processar_df_mensal(_parsear_csv_mensal(conteudo_csv))
+
+
+def ler_zip(caminho: CaminhoArquivo) -> pl.DataFrame:
+    """Lê um ZIP mensal local do secundário de TPFs e converte para silver.
+
+    Fonte: Banco Central do Brasil, sistema SELIC. Esta função é um atalho para
+    pipelines que salvam o bronze bruto e depois processam o arquivo local com o
+    mesmo schema de ``zip_para_silver``.
+
+    Args:
+        caminho: Caminho do arquivo ZIP bruto.
+
+    Returns:
+        DataFrame Polars com dados mensais do mercado secundário.
+
+    Examples:
+        >>> df = yd.tpf.secundario.ler_zip("NegT202501.ZIP")  # doctest: +SKIP
+    """
+    return zip_para_silver(Path(caminho).read_bytes())
+
+
+def mensal(data: DateLike, extragrupo: bool = False) -> pl.DataFrame:
+    """Busca dados mensais do mercado secundário de TPFs.
+
+    Fonte: Banco Central do Brasil, sistema SELIC. Baixa o ZIP mensal de
+    negociações secundárias, valida o bronze bruto e retorna o DataFrame ouro.
+    Apenas o ano e o mês de ``data`` são usados para identificar o arquivo.
+
+    Args:
+        data: Data de referência. Apenas ano e mês definem o arquivo.
+        extragrupo: Se verdadeiro, busca apenas negociações extragrupo.
+
+    Returns:
+        DataFrame Polars com dados mensais do mercado secundário.
+
+    Output Columns:
+        * data_liquidacao (Date): data de liquidação da negociação.
+        * titulo (String): sigla do título público.
+        * codigo_selic (Int64): código único no sistema SELIC.
+        * isin (String): código ISIN.
+        * data_emissao (Date): data de emissão do título.
+        * data_vencimento (Date): data de vencimento do título.
+        * operacoes (Int64): número total de operações.
+        * quantidade (Int64): quantidade total negociada.
+        * pu_minimo (Float64): preço unitário mínimo.
+        * pu_medio (Float64): preço unitário médio.
+        * pu_maximo (Float64): preço unitário máximo.
+        * pu_lastro (Float64): preço unitário de lastro.
+        * valor_par (Float64): valor par do título.
+        * taxa_minima (Float64): taxa mínima.
+        * taxa_media (Float64): taxa média.
+        * taxa_maxima (Float64): taxa máxima.
+        * operacoes_corretagem (Int64): operações com corretagem.
+        * quantidade_corretagem (Int64): quantidade com corretagem.
+        * financeiro (Float64): valor financeiro negociado.
+
+    Notes:
+        Esta é a camada ouro mensal: retorna o schema de ``zip_para_silver``
+        acrescido de ``financeiro = quantidade * pu_medio``.
+
+    Examples:
+        >>> df = yd.tpf.secundario.mensal("07-01-2025", extragrupo=True)
+    """
+    if any_is_empty(data):
+        return pl.DataFrame()
+
+    data_alvo = _data_mensal(data)
+    hoje = relogio.hoje()
+    if (data_alvo.year, data_alvo.month) > (hoje.year, hoje.month):
+        return pl.DataFrame()
+
+    return zip_para_silver(baixar_zip(data_alvo, extragrupo)).with_columns(
+        financeiro=(pl.col("quantidade") * pl.col("pu_medio")).round(2),
+    )

{pyield-0.52.2 → pyield-0.53.1}/pyproject.toml

@@ -19,7 +19,7 @@ dependencies = [
     "fastexcel>=0.19.0",
     "tzdata>=2024.1; platform_system == 'Windows'",
 ]
-version = "0.52.2"
+version = "0.53.1"
 
 [project.urls]
 Homepage = "https://github.com/crdcj/PYield"
@@ -32,7 +32,6 @@ dev = [
     "python-dotenv[cli]",
     "ipykernel",
     "pytest",
-    "pyright",
     "ruff",
     "mkdocs",
     "mkdocs-material",

pyield-0.52.2/pyield/bc/tpf_mensal.py

@@ -1,146 +0,0 @@
-"""
-Módulo para buscar dados mensais de negociações secundárias da Dívida Pública
-Federal (TPF) registradas no sistema Selic do Banco Central do Brasil (BCB).
-Os dados são baixados em ZIP, extraídos e carregados em um DataFrame Polars.
-Exemplo do formato dos dados (3 primeiras linhas):
-DATA MOV  ; SIGLA; CODIGO; CODIGO ISIN ; EMISSAO   ; VENCIMENTO; NUM DE OPER; QUANT NEGOCIADA; VALOR NEGOCIADO; PU MIN        ; PU MED        ; PU MAX        ; PU LASTRO     ; VALOR PAR     ; TAXA MIN; TAXA MED; TAXA MAX; NUM OPER COM CORRETAGEM; QUANT NEG COM CORRETAGEM
-02/09/2024; LFT  ; 210100; BRSTNCLF1RC4; 26/10/2018; 01/03/2025;          48;          100221;                ; 15288,00898200; 15292,57098100; 15302,77742100; 15285,54813387; 15288,23830700; -0,1897 ; -0,0565 ; 0,0032  ;                      20;                    16155
-02/09/2024; LFT  ; 210100; BRSTNCLF1RD2; 08/03/2019; 01/09/2025;         101;          230120;                ; 15288,23830700; 15294,25937800; 15311,01778200; 15279,49187722; 15288,23830700; -0,1498 ; -0,0395 ; 0,0000  ;                      21;                    19059
-02/09/2024; LFT  ; 210100; BRSTNCLF1RE0; 06/09/2019; 01/03/2026;          88;          512642;                ; 15286,63304100; 15288,20025100; 15292,77891300; 15268,60295396; 15288,23830700; -0,0198 ; 0,0002  ; 0,0071  ;                      27;                   121742
-...
-"""
-
-import datetime as dt
-import io
-import zipfile as zf
-
-import polars as pl
-import polars.selectors as ps
-import requests
-
-from pyield._internal.br_numbers import float_br
-from pyield._internal.cache import ttl_cache
-from pyield._internal.converters import converter_datas
-from pyield._internal.retry import retry_padrao
-from pyield._internal.types import DateLike, any_is_empty
-from pyield.relogio import hoje
-
-URL_BASE = "https://www4.bcb.gov.br/pom/demab/negociacoes/download"
-
-CHAVES_ORDENACAO = ["data_liquidacao", "titulo", "data_vencimento"]
-
-
-def _montar_url(data_alvo: dt.date, extragrupo: bool) -> str:
-    ano_mes = data_alvo.strftime("%Y%m")
-    sufixo = "E" if extragrupo else "T"
-    return f"{URL_BASE}/Neg{sufixo}{ano_mes}.ZIP"
-
-
-@ttl_cache()
-@retry_padrao
-def _baixar_zip(url_arquivo: str) -> bytes:
-    """Baixa o conteúdo ZIP e retorna os bytes."""
-    resposta = requests.get(url_arquivo, timeout=10)
-    resposta.raise_for_status()
-    return resposta.content
-
-
-def _descompactar_zip(conteudo_zip: bytes) -> bytes:
-    """Descompacta o ZIP e retorna o conteúdo do primeiro arquivo."""
-    with zf.ZipFile(io.BytesIO(conteudo_zip), "r") as arquivo_zip:
-        return arquivo_zip.read(arquivo_zip.namelist()[0])
-
-
-def _parsear_df(conteudo_csv: bytes) -> pl.DataFrame:
-    """Lê o CSV extraído do ZIP em DataFrame com todas as colunas como string."""
-    return pl.read_csv(
-        conteudo_csv,
-        encoding="latin1",
-        separator=";",
-        infer_schema=False,
-        null_values="",
-    )
-
-
-def _processar_df(df: pl.DataFrame) -> pl.DataFrame:
-    return (
-        df.with_columns(ps.string().str.strip_chars())
-        .with_columns(
-            quantidade=pl.col("QUANT NEGOCIADA").cast(pl.Int64),
-            pu_medio=float_br("PU MED"),
-        )
-        .select(
-            data_liquidacao=pl.col("DATA MOV").str.to_date("%d/%m/%Y", strict=False),
-            titulo=pl.col("SIGLA"),
-            codigo_selic=pl.col("CODIGO").cast(pl.Int64),
-            isin=pl.col("CODIGO ISIN"),
-            data_emissao=pl.col("EMISSAO").str.to_date("%d/%m/%Y", strict=False),
-            data_vencimento=pl.col("VENCIMENTO").str.to_date("%d/%m/%Y", strict=False),
-            operacoes=pl.col("NUM DE OPER").cast(pl.Int64),
-            quantidade=pl.col("quantidade"),
-            financeiro=(pl.col("quantidade") * pl.col("pu_medio")).round(2),
-            pu_minimo=float_br("PU MIN"),
-            pu_medio=pl.col("pu_medio"),
-            pu_maximo=float_br("PU MAX"),
-            pu_lastro=float_br("PU LASTRO"),
-            valor_par=float_br("VALOR PAR"),
-            taxa_minima=float_br("TAXA MIN"),
-            taxa_media=float_br("TAXA MED"),
-            taxa_maxima=float_br("TAXA MAX"),
-            operacoes_corretagem=pl.col("NUM OPER COM CORRETAGEM").cast(pl.Int64),
-            quantidade_corretagem=pl.col("QUANT NEG COM CORRETAGEM").cast(pl.Int64),
-        )
-        .sort(CHAVES_ORDENACAO)
-    )
-
-
-def secundario_mensal(
-    data: DateLike,
-    extragrupo: bool = False,
-) -> pl.DataFrame:
-    """Busca dados mensais do mercado secundário de TPFs.
-
-    Fonte: Banco Central do Brasil, sistema SELIC. Baixa o arquivo mensal de
-    negociações secundárias para o mês correspondente à data informada.
-
-    Args:
-        data: Data de referência.
-        extragrupo: Se verdadeiro, busca apenas negociações extragrupo.
-
-    Returns:
-        DataFrame Polars com dados mensais do mercado secundário.
-
-    Output Columns:
-        * data_liquidacao (Date): data de liquidação da negociação.
-        * titulo (String): sigla do título público.
-        * codigo_selic (Int64): código único no sistema SELIC.
-        * isin (String): código ISIN.
-        * data_emissao (Date): data de emissão do título.
-        * data_vencimento (Date): data de vencimento do título.
-        * operacoes (Int64): número total de operações.
-        * quantidade (Int64): quantidade total negociada.
-        * financeiro (Float64): valor financeiro negociado.
-        * pu_minimo (Float64): preço unitário mínimo.
-        * pu_medio (Float64): preço unitário médio.
-        * pu_maximo (Float64): preço unitário máximo.
-        * pu_lastro (Float64): preço unitário de lastro.
-        * valor_par (Float64): valor par do título.
-        * taxa_minima (Float64): taxa mínima.
-        * taxa_media (Float64): taxa média.
-        * taxa_maxima (Float64): taxa máxima.
-        * operacoes_corretagem (Int64): operações com corretagem.
-        * quantidade_corretagem (Int64): quantidade com corretagem.
-
-    Examples:
-        >>> df = yd.tpf.secundario_mensal("07-01-2025", extragrupo=True)
-    """
-    if any_is_empty(data):
-        return pl.DataFrame()
-    data_alvo = converter_datas(data)
-    if (data_alvo.year, data_alvo.month) > (hoje().year, hoje().month):
-        return pl.DataFrame()
-    url = _montar_url(data_alvo, extragrupo)
-    conteudo_zip = _baixar_zip(url)
-    arquivo_extraido = _descompactar_zip(conteudo_zip)
-    df = _parsear_df(arquivo_extraido)
-    return _processar_df(df)