pyield 0.53.0__tar.gz → 0.53.1__tar.gz

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

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

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.53.1/pyield/tpf/secundario/_intradia.py

@@ -0,0 +1,139 @@
+"""Dados intradia do mercado secundário de TPFs no sistema Selic do BCB."""
+
+import datetime as dt
+
+import polars as pl
+import requests
+
+from pyield import du, relogio
+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
+
+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_intradia() -> bytes:
+    hoje = relogio.hoje()
+    data_formatada = hoje.strftime("%d-%m-%Y")
+    url = f"{URL_BASE_TEMPO_REAL}{data_formatada}"
+    resposta = requests.get(url, timeout=30)  # API costuma levar ~10s
+    resposta.raise_for_status()
+    return resposta.content
+
+
+def _parsear_csv_intradia(dados: bytes) -> pl.DataFrame:
+    return pl.read_csv(
+        dados,
+        separator=";",
+        infer_schema=False,
+        null_values="-",
+    ).rename(lambda c: c.strip())
+
+
+def _processar_df_intradia(df: pl.DataFrame) -> pl.DataFrame:
+    agora = relogio.agora()
+    return df.filter(pl.col("//1") == "1").select(
+        data_hora_consulta=agora,
+        data_liquidacao=agora.date(),
+        titulo=pl.col("sigla").str.strip_chars(),
+        codigo_selic=inteiro_br("código título"),
+        data_vencimento=pl.col("data vencimento").str.to_date("%d/%m/%Y"),
+        pu_minimo=float_br("pu mínimo"),
+        pu_medio=float_br("pu médio"),
+        pu_maximo=float_br("pu máximo"),
+        pu_ultimo=float_br("mercado à vista pu último"),
+        taxa_minima=taxa_br("tx mínimo"),
+        taxa_media=taxa_br("tx médio"),
+        taxa_maxima=taxa_br("tx máximo"),
+        taxa_ultima=taxa_br("tx último"),
+        operacoes=inteiro_br("totais liquidados operações"),
+        quantidade=inteiro_br("títulos"),
+        financeiro=float_br("financeiro"),
+        operacoes_corretagem=inteiro_br("corretagem liquidados operações"),
+        quantidade_corretagem=inteiro_br("corretagem títulos"),
+        termo_pu_minimo=float_br("pu mínimo_duplicated_0"),
+        termo_pu_medio=float_br("pu médio_duplicated_0"),
+        termo_pu_ultimo=float_br("mercado a termo pu último"),
+        termo_pu_maximo=float_br("pu máximo_duplicated_0"),
+        termo_taxa_ultima=taxa_br("tx último_duplicated_0"),
+        termo_taxa_minima=taxa_br("tx mínimo_duplicated_0"),
+        termo_taxa_media=taxa_br("tx médio_duplicated_0"),
+        termo_taxa_maxima=taxa_br("tx máximo_duplicated_0"),
+        termo_operacoes=inteiro_br("totais contratados operações"),
+        termo_quantidade=inteiro_br("títulos_duplicated_0"),
+        termo_financeiro=float_br("financeiro_duplicated_0"),
+        termo_operacoes_corretagem=inteiro_br("corretagem contratados operações"),
+        termo_quantidade_corretagem=inteiro_br("corretagem títulos_duplicated_0"),
+    )
+
+
+def _mercado_selic_aberto() -> bool:
+    agora = relogio.agora()
+    hoje = agora.date()
+    hora = agora.time()
+    eh_dia_util = du.eh_dia_util(hoje)
+    eh_horario = HORA_INICIO_TEMPO_REAL <= hora <= HORA_FIM_TEMPO_REAL
+
+    return eh_dia_util and eh_horario
+
+
+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
+    apenas durante o horário do SELIC (09:00-22:00 BRT) em dias úteis.
+
+    Returns:
+        DataFrame Polars com negociações intradia do mercado secundário.
+        Retorna DataFrame vazio fora do horário do SELIC.
+
+    Output Columns:
+        * data_hora_consulta (Datetime): data e hora da consulta.
+        * data_liquidacao (Date): data de liquidação à vista.
+        * titulo (String): sigla do título público.
+        * codigo_selic (Int64): código SELIC do título.
+        * data_vencimento (Date): data de vencimento do título.
+        * pu_minimo (Float64): menor preço negociado.
+        * pu_medio (Float64): preço médio negociado.
+        * pu_maximo (Float64): maior preço negociado.
+        * pu_ultimo (Float64): último preço negociado.
+        * taxa_minima (Float64): menor taxa negociada.
+        * taxa_media (Float64): taxa média negociada.
+        * taxa_maxima (Float64): maior taxa negociada.
+        * taxa_ultima (Float64): última taxa negociada.
+        * operacoes (Int64): total de operações liquidadas.
+        * quantidade (Int64): quantidade total de títulos negociados.
+        * financeiro (Float64): valor financeiro total negociado.
+        * operacoes_corretagem (Int64): operações via corretagem.
+        * quantidade_corretagem (Int64): títulos via corretagem.
+        * termo_pu_minimo (Float64): menor preço a termo negociado.
+        * termo_pu_medio (Float64): preço médio a termo negociado.
+        * termo_pu_ultimo (Float64): último preço a termo negociado.
+        * termo_pu_maximo (Float64): maior preço a termo negociado.
+        * termo_taxa_ultima (Float64): última taxa a termo negociada.
+        * termo_taxa_minima (Float64): menor taxa a termo negociada.
+        * termo_taxa_media (Float64): taxa média a termo negociada.
+        * termo_taxa_maxima (Float64): maior taxa a termo negociada.
+        * termo_operacoes (Int64): total de operações a termo.
+        * termo_quantidade (Int64): total de títulos a termo negociados.
+        * termo_financeiro (Float64): valor financeiro total a termo.
+        * termo_operacoes_corretagem (Int64): operações a termo via corretagem.
+        * termo_quantidade_corretagem (Int64): títulos a termo via corretagem.
+
+    Examples:
+        >>> df = yd.tpf.secundario.intradia()  # doctest: +SKIP
+    """
+    if not _mercado_selic_aberto():
+        return pl.DataFrame()
+
+    texto_bruto = _buscar_csv_intradia()
+    df = _parsear_csv_intradia(texto_bruto)
+    return _processar_df_intradia(df)

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

@@ -1,4 +1,4 @@
-"""Negociações do mercado secundário de TPFs no sistema Selic do BCB."""
+"""Dados mensais do mercado secundário de TPFs no sistema Selic do BCB."""
 
 import datetime as dt
 import io
@@ -10,33 +10,19 @@ import polars as pl
 import polars.selectors as ps
 import requests
 
-from pyield import du, relogio
-from pyield._internal.br_numbers import float_br, inteiro_br, taxa_br
+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"
-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)
 CHAVES_ORDENACAO = ["data_liquidacao", "titulo", "data_vencimento"]
 COLUNAS_MINIMAS_CSV = 2
 
 type CaminhoArquivo = str | os.PathLike[str]
 
-__all__ = [
-    "baixar_zip",
-    "intradia",
-    "ler_zip",
-    "mensal",
-    "zip_para_silver",
-]
-
 
 def _tipo_arquivo(extragrupo: bool) -> str:
     return "E" if extragrupo else "T"
@@ -50,7 +36,22 @@ def _data_mensal(data: DateLike) -> dt.date:
     return data_alvo
 
 
-def _nome_arquivo(data: DateLike, extragrupo: bool = False) -> str:
+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"
 
@@ -88,7 +89,7 @@ def baixar_zip(data: DateLike, extragrupo: bool = False) -> bytes:
     Examples:
         >>> conteudo = yd.tpf.secundario.baixar_zip("07-01-2025")  # doctest: +SKIP
     """
-    arquivo = _nome_arquivo(data, extragrupo)
+    arquivo = nome_arquivo_mensal(data, extragrupo)
     conteudo_zip = _baixar_url_zip(f"{URL_BASE_MENSAL}/{arquivo}")
     _validar_zip(conteudo_zip, arquivo)
     return conteudo_zip
@@ -147,6 +148,17 @@ def _parsear_csv_mensal(conteudo_csv: bytes) -> pl.DataFrame:
 
 
 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(
@@ -162,7 +174,6 @@ def _processar_df_mensal(df: pl.DataFrame) -> pl.DataFrame:
             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"),
@@ -171,8 +182,8 @@ def _processar_df_mensal(df: pl.DataFrame) -> pl.DataFrame:
             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),
+            operacoes_corretagem=operacoes_corretagem,
+            quantidade_corretagem=quantidade_corretagem,
         )
         .sort(CHAVES_ORDENACAO)
     )
@@ -201,7 +212,6 @@ def zip_para_silver(conteudo_zip: bytes) -> pl.DataFrame:
         * 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.
@@ -213,6 +223,11 @@ def zip_para_silver(conteudo_zip: bytes) -> pl.DataFrame:
         * 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
@@ -244,7 +259,7 @@ 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 silver.
+    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:
@@ -263,7 +278,6 @@ def mensal(data: DateLike, extragrupo: bool = False) -> pl.DataFrame:
         * 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.
@@ -274,6 +288,11 @@ def mensal(data: DateLike, extragrupo: bool = False) -> pl.DataFrame:
         * 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)
@@ -286,125 +305,6 @@ def mensal(data: DateLike, extragrupo: bool = False) -> pl.DataFrame:
     if (data_alvo.year, data_alvo.month) > (hoje.year, hoje.month):
         return pl.DataFrame()
 
-    return zip_para_silver(baixar_zip(data_alvo, extragrupo))
-
-
-@ttl_cache()
-@retry_padrao
-def _buscar_csv_intradia() -> bytes:
-    hoje = relogio.hoje()
-    data_formatada = hoje.strftime("%d-%m-%Y")
-    url = f"{URL_BASE_TEMPO_REAL}{data_formatada}"
-    resposta = requests.get(url, timeout=30)  # API costuma levar ~10s
-    resposta.raise_for_status()
-    return resposta.content
-
-
-def _parsear_csv_intradia(dados: bytes) -> pl.DataFrame:
-    return pl.read_csv(
-        dados,
-        separator=";",
-        infer_schema=False,
-        null_values="-",
-    ).rename(lambda c: c.strip())
-
-
-def _processar_df_intradia(df: pl.DataFrame) -> pl.DataFrame:
-    agora = relogio.agora()
-    return df.filter(pl.col("//1") == "1").select(
-        data_hora_consulta=agora,
-        data_liquidacao=agora.date(),
-        titulo=pl.col("sigla").str.strip_chars(),
-        codigo_selic=inteiro_br("código título"),
-        data_vencimento=pl.col("data vencimento").str.to_date("%d/%m/%Y"),
-        pu_minimo=float_br("pu mínimo"),
-        pu_medio=float_br("pu médio"),
-        pu_maximo=float_br("pu máximo"),
-        pu_ultimo=float_br("mercado à vista pu último"),
-        taxa_minima=taxa_br("tx mínimo"),
-        taxa_media=taxa_br("tx médio"),
-        taxa_maxima=taxa_br("tx máximo"),
-        taxa_ultima=taxa_br("tx último"),
-        operacoes=inteiro_br("totais liquidados operações"),
-        quantidade=inteiro_br("títulos"),
-        financeiro=float_br("financeiro"),
-        operacoes_corretagem=inteiro_br("corretagem liquidados operações"),
-        quantidade_corretagem=inteiro_br("corretagem títulos"),
-        termo_pu_minimo=float_br("pu mínimo_duplicated_0"),
-        termo_pu_medio=float_br("pu médio_duplicated_0"),
-        termo_pu_ultimo=float_br("mercado a termo pu último"),
-        termo_pu_maximo=float_br("pu máximo_duplicated_0"),
-        termo_taxa_ultima=taxa_br("tx último_duplicated_0"),
-        termo_taxa_minima=taxa_br("tx mínimo_duplicated_0"),
-        termo_taxa_media=taxa_br("tx médio_duplicated_0"),
-        termo_taxa_maxima=taxa_br("tx máximo_duplicated_0"),
-        termo_operacoes=inteiro_br("totais contratados operações"),
-        termo_quantidade=inteiro_br("títulos_duplicated_0"),
-        termo_financeiro=float_br("financeiro_duplicated_0"),
-        termo_operacoes_corretagem=inteiro_br("corretagem contratados operações"),
-        termo_quantidade_corretagem=inteiro_br("corretagem títulos_duplicated_0"),
+    return zip_para_silver(baixar_zip(data_alvo, extragrupo)).with_columns(
+        financeiro=(pl.col("quantidade") * pl.col("pu_medio")).round(2),
     )
-
-
-def _mercado_selic_aberto() -> bool:
-    agora = relogio.agora()
-    hoje = agora.date()
-    hora = agora.time()
-    eh_dia_util = du.eh_dia_util(hoje)
-    eh_horario = HORA_INICIO_TEMPO_REAL <= hora <= HORA_FIM_TEMPO_REAL
-
-    return eh_dia_util and eh_horario
-
-
-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
-    apenas durante o horário do SELIC (09:00-22:00 BRT) em dias úteis.
-
-    Returns:
-        DataFrame Polars com negociações intradia do mercado secundário.
-        Retorna DataFrame vazio fora do horário do SELIC.
-
-    Output Columns:
-        * data_hora_consulta (Datetime): data e hora da consulta.
-        * data_liquidacao (Date): data de liquidação à vista.
-        * titulo (String): sigla do título público.
-        * codigo_selic (Int64): código SELIC do título.
-        * data_vencimento (Date): data de vencimento do título.
-        * pu_minimo (Float64): menor preço negociado.
-        * pu_medio (Float64): preço médio negociado.
-        * pu_maximo (Float64): maior preço negociado.
-        * pu_ultimo (Float64): último preço negociado.
-        * taxa_minima (Float64): menor taxa negociada.
-        * taxa_media (Float64): taxa média negociada.
-        * taxa_maxima (Float64): maior taxa negociada.
-        * taxa_ultima (Float64): última taxa negociada.
-        * operacoes (Int64): total de operações liquidadas.
-        * quantidade (Int64): quantidade total de títulos negociados.
-        * financeiro (Float64): valor financeiro total negociado.
-        * operacoes_corretagem (Int64): operações via corretagem.
-        * quantidade_corretagem (Int64): títulos via corretagem.
-        * termo_pu_minimo (Float64): menor preço a termo negociado.
-        * termo_pu_medio (Float64): preço médio a termo negociado.
-        * termo_pu_ultimo (Float64): último preço a termo negociado.
-        * termo_pu_maximo (Float64): maior preço a termo negociado.
-        * termo_taxa_ultima (Float64): última taxa a termo negociada.
-        * termo_taxa_minima (Float64): menor taxa a termo negociada.
-        * termo_taxa_media (Float64): taxa média a termo negociada.
-        * termo_taxa_maxima (Float64): maior taxa a termo negociada.
-        * termo_operacoes (Int64): total de operações a termo.
-        * termo_quantidade (Int64): total de títulos a termo negociados.
-        * termo_financeiro (Float64): valor financeiro total a termo.
-        * termo_operacoes_corretagem (Int64): operações a termo via corretagem.
-        * termo_quantidade_corretagem (Int64): títulos a termo via corretagem.
-
-    Examples:
-        >>> df = yd.tpf.secundario.intradia()  # doctest: +SKIP
-    """
-    if not _mercado_selic_aberto():
-        return pl.DataFrame()
-
-    texto_bruto = _buscar_csv_intradia()
-    df = _parsear_csv_intradia(texto_bruto)
-    return _processar_df_intradia(df)

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

@@ -19,7 +19,7 @@ dependencies = [
     "fastexcel>=0.19.0",
     "tzdata>=2024.1; platform_system == 'Windows'",
 ]
-version = "0.53.0"
+version = "0.53.1"
 
 [project.urls]
 Homepage = "https://github.com/crdcj/PYield"