pyield 0.48.5__tar.gz → 0.48.7__tar.gz

{pyield-0.48.5 → pyield-0.48.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyield
-Version: 0.48.5
+Version: 0.48.7
 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

pyield-0.48.7/pyield/__about__.py

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

{pyield-0.48.5 → pyield-0.48.7}/pyield/bc/__init__.py

@@ -1,8 +1,9 @@
 from pyield.bc import compromissada, copom
 from pyield.bc.compromissada import compromissadas
 from pyield.bc.leiloes import leiloes
-from pyield.bc.ptax import ptax, ptax_serie
-from pyield.bc.selic import (
+from pyield.bc.sgs import (
+    ptax,
+    ptax_serie,
     selic_meta,
     selic_meta_serie,
     selic_over,

pyield-0.48.7/pyield/bc/_olinda.py

@@ -0,0 +1,33 @@
+"""Helpers compartilhados para acesso à API OData do BCB (olinda.bcb.gov.br)."""
+
+import polars as pl
+import requests
+
+from pyield._internal.retry import retry_padrao
+
+
+def montar_url(url_base: str, parametros: dict[str, str]) -> str:
+    """Monta URL OData com parâmetros opcionais e formato CSV.
+
+    Args:
+        url_base: URL base do endpoint OData (com '?' no final).
+        parametros: Dicionário ``{nome_param: valor}`` já formatado.
+            Parâmetros com valor vazio são ignorados.
+    """
+    partes = [f"@{k}='{v}'" for k, v in parametros.items() if v]
+    return url_base + "&".join(partes) + "&$format=text/csv"
+
+
+@retry_padrao
+def buscar_csv(url: str) -> bytes:
+    """Busca CSV da API OData do BCB com retry automático."""
+    r = requests.get(url, timeout=10)
+    r.raise_for_status()
+    return r.content
+
+
+def parsear_csv(dados: bytes) -> pl.DataFrame:
+    """Lê CSV OData como DataFrame sem inferência de tipos."""
+    if not dados.strip():
+        return pl.DataFrame()
+    return pl.read_csv(dados, infer_schema=False, null_values=["null", ""])

{pyield-0.48.5 → pyield-0.48.7}/pyield/bc/compromissada.py

@@ -13,63 +13,27 @@ ac1b013d13d6fb1d9d9e251b8000121e, 2025-08-21   , 12:00     , TodoMercado
 """
 
 import polars as pl
-import requests
 
 import pyield._internal.converters as cv
 from pyield import du
 from pyield._internal.br_numbers import float_br, taxa_br
-from pyield._internal.retry import retry_padrao
 from pyield._internal.types import DateLike
+from pyield.bc._olinda import buscar_csv, montar_url, parsear_csv
 
 URL_BASE_API = "https://olinda.bcb.gov.br/olinda/servico/leiloes_selic/versao/v1/odata/leiloes_compromissadas(dataLancamentoInicio=@dataLancamentoInicio,dataLancamentoFim=@dataLancamentoFim,horaInicio=@horaInicio,dataLiquidacao=@dataLiquidacao,dataRetorno=@dataRetorno,publicoPermitidoLeilao=@publicoPermitidoLeilao,nomeTipoOferta=@nomeTipoOferta)?"
 
 
-def _montar_url(
+def _montar_parametros(
     inicio: DateLike | None,
     fim: DateLike | None,
-) -> str:
-    """Monta URL de consulta conforme parâmetros opcionais de período.
-
-    Regras da API:
-        - Apenas inicio: retorna de inicio até o fim da série.
-        - Apenas fim: retorna do início da série até fim.
-        - Ambos ausentes: retorna a série completa.
-    """
-    url = URL_BASE_API
+) -> dict[str, str]:
+    """Converte parâmetros opcionais de período em dicionário para a URL."""
+    params: dict[str, str] = {}
     if inicio:
-        inicio_dt = cv.converter_datas(inicio)
-        inicio_str = inicio_dt.strftime("%Y-%m-%d")
-        url += f"@dataLancamentoInicio='{inicio_str}'"
-
+        params["dataLancamentoInicio"] = cv.converter_datas(inicio).strftime("%Y-%m-%d")
     if fim:
-        fim_dt = cv.converter_datas(fim)
-        fim_str = fim_dt.strftime("%Y-%m-%d")
-        url += f"&@dataLancamentoFim='{fim_str}'"
-
-    url += "&$format=text/csv"  # Adiciona o formato CSV ao final
-
-    return url
-
-
-@retry_padrao
-def _buscar_csv_api(url: str) -> bytes:
-    """Executa requisição HTTP e retorna o corpo CSV como string.
-
-    Decorado com ``retry_padrao`` para resiliência a falhas transitórias.
-    Levanta exceções de status HTTP para tratamento a montante.
-    """
-    r = requests.get(url, timeout=10)
-    r.raise_for_status()
-    return r.content
-
-
-def _ler_csv(csv_bytes: bytes) -> pl.DataFrame:
-    """Lê o CSV (bytes) em um DataFrame Polars sem inferência de tipos."""
-    return pl.read_csv(
-        csv_bytes,
-        infer_schema=False,
-        null_values=["null", ""],
-    )
+        params["dataLancamentoFim"] = cv.converter_datas(fim).strftime("%Y-%m-%d")
+    return params
 
 
 def _processar_df(df: pl.DataFrame) -> pl.DataFrame:
@@ -80,14 +44,14 @@ def _processar_df(df: pl.DataFrame) -> pl.DataFrame:
         data_liquidacao=pl.col("dataLiquidacao").str.to_date("%Y-%m-%d"),
         data_retorno=pl.col("dataRetorno").str.to_date("%Y-%m-%d"),
         hora_inicio=pl.col("horaInicio").str.to_time("%H:%M"),
-        prazo_dias_corridos=pl.col("prazoDiasCorridos").cast(pl.Int64),
-        prazo_dias_uteis=du.contar_expr("dataLiquidacao", "dataRetorno"),
-        numero_comunicado=pl.col("numeroComunicado").cast(pl.Int64),
+        prazo_dc=pl.col("prazoDiasCorridos").cast(pl.Int64),
+        prazo_du=du.contar_expr("dataLiquidacao", "dataRetorno"),
+        comunicado=pl.col("numeroComunicado").cast(pl.Int64),
         tipo_oferta=pl.col("nomeTipoOferta"),
-        publico_permitido=pl.col("publicoPermitidoLeilao"),
-        volume_aceito=1000 * pl.col("volumeAceito").cast(pl.Int64),
+        publico=pl.col("publicoPermitidoLeilao"),
+        financeiro_aceito=1000 * pl.col("volumeAceito").cast(pl.Float64),
         taxa_corte=pl.when(vol_zero).then(None).otherwise(taxa_br("taxaCorte")),
-        percentual_aceito=pl.when(vol_zero)
+        pct_aceito=pl.when(vol_zero)
         .then(0.0)
         .otherwise(100 - float_br("percentualCorte")),
     ).sort("data_leilao", "hora_inicio", "tipo_oferta")
@@ -117,36 +81,41 @@ def compromissadas(
         - data_liquidacao (Date): data de liquidação (início da operação).
         - data_retorno (Date): data de recompra / término da operação.
         - hora_inicio (Time): horário de início do leilão.
-        - prazo_dias_corridos (Int64): dias corridos até a data de retorno.
-                - prazo_dias_uteis (Int64): dias úteis entre liquidação e retorno
-                    (du.contar).
-        - numero_comunicado (Int64): número do comunicado/aviso do BC (pode ser nulo).
+        - prazo_dc (Int64): dias corridos até a data de retorno.
+        - prazo_du (Int64): dias úteis entre liquidação e retorno.
+        - comunicado (Int64): número do comunicado/aviso do BC (pode ser nulo).
         - tipo_oferta (String): classif. do tipo de oferta (ex: Tomador, Compromissada 1047).
-        - publico_permitido (String): escopo de participantes (SomenteDealer, TodoMercado).
-        - volume_aceito (Int64): volume aceito no leilão em reais (convertido de milhares).
-        - taxa_corte (Float64): taxa de corte (ex. 0.1490 = 14,90%). Nula se volume_aceito = 0.
-        - percentual_aceito (Float64): percentual do volume ofertado efetivamente aceito (0-100).
+        - publico (String): público permitido no leilão (SomenteDealer, TodoMercado).
+        - financeiro_aceito (Float64): financeiro aceito no leilão em reais (convertido de milhares).
+        - taxa_corte (Float64): taxa de corte (ex. 0.1490 = 14,90%). Nula se financeiro_aceito = 0.
+        - pct_aceito (Float64): percentual do volume ofertado efetivamente aceito (0-100).
           100 = nenhuma rejeição. 0 indica nada aceito (volume_aceito = 0).
 
     Notes:
         - Dados ordenados por: data_leilao, hora_inicio, tipo_oferta.
 
     Examples:
+        >>> import polars as pl
+        >>> _ = pl.Config.set_tbl_width_chars(210)
+        >>> _ = pl.Config.set_tbl_cols(-1)
         >>> from pyield import bc
         >>> bc.compromissadas(inicio="21-08-2025", fim="21-08-2025")
         shape: (2, 12)
-        ┌─────────────┬─────────────────┬──────────────┬─────────────┬───┬───────────────────┬───────────────┬────────────┬───────────────────┐
-        │ data_leilao ┆ data_liquidacao ┆ data_retorno ┆ hora_inicio ┆ … ┆ publico_permitido ┆ volume_aceito ┆ taxa_corte ┆ percentual_aceito │
-        │ ---         ┆ ---             ┆ ---          ┆ ---         ┆   ┆ ---               ┆ ---           ┆ ---        ┆ ---               │
-        │ date        ┆ date            ┆ date         ┆ time        ┆   ┆ str               ┆ i64           ┆ f64        ┆ f64               │
-        ╞═════════════╪═════════════════╪══════════════╪═════════════╪═══╪═══════════════════╪═══════════════╪════════════╪═══════════════════╡
-        │ 2025-08-21  ┆ 2025-08-21      ┆ 2025-08-22   ┆ 09:00:00    ┆ … ┆ SomenteDealer     ┆ 647707406000  ┆ 0.149      ┆ 100.0             │
-        │ 2025-08-21  ┆ 2025-08-22      ┆ 2025-11-21   ┆ 12:00:00    ┆ … ┆ TodoMercado       ┆ 5000000000    ┆ 0.9978     ┆ 35.87             │
-        └─────────────┴─────────────────┴──────────────┴─────────────┴───┴───────────────────┴───────────────┴────────────┴───────────────────┘
+        ┌─────────────┬─────────────────┬──────────────┬─────────────┬──────────┬──────────┬────────────┬────────────────────┬───────────────┬───────────────────┬────────────┬────────────┐
+        │ data_leilao ┆ data_liquidacao ┆ data_retorno ┆ hora_inicio ┆ prazo_dc ┆ prazo_du ┆ comunicado ┆ tipo_oferta        ┆ publico       ┆ financeiro_aceito ┆ taxa_corte ┆ pct_aceito │
+        │ ---         ┆ ---             ┆ ---          ┆ ---         ┆ ---      ┆ ---      ┆ ---        ┆ ---                ┆ ---           ┆ ---               ┆ ---        ┆ ---        │
+        │ date        ┆ date            ┆ date         ┆ time        ┆ i64      ┆ i64      ┆ i64        ┆ str                ┆ str           ┆ f64               ┆ f64        ┆ f64        │
+        ╞═════════════╪═════════════════╪══════════════╪═════════════╪══════════╪══════════╪════════════╪════════════════════╪═══════════════╪═══════════════════╪════════════╪════════════╡
+        │ 2025-08-21  ┆ 2025-08-21      ┆ 2025-08-22   ┆ 09:00:00    ┆ 1        ┆ 1        ┆ null       ┆ Tomador            ┆ SomenteDealer ┆ 6.4771e11         ┆ 0.149      ┆ 100.0      │
+        │ 2025-08-21  ┆ 2025-08-22      ┆ 2025-11-21   ┆ 12:00:00    ┆ 91       ┆ 64       ┆ 43716      ┆ Compromissada 1047 ┆ TodoMercado   ┆ 5.0000e9          ┆ 0.9978     ┆ 35.87      │
+        └─────────────┴─────────────────┴──────────────┴─────────────┴──────────┴──────────┴────────────┴────────────────────┴───────────────┴───────────────────┴────────────┴────────────┘
+        >>> _ = pl.Config.restore_defaults()
+        >>> _ = pl.Config.set_tbl_width_chars(150)
     """
-    url = _montar_url(inicio=inicio, fim=fim)
-    csv_api = _buscar_csv_api(url)
-    df = _ler_csv(csv_api)
+    params = _montar_parametros(inicio, fim)
+    url = montar_url(URL_BASE_API, params)
+    dados = buscar_csv(url)
+    df = parsear_csv(dados)
     if df.is_empty():
         return pl.DataFrame()
     return _processar_df(df)

{pyield-0.48.5 → pyield-0.48.7}/pyield/bc/leiloes.py

@@ -12,14 +12,13 @@ from typing import Literal
 
 import polars as pl
 import polars.selectors as cs
-import requests
 
 import pyield._internal.converters as cv
 from pyield import du
 from pyield._internal.br_numbers import float_br, taxa_br
-from pyield._internal.retry import retry_padrao
 from pyield._internal.types import DateLike
-from pyield.bc.ptax import ptax_serie
+from pyield.bc._olinda import buscar_csv, montar_url, parsear_csv
+from pyield.bc.sgs import ptax_serie
 from pyield.tn.ntnb import duration as duration_b
 from pyield.tn.ntnf import duration as duration_f
 
@@ -74,39 +73,17 @@ CHAVES_ORDENACAO = ["data_leilao", "tipo_leilao", "titulo", "data_vencimento"]
 URL_BASE_API = "https://olinda.bcb.gov.br/olinda/servico/leiloes_selic/versao/v1/odata/leiloesTitulosPublicos(dataMovimentoInicio=@dataMovimentoInicio,dataMovimentoFim=@dataMovimentoFim,dataLiquidacao=@dataLiquidacao,codigoTitulo=@codigoTitulo,dataVencimento=@dataVencimento,edital=@edital,tipoPublico=@tipoPublico,tipoOferta=@tipoOferta)?"
 
 
-MAPA_TIPO_LEILAO = {"venda": "Venda", "compra": "Compra"}
-
-
-def _montar_url(
+def _montar_parametros(
     inicio: DateLike | None = None,
     fim: DateLike | None = None,
-    tipo_leilao: Literal["venda", "compra"] | None = None,
-) -> str:
-    url = URL_BASE_API
+) -> dict[str, str]:
+    """Converte parâmetros opcionais de período em dicionário para a URL."""
+    params: dict[str, str] = {}
     if inicio:
-        inicio = cv.converter_datas(inicio)
-        url += f"@dataMovimentoInicio='{inicio:%Y-%m-%d}'"
+        params["dataMovimentoInicio"] = cv.converter_datas(inicio).strftime("%Y-%m-%d")
     if fim:
-        fim = cv.converter_datas(fim)
-        url += f"&@dataMovimentoFim='{fim:%Y-%m-%d}'"
-    if tipo_leilao:
-        url += f"&@tipoOferta='{MAPA_TIPO_LEILAO[tipo_leilao.lower()]}'"
-    url += "&$format=text/csv"
-    return url
-
-
-@retry_padrao
-def _buscar_csv(url: str) -> bytes:
-    resposta = requests.get(url, timeout=10)
-    resposta.raise_for_status()
-    return resposta.content
-
-
-def _parsear_df(dados: bytes) -> pl.DataFrame:
-    """Lê CSV como strings."""
-    if not dados.strip():
-        return pl.DataFrame()
-    return pl.read_csv(dados, infer_schema=False, null_values=["null"])
+        params["dataMovimentoFim"] = cv.converter_datas(fim).strftime("%Y-%m-%d")
+    return params
 
 
 def _processar_df(df: pl.DataFrame) -> pl.DataFrame:
@@ -147,9 +124,7 @@ def _processar_df(df: pl.DataFrame) -> pl.DataFrame:
             pu_corte=float_br("cotacaoCorte"),
             taxa_media=taxa_br("taxaMedia"),
             taxa_corte=taxa_br("taxaCorte"),
-            financeiro_total=(float_br("financeiro") * 1_000_000)
-            .round(0)
-            .cast(pl.Int64),
+            financeiro_total=float_br("financeiro") * 1_000_000,
             quantidade_ofertada_1v=pl.col("quantidadeOfertada").cast(pl.Int64),
             quantidade_aceita_1v=pl.col("quantidadeAceita").cast(pl.Int64),
             quantidade_liquidada_1v=pl.col("quantidadeLiquidada").cast(pl.Int64),
@@ -182,9 +157,7 @@ def _processar_df(df: pl.DataFrame) -> pl.DataFrame:
                 (pl.col("quantidade_aceita_1v") / pl.col("quantidade_aceita_total"))
                 * pl.col("financeiro_total")
             )
-            .otherwise(0)
-            .round(0)
-            .cast(pl.Int64),
+            .otherwise(0.0),
         )
         .with_columns(
             financeiro_2v=pl.col("financeiro_total") - pl.col("financeiro_1v"),
@@ -240,8 +213,8 @@ def _buscar_ptax(df: pl.DataFrame) -> pl.DataFrame:
         return pl.DataFrame()
 
     return (
-        df_ptax.select("data", "cotacao_media")
-        .rename({"data": "data_ref", "cotacao_media": "ptax"})
+        df_ptax.select("data", "cotacao")
+        .rename({"data": "data_ref", "cotacao": "ptax"})
         .sort("data_ref")
     )
 
@@ -319,9 +292,9 @@ def leiloes(
         * quantidade_aceita_1v (Int64): qtd aceita 1ª volta.
         * quantidade_aceita_2v (Int64): qtd aceita 2ª volta.
         * quantidade_aceita_total (Int64): qtd total aceita.
-        * financeiro_1v (Int64): financeiro 1ª volta em R$.
-        * financeiro_2v (Int64): financeiro 2ª volta em R$.
-        * financeiro_total (Int64): financeiro total em R$.
+        * financeiro_1v (Float64): financeiro 1ª volta em R$.
+        * financeiro_2v (Float64): financeiro 2ª volta em R$.
+        * financeiro_total (Float64): financeiro total em R$.
 
     Notes:
         1v = primeira volta (rodada), 2v = segunda volta.
@@ -333,24 +306,23 @@ def leiloes(
         ┌─────────────┬─────────────────┬─────────────┬───────────────┬───┬─────────────────────────┬───────────────┬───────────────┬──────────────────┐
         │ data_leilao ┆ data_liquidacao ┆ tipo_leilao ┆ numero_edital ┆ … ┆ quantidade_aceita_total ┆ financeiro_1v ┆ financeiro_2v ┆ financeiro_total │
         │ ---         ┆ ---             ┆ ---         ┆ ---           ┆   ┆ ---                     ┆ ---           ┆ ---           ┆ ---              │
-        │ date        ┆ date            ┆ str         ┆ i64           ┆   ┆ i64                     ┆ i64           ┆ i64           ┆ i64              │
+        │ date        ┆ date            ┆ str         ┆ i64           ┆   ┆ i64                     ┆ f64           ┆ f64           ┆ f64              │
         ╞═════════════╪═════════════════╪═════════════╪═══════════════╪═══╪═════════════════════════╪═══════════════╪═══════════════╪══════════════════╡
-        │ 2025-08-19  ┆ 2025-08-20      ┆ Venda       ┆ 192           ┆ … ┆ 150000                  ┆ 2572400000    ┆ 0             ┆ 2572400000       │
-        │ 2025-08-19  ┆ 2025-08-20      ┆ Venda       ┆ 192           ┆ … ┆ 751003                  ┆ 12804476147   ┆ 17123853      ┆ 12821600000      │
-        │ 2025-08-19  ┆ 2025-08-20      ┆ Venda       ┆ 193           ┆ … ┆ 300759                  ┆ 1289936461    ┆ 3263539       ┆ 1293200000       │
-        │ 2025-08-19  ┆ 2025-08-20      ┆ Venda       ┆ 194           ┆ … ┆ 500542                  ┆ 2071654327    ┆ 2245673       ┆ 2073900000       │
-        │ 2025-08-19  ┆ 2025-08-20      ┆ Venda       ┆ 194           ┆ … ┆ 500000                  ┆ 2010700000    ┆ 0             ┆ 2010700000       │
+        │ 2025-08-19  ┆ 2025-08-20      ┆ Venda       ┆ 192           ┆ … ┆ 150000                  ┆ 2.5724e9      ┆ 0.0           ┆ 2.5724e9         │
+        │ 2025-08-19  ┆ 2025-08-20      ┆ Venda       ┆ 192           ┆ … ┆ 751003                  ┆ 1.2804e10     ┆ 1.7124e7      ┆ 1.2822e10        │
+        │ 2025-08-19  ┆ 2025-08-20      ┆ Venda       ┆ 193           ┆ … ┆ 300759                  ┆ 1.2899e9      ┆ 3.2635e6      ┆ 1.2932e9         │
+        │ 2025-08-19  ┆ 2025-08-20      ┆ Venda       ┆ 194           ┆ … ┆ 500542                  ┆ 2.0717e9      ┆ 2.2457e6      ┆ 2.0739e9         │
+        │ 2025-08-19  ┆ 2025-08-20      ┆ Venda       ┆ 194           ┆ … ┆ 500000                  ┆ 2.0107e9      ┆ 0.0           ┆ 2.0107e9         │
         └─────────────┴─────────────────┴─────────────┴───────────────┴───┴─────────────────────────┴───────────────┴───────────────┴──────────────────┘
     """
-    url = _montar_url(
-        inicio=inicio,
-        fim=fim,
-        tipo_leilao=tipo_leilao,
-    )
-    dados = _buscar_csv(url)
-    df = _parsear_df(dados)
+    url = montar_url(URL_BASE_API, _montar_parametros(inicio, fim))
+    dados = buscar_csv(url)
+    df = parsear_csv(dados)
     if df.is_empty():
         return pl.DataFrame()
     df = _processar_df(df)
     df = _adicionar_dv01_usd(df)
-    return df.select(ORDEM_COLUNAS_FINAL).sort(CHAVES_ORDENACAO)
+    df = df.select(ORDEM_COLUNAS_FINAL).sort(CHAVES_ORDENACAO)
+    if tipo_leilao:
+        df = df.filter(pl.col("tipo_leilao").str.to_lowercase() == tipo_leilao.lower())
+    return df

pyield-0.48.5/pyield/bc/selic.py → pyield-0.48.7/pyield/bc/sgs.py

@@ -1,22 +1,24 @@
-"""Taxas de juros do Banco Central do Brasil (séries SGS).
+"""Séries do Sistema Gerenciador de Séries (SGS) do Banco Central.
 
 Séries disponíveis:
-    - SELIC Over (SGS 1178)
+    - PTAX Venda (SGS 1)
     - SELIC Meta (SGS 432)
+    - SELIC Over (SGS 1178)
 
 Exemplos de chamada à API:
     https://api.bcb.gov.br/dados/serie/bcdata.sgs.1178/dados?formato=json&dataInicial=29/01/2025&dataFinal=31/01/2025
     https://api.bcb.gov.br/dados/serie/bcdata.sgs.1178/dados/ultimos/5?formato=json
 
-Exemplo de resposta JSON da API do BCB (valores em percentual):
+Exemplo de resposta JSON da API do BCB:
     [{"data":"29/01/2025","valor":"12.15"},
      {"data":"30/01/2025","valor":"13.15"},
      {"data":"31/01/2025","valor":"13.15"}]
 
 Notas de implementação:
-    - Valores percentuais são convertidos para decimal (divididos por 100).
-    - SELIC Over e Meta: arredondadas para 4 casas decimais.
     - Intervalos > 10 anos são divididos automaticamente em blocos.
+    - SELIC Over e Meta: valores percentuais convertidos para decimal
+      (divididos por 100) e arredondados para 4 casas decimais.
+    - PTAX Venda: valor absoluto em R$ arredondado para 4 casas.
 """
 
 import datetime as dt
@@ -31,39 +33,39 @@ from pyield._internal.converters import converter_datas
 from pyield._internal.retry import retry_padrao
 from pyield._internal.types import DateLike, any_is_empty
 
-
-def _extrair_taxa(df: pl.DataFrame) -> float:
-    """Extrai a taxa escalar de um DataFrame ou retorna nan se vazio."""
-    if df.is_empty():
-        return float("nan")
-    return df["taxa"].item(0)
-
-
 URL_BASE = "https://api.bcb.gov.br/dados/serie/bcdata.sgs."
-CASAS_DECIMAIS_ANUALIZADA = 4  # 2 casas no formato percentual
+
+ESQUEMA_BRUTO = {"data": pl.Date, "valor": pl.Float64}
 
 # Limite de segurança em dias, correspondendo a ~9.5 anos.
 # Evita a complexidade do cálculo exato de 10 anos-calendário.
 LIMITE_DIAS_SEGURO = 3500  # aprox 365 * 9.5
 
+CASAS_DECIMAIS_TAXA = 4  # Selic: 2 casas no formato percentual → 4 em decimal
+CASAS_DECIMAIS_PTAX = 4
 
-class SerieBC(Enum):
-    """Enum para as séries disponíveis no Banco Central."""
 
-    SELIC_OVER = 1178
+class SerieSGS(Enum):
+    """Enum para as séries disponíveis no SGS do Banco Central."""
+
+    PTAX_VENDA = 1
     SELIC_META = 432
+    SELIC_OVER = 1178
+
+
+# ── Infraestrutura de acesso à API SGS ──────────────────────────────
 
 
 @ttl_cache()
 @retry_padrao
 def _chamar_api(url_api: str) -> list[dict[str, str]]:
-    resposta = requests.get(url_api, timeout=10)
+    resposta = requests.get(url_api, timeout=30)
     resposta.raise_for_status()
     return resposta.json()
 
 
 def _montar_url_intervalo(
-    serie: SerieBC, inicio: dt.date, fim: dt.date | None = None
+    serie: SerieSGS, inicio: dt.date, fim: dt.date | None = None
 ) -> str:
     inicio_str = inicio.strftime("%d/%m/%Y")
     url = f"{URL_BASE}{serie.value}/dados?formato=json&dataInicial={inicio_str}"
@@ -72,37 +74,30 @@ def _montar_url_intervalo(
     return url
 
 
-def _montar_url_ultimos(serie: SerieBC, n: int) -> str:
+def _montar_url_ultimos(serie: SerieSGS, n: int) -> str:
     return f"{URL_BASE}{serie.value}/dados/ultimos/{n}?formato=json"
 
 
 def _buscar_api(url_api: str) -> pl.DataFrame:
-    """Busca dados da API e converte em DataFrame."""
-    esquema = {"data": pl.Date, "taxa": pl.Float64}
-
+    """Busca dados da API e retorna DataFrame bruto {data, valor}."""
     try:
         dados = _chamar_api(url_api)
     except requests.exceptions.HTTPError as e:
         if e.response.status_code == 404:  # noqa
-            return pl.DataFrame(schema=esquema)
+            return pl.DataFrame(schema=ESQUEMA_BRUTO)
         raise
 
     if not dados:
-        return pl.DataFrame(schema=esquema)
+        return pl.DataFrame(schema=ESQUEMA_BRUTO)
 
-    df = pl.from_dicts(dados).select(
+    return pl.from_dicts(dados).select(
         pl.col("data").str.to_date("%d/%m/%Y"),
-        pl.col("valor")
-        .cast(pl.Float64)
-        .truediv(100)
-        .round(CASAS_DECIMAIS_ANUALIZADA)
-        .alias("taxa"),
+        pl.col("valor").cast(pl.Float64),
     )
-    return df
 
 
 def _buscar_dados_url(
-    serie: SerieBC,
+    serie: SerieSGS,
     inicio: DateLike,
     fim: DateLike | None = None,
 ) -> pl.DataFrame:
@@ -124,11 +119,51 @@ def _buscar_dados_url(
     todos_dfs = [df for df in todos_dfs if not df.is_empty()]
 
     if not todos_dfs:
-        return pl.DataFrame()
+        return pl.DataFrame(schema=ESQUEMA_BRUTO)
 
     return pl.concat(todos_dfs).unique(subset=["data"], keep="first").sort("data")
 
 
+def _buscar_serie(
+    serie: SerieSGS,
+    inicio: DateLike | None,
+    fim: DateLike | None,
+    ultimos: int | None,
+) -> pl.DataFrame:
+    """Busca genérica para qualquer série SGS."""
+    if ultimos is not None:
+        return _buscar_api(_montar_url_ultimos(serie, ultimos))
+    if inicio is not None:
+        return _buscar_dados_url(serie, inicio, fim)
+    raise ValueError("Informe 'inicio' ou 'ultimos'.")
+
+
+# ── Helpers de transformação ─────────────────────────────────────────
+
+ESQUEMA_TAXA = {"data": pl.Date, "taxa": pl.Float64}
+ESQUEMA_PTAX = {"data": pl.Date, "cotacao": pl.Float64}
+
+
+def _converter_para_taxa(df: pl.DataFrame) -> pl.DataFrame:
+    """Converte valor percentual para decimal e renomeia para 'taxa'."""
+    if df.is_empty():
+        return pl.DataFrame(schema=ESQUEMA_TAXA)
+    return df.select(
+        "data",
+        taxa=pl.col("valor").truediv(100).round(CASAS_DECIMAIS_TAXA),
+    )
+
+
+def _extrair_escalar(df: pl.DataFrame, coluna: str) -> float:
+    """Extrai um valor escalar de um DataFrame ou retorna nan se vazio."""
+    if df.is_empty():
+        return float("nan")
+    return df[coluna].item(0)
+
+
+# ── SELIC Over ───────────────────────────────────────────────────────
+
+
 def selic_over_serie(
     inicio: DateLike | None = None,
     fim: DateLike | None = None,
@@ -179,13 +214,9 @@ def selic_over_serie(
         │ 2025-09-17 ┆ 0.149 │
         └────────────┴───────┘
     """
-    if ultimos is not None:
-        df = _buscar_api(_montar_url_ultimos(SerieBC.SELIC_OVER, ultimos))
-    elif inicio is not None:
-        df = _buscar_dados_url(SerieBC.SELIC_OVER, inicio, fim)
-    else:
-        raise ValueError("Informe 'inicio' ou 'ultimos'.")
-    return df
+    return _converter_para_taxa(
+        _buscar_serie(SerieSGS.SELIC_OVER, inicio, fim, ultimos)
+    )
 
 
 def selic_over(data: DateLike) -> float:
@@ -204,7 +235,10 @@ def selic_over(data: DateLike) -> float:
     """
     if any_is_empty(data):
         return float("nan")
-    return _extrair_taxa(selic_over_serie(data, data))
+    return _extrair_escalar(selic_over_serie(data, data), "taxa")
+
+
+# ── SELIC Meta ───────────────────────────────────────────────────────
 
 
 def selic_meta_serie(
@@ -238,13 +272,9 @@ def selic_meta_serie(
         │ 2024-05-31 ┆ 0.105 │
         └────────────┴───────┘
     """
-    if ultimos is not None:
-        df = _buscar_api(_montar_url_ultimos(SerieBC.SELIC_META, ultimos))
-    elif inicio is not None:
-        df = _buscar_dados_url(SerieBC.SELIC_META, inicio, fim)
-    else:
-        raise ValueError("Informe 'inicio' ou 'ultimos'.")
-    return df
+    return _converter_para_taxa(
+        _buscar_serie(SerieSGS.SELIC_META, inicio, fim, ultimos)
+    )
 
 
 def selic_meta(data: DateLike) -> float:
@@ -263,4 +293,94 @@ def selic_meta(data: DateLike) -> float:
     """
     if any_is_empty(data):
         return float("nan")
-    return _extrair_taxa(selic_meta_serie(data, data))
+    return _extrair_escalar(selic_meta_serie(data, data), "taxa")
+
+
+# ── PTAX ─────────────────────────────────────────────────────────────
+
+
+def ptax_serie(
+    inicio: DateLike | None = None,
+    fim: DateLike | None = None,
+    *,
+    ultimos: int | None = None,
+) -> pl.DataFrame:
+    """Cotação PTAX de venda do dólar (série SGS 1).
+
+    Fonte: Banco Central do Brasil (BCB). Frequência diária.
+
+    A cotação retornada é a PTAX de **venda**, a taxa de câmbio
+    oficial do dólar no Brasil, usada como referência para
+    liquidação de contratos, marcação a mercado de derivativos,
+    conversão de DV01 e índices de fundos cambiais.
+
+    Args:
+        inicio: Data inicial.
+        fim: Data final. Se ``None``, usa a data mais recente.
+        ultimos: Número de registros mais recentes a retornar.
+            Mutuamente exclusivo com ``inicio``/``fim``.
+
+    Returns:
+        DataFrame com colunas data e cotacao, ou DataFrame vazio
+        se não houver dados.
+
+    Output Columns:
+        * data (Date): data da cotação.
+        * cotacao (Float64): cotação PTAX de venda em R$/US$.
+
+    Notes:
+        Disponível desde 28.11.1984. Refere-se às taxas administradas até
+        março de 1990 e às taxas livres a partir de então (Resolução 1690,
+        de 18.3.1990). A partir de março de 1992, essa taxa recebeu a
+        denominação PTAX. Desde 1 de julho de 2011 (Circular 3506), a PTAX
+        corresponde à média aritmética das taxas obtidas em quatro consultas
+        diárias aos dealers de câmbio.
+
+    Examples:
+        >>> from pyield import bc
+        >>> bc.ptax_serie("20-04-2025", "25-04-2025")
+        shape: (4, 2)
+        ┌────────────┬─────────┐
+        │ data       ┆ cotacao │
+        │ ---        ┆ ---     │
+        │ date       ┆ f64     │
+        ╞════════════╪═════════╡
+        │ 2025-04-22 ┆ 5.7496  │
+        │ 2025-04-23 ┆ 5.688   │
+        │ 2025-04-24 ┆ 5.6738  │
+        │ 2025-04-25 ┆ 5.6846  │
+        └────────────┴─────────┘
+    """
+    df = _buscar_serie(SerieSGS.PTAX_VENDA, inicio, fim, ultimos)
+    if df.is_empty():
+        return pl.DataFrame(schema=ESQUEMA_PTAX)
+    return df.select(
+        "data",
+        cotacao=pl.col("valor").round(CASAS_DECIMAIS_PTAX),
+    )
+
+
+def ptax(data: DateLike) -> float:
+    """Cotação PTAX de venda para uma data específica.
+
+    Retorna a PTAX de venda, taxa de câmbio oficial do dólar no
+    Brasil.
+
+    Args:
+        data: Data desejada.
+
+    Returns:
+        Cotação PTAX de venda em R$/US$, ou ``nan`` se não houver
+        cotação (feriado, fim de semana ou data futura).
+
+    Examples:
+        >>> from pyield import bc
+        >>> bc.ptax("22-04-2025")
+        5.7496
+
+        >>> bc.ptax("20-04-2025")
+        nan
+    """
+    if any_is_empty(data):
+        return float("nan")
+    return _extrair_escalar(ptax_serie(data, data), "cotacao")

{pyield-0.48.5 → pyield-0.48.7}/pyield/tn/leiloes.py

@@ -292,8 +292,8 @@ def _buscar_ptax(data_leilao: dt.date) -> pl.DataFrame:
         return pl.DataFrame()
 
     return (
-        df.select("data", "cotacao_media")
-        .rename({"data": "data_ref", "cotacao_media": "ptax"})
+        df.select("data", "cotacao")
+        .rename({"data": "data_ref", "cotacao": "ptax"})
         .sort("data_ref")
     )
 

{pyield-0.48.5 → pyield-0.48.7}/pyield/tn/utils.py

@@ -80,7 +80,7 @@ def adicionar_duration(
 
 def adicionar_dv01(df: pl.DataFrame, data_ref: dt.date) -> pl.DataFrame:
     """Adiciona `dv01` e `dv01_usd` ao DataFrame. Requer coluna `duration`."""
-    from pyield.bc.ptax import ptax  # noqa: PLC0415
+    from pyield.bc.sgs import ptax  # noqa: PLC0415
 
     expr_duracao_mod = pl.col("duration") / (1 + pl.col("taxa_indicativa"))
     df = df.with_columns(dv01=0.0001 * expr_duracao_mod * pl.col("pu"))

pyield-0.48.5/pyield/__about__.py

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

pyield-0.48.5/pyield/bc/ptax.py

@@ -1,196 +0,0 @@
-"""
-Módulo para acessar a API de cotações PTAX do Banco Central do Brasil (BCB)
-
-Exemplo de chamada à API:
-    https://olinda.bcb.gov.br/olinda/servico/PTAX/versao/v1/odata/CotacaoDolarPeriodo(dataInicial=@dataInicial,dataFinalCotacao=@dataFinalCotacao)?@dataInicial='09-01-2025'&@dataFinalCotacao='09-10-2025'&$format=text/csv
-
-Exemplo de resposta CSV da API do BCB:
-cotacaoCompra, cotacaoVenda, dataHoraCotacao
-2814         , 2828        , 1984-12-03 11:29:00.0
-2814         , 2828        , 1984-12-03 16:38:00.0
-2867         , 2881        , 1984-12-04 11:17:00.0
-"0,843"      , "0,845"     , 1995-01-02 18:20:00.0
-...
-"5,4272"     , "5,4278"    , 2025-09-08 13:09:40.608
-"5,4272"     , "5,4278"    , 2025-09-09 13:07:27.786
-"5,4117"     , "5,4123"    , 2025-09-10 13:06:29.196
-
-ATENÇÃO: a fração de segundo varia entre .0 (datas antigas) e .608
-(datas recentes). Usar %.f (variável) no parsing, nunca %.3f (fixo).
-"""
-
-import datetime as dt
-
-import polars as pl
-import requests
-
-import pyield._internal.converters as cv
-from pyield import relogio
-from pyield._internal.br_numbers import float_br
-from pyield._internal.cache import ttl_cache
-from pyield._internal.retry import retry_padrao
-from pyield._internal.types import DateLike
-
-URL_API_PTAX = "https://olinda.bcb.gov.br/olinda/servico/PTAX/versao/v1/odata/CotacaoDolarPeriodo(dataInicial=@dataInicial,dataFinalCotacao=@dataFinalCotacao)?"
-
-
-def _montar_url_api(inicio: dt.date, fim: dt.date) -> str:
-    inicio_str = inicio.strftime("%m-%d-%Y")
-    fim_str = fim.strftime("%m-%d-%Y")
-    return (
-        f"{URL_API_PTAX}"
-        f"@dataInicial='{inicio_str}'"
-        f"&@dataFinalCotacao='{fim_str}'"
-        f"&$format=text/csv"
-    )
-
-
-@ttl_cache()
-@retry_padrao
-def _buscar_texto_api(url: str) -> bytes:
-    resposta = requests.get(url, timeout=10)
-    resposta.raise_for_status()
-    return resposta.content
-
-
-def _parsear_df(conteudo_csv: bytes) -> pl.DataFrame:
-    """Lê o CSV bruto da API PTAX em DataFrame com todas as colunas como string."""
-    return pl.read_csv(conteudo_csv, infer_schema=False)
-
-
-def _processar_df(df: pl.DataFrame) -> pl.DataFrame:
-    return (
-        df.with_columns(
-            cotacao_compra=float_br("cotacaoCompra"),
-            cotacao_venda=float_br("cotacaoVenda"),
-            data_hora=pl.col("dataHoraCotacao").str.to_datetime(
-                format="%Y-%m-%d %H:%M:%S%.f", strict=False
-            ),
-        )
-        .with_columns(
-            data=pl.col("data_hora").cast(pl.Date),
-            hora=pl.col("data_hora").dt.time(),
-            cotacao_media=pl.mean_horizontal("cotacao_compra", "cotacao_venda").round(
-                5
-            ),
-        )
-        .sort("data_hora")
-        .unique(subset=["data"], keep="last")
-        .select("data", "hora", "cotacao_compra", "cotacao_venda", "cotacao_media")
-        .sort("data")
-    )
-
-
-def ptax_serie(
-    inicio: DateLike | None = None,
-    fim: DateLike | None = None,
-) -> pl.DataFrame:
-    """Cotações de fechamento do Dólar PTAX (taxa de câmbio).
-
-    Fonte: Banco Central do Brasil (BCB). Frequência diária.
-
-    Se `inicio` não for informada, usa 28.11.1984 (primeira data
-    disponível). Se `fim` não for informada, usa a data de hoje.
-
-    Args:
-        inicio: Data de início da consulta. Padrão é ``None``.
-        fim: Data de fim da consulta. Padrão é ``None``.
-
-    Returns:
-        DataFrame com as cotações do período, ou DataFrame vazio
-        se não houver dados.
-
-    Output Columns:
-        * data (Date): data da cotação.
-        * hora (Time): hora da cotação.
-        * cotacao_compra (Float64): taxa de compra em R$.
-        * cotacao_venda (Float64): taxa de venda em R$.
-        * cotacao_media (Float64): média de compra/venda (5 casas).
-
-    Notes:
-        Disponível desde 28.11.1984; refere-se às taxas
-        administradas até março de 1990 e às taxas livres a
-        partir de então (Resolução 1690, de 18.3.1990). A
-        partir de março de 1992, essa taxa recebeu a
-        denominação PTAX. Desde 1 de julho de 2011 (Circular
-        3506), a PTAX corresponde à média aritmética das
-        taxas obtidas em quatro consultas diárias aos dealers
-        de câmbio.
-
-        Documentação da API:
-        https://olinda.bcb.gov.br/olinda/servico/PTAX/versao/v1/documentacao
-
-    Examples:
-        >>> from pyield import bc
-        >>> bc.ptax_serie(inicio="20-04-2025", fim="25-04-2025")
-        shape: (4, 5)
-        ┌────────────┬──────────────┬────────────────┬───────────────┬───────────────┐
-        │ data       ┆ hora         ┆ cotacao_compra ┆ cotacao_venda ┆ cotacao_media │
-        │ ---        ┆ ---          ┆ ---            ┆ ---           ┆ ---           │
-        │ date       ┆ time         ┆ f64            ┆ f64           ┆ f64           │
-        ╞════════════╪══════════════╪════════════════╪═══════════════╪═══════════════╡
-        │ 2025-04-22 ┆ 13:09:35.629 ┆ 5.749          ┆ 5.7496        ┆ 5.7493        │
-        │ 2025-04-23 ┆ 13:06:30.443 ┆ 5.6874         ┆ 5.688         ┆ 5.6877        │
-        │ 2025-04-24 ┆ 13:04:29.639 ┆ 5.6732         ┆ 5.6738        ┆ 5.6735        │
-        │ 2025-04-25 ┆ 13:09:26.592 ┆ 5.684          ┆ 5.6846        ┆ 5.6843        │
-        └────────────┴──────────────┴────────────────┴───────────────┴───────────────┘
-
-        >>> bc.ptax_serie(inicio="02-01-1995", fim="06-01-1995")
-        shape: (5, 5)
-        ┌────────────┬──────────┬────────────────┬───────────────┬───────────────┐
-        │ data       ┆ hora     ┆ cotacao_compra ┆ cotacao_venda ┆ cotacao_media │
-        │ ---        ┆ ---      ┆ ---            ┆ ---           ┆ ---           │
-        │ date       ┆ time     ┆ f64            ┆ f64           ┆ f64           │
-        ╞════════════╪══════════╪════════════════╪═══════════════╪═══════════════╡
-        │ 1995-01-02 ┆ 18:20:00 ┆ 0.843          ┆ 0.845         ┆ 0.844         │
-        │ 1995-01-03 ┆ 18:25:00 ┆ 0.844          ┆ 0.846         ┆ 0.845         │
-        │ 1995-01-04 ┆ 18:12:00 ┆ 0.844          ┆ 0.846         ┆ 0.845         │
-        │ 1995-01-05 ┆ 18:07:00 ┆ 0.842          ┆ 0.844         ┆ 0.843         │
-        │ 1995-01-06 ┆ 18:12:00 ┆ 0.839          ┆ 0.841         ┆ 0.84          │
-        └────────────┴──────────┴────────────────┴───────────────┴───────────────┘
-    """
-    if inicio:
-        inicio = cv.converter_datas(inicio)
-    else:
-        inicio = dt.date(1984, 11, 28)
-
-    if fim:
-        fim = cv.converter_datas(fim)
-    else:
-        fim = relogio.hoje()
-
-    url = _montar_url_api(inicio, fim)
-    texto = _buscar_texto_api(url)
-    df = _parsear_df(texto)
-    if df.is_empty():
-        return pl.DataFrame()
-    return _processar_df(df)
-
-
-def ptax(data: DateLike) -> float:
-    """Cotação PTAX média de fechamento para uma data específica.
-
-    Args:
-        data: Data desejada.
-
-    Returns:
-        Taxa média (cotacao_media) do dia, ou ``nan`` se não
-        houver cotação (feriado, fim de semana ou data futura).
-
-    Examples:
-        >>> from pyield import bc
-        >>> # Busca a PTAX para um dia útil
-        >>> bc.ptax("22-08-2025")
-        5.4389
-
-        >>> # Busca a PTAX para um fim de semana (sem dados)
-        >>> bc.ptax("23-08-2025")
-        nan
-    """
-    dados_ptax = ptax_serie(
-        inicio=data,
-        fim=data,
-    )
-    if dados_ptax.is_empty():
-        return float("nan")
-    return dados_ptax["cotacao_media"].item(0)