pyield 0.48.4__tar.gz → 0.48.6__tar.gz

{pyield-0.48.4 → pyield-0.48.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyield
-Version: 0.48.4
+Version: 0.48.6
 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.6/pyield/__about__.py

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

{pyield-0.48.4 → pyield-0.48.6}/pyield/b3/di_over.py

@@ -9,46 +9,29 @@ Formato do arquivo (ex.: 20250228.txt):
 Notas de implementação:
     - O valor "00001315" representa 1315 / 10^4 = 0.1315 (13,15% a.a.).
     - Arquivos ausentes (feriados/fins de semana) retornam erro FTP 550.
+    - Série disponível a partir de 20/08/2012 (primeiro arquivo no FTP).
 """
 
+import datetime as dt
 import ftplib
 import logging
 
+from pyield._internal.cache import ttl_cache
 from pyield._internal.converters import converter_datas
 from pyield._internal.types import DateLike, any_is_empty
 
 registro = logging.getLogger(__name__)
 
+# Primeiro arquivo disponível no FTP da CETIP
+DATA_INICIO = dt.date(2012, 8, 20)
+
 # 4 casas decimais na taxa = 2 casas decimais em percentual
 CASAS_DECIMAIS_DI_OVER = 4
 
 
-def di_over(data: DateLike) -> float:
-    """Obtém a taxa DI over via FTP da B3/CETIP.
-
-    Busca o arquivo de taxa DI (Depósito Interfinanceiro) no servidor
-    FTP da CETIP para a data informada.
-
-    Args:
-        data: data da consulta para buscar a taxa DI.
-
-    Returns:
-        Taxa DI para a data especificada (ex: 0.1315 para 13,15%).
-        Retorna ``nan`` se a data for feriado ou fim de semana.
-
-    Examples:
-        >>> di_over("28/02/2025")
-        0.1315
-        >>> di_over("01/01/2025")  # Feriado
-        nan
-    """
-    if any_is_empty(data):
-        return float("nan")
-
-    # Converte a data para o formato esperado do arquivo: YYYYMMDD.txt
-    data_ref = converter_datas(data)
-    nome_arquivo = data_ref.strftime("%Y%m%d.txt")
-
+@ttl_cache()
+def _buscar_taxa(nome_arquivo: str) -> float:
+    """Busca a taxa DI no FTP da CETIP para o arquivo informado."""
     try:
         with ftplib.FTP("ftp.cetip.com.br", timeout=10) as ftp:
             ftp.login()
@@ -75,3 +58,34 @@ def di_over(data: DateLike) -> float:
     except ftplib.all_errors as e:
         registro.error("Erro de conexão ou transferência FTP: %s", e)
         raise ConnectionError(f"Falha ao buscar taxa DI via FTP: {e}") from e
+
+
+def di_over(data: DateLike) -> float:
+    """Obtém a taxa DI over via FTP da B3/CETIP.
+
+    Busca o arquivo de taxa DI (Depósito Interfinanceiro) no servidor
+    FTP da CETIP para a data informada.
+
+    Args:
+        data: data da consulta para buscar a taxa DI.
+
+    Returns:
+        Taxa DI para a data especificada (ex: 0.1315 para 13,15%).
+        Retorna ``nan`` se a data for feriado, fim de semana ou
+        anterior a 20/08/2012 (início da série no FTP).
+
+    Examples:
+        >>> di_over("28/02/2025")
+        0.1315
+        >>> di_over("01/01/2025")  # Feriado
+        nan
+    """
+    if any_is_empty(data):
+        return float("nan")
+
+    data_ref = converter_datas(data)
+    if data_ref < DATA_INICIO:
+        return float("nan")
+
+    nome_arquivo = data_ref.strftime("%Y%m%d.txt")
+    return _buscar_taxa(nome_arquivo)

{pyield-0.48.4 → pyield-0.48.6}/pyield/bc/__init__.py

@@ -1,10 +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.taxas import (
-    di_over,
-    di_over_serie,
+from pyield.bc.sgs import (
+    ptax,
+    ptax_serie,
     selic_meta,
     selic_meta_serie,
     selic_over,
@@ -17,8 +16,6 @@ from pyield.bc.vna import vna_lft
 __all__ = [
     "copom",
     "compromissada",
-    "di_over",
-    "di_over_serie",
     "leiloes",
     "ptax_serie",
     "compromissadas",

{pyield-0.48.4 → pyield-0.48.6}/pyield/bc/leiloes.py

@@ -19,7 +19,7 @@ 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.sgs import ptax_serie
 from pyield.tn.ntnb import duration as duration_b
 from pyield.tn.ntnf import duration as duration_f
 
@@ -240,8 +240,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")
     )
 

pyield-0.48.6/pyield/bc/sgs.py

@@ -0,0 +1,386 @@
+"""Séries do Sistema Gerenciador de Séries (SGS) do Banco Central.
+
+Séries disponíveis:
+    - 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:
+    [{"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:
+    - 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
+from enum import Enum
+
+import polars as pl
+import requests
+
+from pyield import relogio
+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 = "https://api.bcb.gov.br/dados/serie/bcdata.sgs."
+
+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 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.raise_for_status()
+    return resposta.json()
+
+
+def _montar_url_intervalo(
+    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}"
+    if fim:
+        url += f"&dataFinal={fim.strftime('%d/%m/%Y')}"
+    return url
+
+
+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 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_BRUTO)
+        raise
+
+    if not dados:
+        return pl.DataFrame(schema=ESQUEMA_BRUTO)
+
+    return pl.from_dicts(dados).select(
+        pl.col("data").str.to_date("%d/%m/%Y"),
+        pl.col("valor").cast(pl.Float64),
+    )
+
+
+def _buscar_dados_url(
+    serie: SerieSGS,
+    inicio: DateLike,
+    fim: DateLike | None = None,
+) -> pl.DataFrame:
+    """Orquestra a busca, dividindo intervalos > 10 anos em blocos."""
+    data_inicio = converter_datas(inicio)
+    data_fim = converter_datas(fim) if fim else relogio.hoje()
+
+    if (data_fim - data_inicio).days < LIMITE_DIAS_SEGURO:
+        return _buscar_api(_montar_url_intervalo(serie, data_inicio, data_fim))
+
+    inicios = pl.date_range(start=data_inicio, end=data_fim, interval="10y", eager=True)
+    fins = inicios.dt.offset_by("10y").clip(upper_bound=data_fim)
+
+    todos_dfs = [
+        _buscar_api(_montar_url_intervalo(serie, ini, fim))
+        for ini, fim in zip(inicios, fins)
+    ]
+
+    todos_dfs = [df for df in todos_dfs if not df.is_empty()]
+
+    if not todos_dfs:
+        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,
+    *,
+    ultimos: int | None = None,
+) -> pl.DataFrame:
+    """Taxa SELIC Over (série SGS 1178).
+
+    Taxa de juros média diária praticada no mercado interbancário,
+    com títulos públicos como garantia.
+
+    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 taxa, ou DataFrame vazio.
+
+    Examples:
+        >>> from pyield import bc
+        >>> # Sem dados em 26-01-2025 (domingo). Selic mudou por reunião do Copom.
+        >>> bc.selic_over_serie("26-01-2025").head(5)  # Primeiras 5 linhas
+        shape: (5, 2)
+        ┌────────────┬────────┐
+        │ data       ┆ taxa   │
+        │ ---        ┆ ---    │
+        │ date       ┆ f64    │
+        ╞════════════╪════════╡
+        │ 2025-01-27 ┆ 0.1215 │
+        │ 2025-01-28 ┆ 0.1215 │
+        │ 2025-01-29 ┆ 0.1215 │
+        │ 2025-01-30 ┆ 0.1315 │
+        │ 2025-01-31 ┆ 0.1315 │
+        └────────────┴────────┘
+
+        >>> # Buscando dados para um intervalo específico
+        >>> bc.selic_over_serie("14-09-2025", "17-09-2025")
+        shape: (3, 2)
+        ┌────────────┬───────┐
+        │ data       ┆ taxa  │
+        │ ---        ┆ ---   │
+        │ date       ┆ f64   │
+        ╞════════════╪═══════╡
+        │ 2025-09-15 ┆ 0.149 │
+        │ 2025-09-16 ┆ 0.149 │
+        │ 2025-09-17 ┆ 0.149 │
+        └────────────┴───────┘
+    """
+    return _converter_para_taxa(
+        _buscar_serie(SerieSGS.SELIC_OVER, inicio, fim, ultimos)
+    )
+
+
+def selic_over(data: DateLike) -> float:
+    """Taxa SELIC Over para uma data específica.
+
+    Args:
+        data: Data da consulta.
+
+    Returns:
+        Taxa SELIC Over ou ``nan`` se não disponível.
+
+    Examples:
+        >>> from pyield import bc
+        >>> bc.selic_over("31-05-2024")
+        0.104
+    """
+    if any_is_empty(data):
+        return float("nan")
+    return _extrair_escalar(selic_over_serie(data, data), "taxa")
+
+
+# ── SELIC Meta ───────────────────────────────────────────────────────
+
+
+def selic_meta_serie(
+    inicio: DateLike | None = None,
+    fim: DateLike | None = None,
+    *,
+    ultimos: int | None = None,
+) -> pl.DataFrame:
+    """Taxa SELIC Meta (série SGS 432).
+
+    Taxa de juros oficial definida pelo COPOM.
+
+    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 taxa, ou DataFrame vazio.
+
+    Examples:
+        >>> from pyield import bc
+        >>> bc.selic_meta_serie("31-05-2024", "31-05-2024")
+        shape: (1, 2)
+        ┌────────────┬───────┐
+        │ data       ┆ taxa  │
+        │ ---        ┆ ---   │
+        │ date       ┆ f64   │
+        ╞════════════╪═══════╡
+        │ 2024-05-31 ┆ 0.105 │
+        └────────────┴───────┘
+    """
+    return _converter_para_taxa(
+        _buscar_serie(SerieSGS.SELIC_META, inicio, fim, ultimos)
+    )
+
+
+def selic_meta(data: DateLike) -> float:
+    """Taxa SELIC Meta para uma data específica.
+
+    Args:
+        data: Data da consulta.
+
+    Returns:
+        Taxa SELIC Meta ou ``nan`` se não disponível.
+
+    Examples:
+        >>> from pyield import bc
+        >>> bc.selic_meta("31-05-2024")
+        0.105
+    """
+    if any_is_empty(data):
+        return float("nan")
+    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.4 → pyield-0.48.6}/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.4 → pyield-0.48.6}/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.4/pyield/__about__.py

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

pyield-0.48.4/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)

pyield-0.48.4/pyield/bc/taxas.py

@@ -1,317 +0,0 @@
-"""Taxas de juros do Banco Central do Brasil (séries SGS).
-
-Séries disponíveis:
-    - SELIC Over (SGS 1178)
-    - SELIC Meta (SGS 432)
-    - DI Over (SGS 11)
-
-Exemplo de chamada à API:
-    https://api.bcb.gov.br/dados/serie/bcdata.sgs.1178/dados?formato=json&dataInicial=29/01/2025&dataFinal=31/01/2025
-
-Exemplo de resposta JSON da API do BCB (valores em percentual):
-    [{"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.
-    - DI Over diária: 8 casas decimais; anualizada: 4 casas decimais.
-    - Intervalos > 10 anos são divididos automaticamente em blocos.
-"""
-
-import datetime as dt
-from enum import Enum
-
-import polars as pl
-import requests
-
-from pyield import relogio
-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
-
-
-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
-CASAS_DECIMAIS_DIARIA = 8  # 6 casas no formato percentual
-
-# 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
-
-
-class SerieBC(Enum):
-    """Enum para as séries disponíveis no Banco Central."""
-
-    SELIC_OVER = 1178
-    SELIC_META = 432
-    DI_OVER = 11
-
-
-@ttl_cache()
-@retry_padrao
-def _chamar_api(url_api: str) -> list[dict[str, str]]:
-    resposta = requests.get(url_api, timeout=10)
-    resposta.raise_for_status()
-    return resposta.json()
-
-
-def _montar_url_download(
-    serie: SerieBC, 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}"
-    if fim:
-        url += f"&dataFinal={fim.strftime('%d/%m/%Y')}"
-    return url
-
-
-def _buscar_requisicao(
-    serie: SerieBC,
-    inicio: dt.date,
-    fim: dt.date | None,
-) -> pl.DataFrame:
-    """Busca dados da API para um intervalo."""
-    esquema_esperado = {"data": pl.Date, "taxa": pl.Float64}
-    url_api = _montar_url_download(serie, inicio, fim)
-
-    try:
-        dados = _chamar_api(url_api)
-    except requests.exceptions.HTTPError as e:
-        if e.response.status_code == 404:  # noqa
-            return pl.DataFrame(schema=esquema_esperado)
-        raise
-
-    if not dados:
-        return pl.DataFrame(schema=esquema_esperado)
-
-    return pl.from_dicts(dados).select(
-        pl.col("data").str.to_date("%d/%m/%Y"),
-        taxa=pl.col("valor").cast(pl.Float64) / 100,
-    )
-
-
-def _buscar_dados_url(
-    serie: SerieBC,
-    inicio: DateLike,
-    fim: DateLike | None = None,
-) -> pl.DataFrame:
-    """Orquestra a busca, dividindo intervalos > 10 anos em blocos."""
-    data_inicio = converter_datas(inicio)
-    data_fim = converter_datas(fim) if fim else relogio.hoje()
-
-    if (data_fim - data_inicio).days < LIMITE_DIAS_SEGURO:
-        return _buscar_requisicao(serie, data_inicio, data_fim)
-
-    inicios = pl.date_range(start=data_inicio, end=data_fim, interval="10y", eager=True)
-    fins = inicios.dt.offset_by("10y").clip(upper_bound=data_fim)
-
-    todos_dfs = [_buscar_requisicao(serie, ini, fim) for ini, fim in zip(inicios, fins)]
-
-    todos_dfs = [df for df in todos_dfs if not df.is_empty()]
-
-    if not todos_dfs:
-        return pl.DataFrame()
-
-    return pl.concat(todos_dfs).unique(subset=["data"], keep="first").sort("data")
-
-
-def selic_over_serie(
-    inicio: DateLike,
-    fim: DateLike | None = None,
-) -> pl.DataFrame:
-    """Taxa SELIC Over (série SGS 1178).
-
-    Taxa de juros média diária praticada no mercado interbancário,
-    com títulos públicos como garantia.
-
-    Args:
-        inicio: Data inicial.
-        fim: Data final. Se ``None``, usa a data mais recente.
-
-    Returns:
-        DataFrame com colunas data e taxa, ou DataFrame vazio.
-
-    Examples:
-        >>> from pyield import bc
-        >>> # Sem dados em 26-01-2025 (domingo). Selic mudou por reunião do Copom.
-        >>> bc.selic_over_serie("26-01-2025").head(5)  # Primeiras 5 linhas
-        shape: (5, 2)
-        ┌────────────┬────────┐
-        │ data       ┆ taxa   │
-        │ ---        ┆ ---    │
-        │ date       ┆ f64    │
-        ╞════════════╪════════╡
-        │ 2025-01-27 ┆ 0.1215 │
-        │ 2025-01-28 ┆ 0.1215 │
-        │ 2025-01-29 ┆ 0.1215 │
-        │ 2025-01-30 ┆ 0.1315 │
-        │ 2025-01-31 ┆ 0.1315 │
-        └────────────┴────────┘
-
-        >>> # Buscando dados para um intervalo específico
-        >>> bc.selic_over_serie("14-09-2025", "17-09-2025")
-        shape: (3, 2)
-        ┌────────────┬───────┐
-        │ data       ┆ taxa  │
-        │ ---        ┆ ---   │
-        │ date       ┆ f64   │
-        ╞════════════╪═══════╡
-        │ 2025-09-15 ┆ 0.149 │
-        │ 2025-09-16 ┆ 0.149 │
-        │ 2025-09-17 ┆ 0.149 │
-        └────────────┴───────┘
-    """
-    if any_is_empty(inicio):
-        return pl.DataFrame()
-    df = _buscar_dados_url(SerieBC.SELIC_OVER, inicio, fim)
-    return df.with_columns(pl.col("taxa").round(CASAS_DECIMAIS_ANUALIZADA))
-
-
-def selic_over(data: DateLike) -> float:
-    """Taxa SELIC Over para uma data específica.
-
-    Args:
-        data: Data da consulta.
-
-    Returns:
-        Taxa SELIC Over ou ``nan`` se não disponível.
-
-    Examples:
-        >>> from pyield import bc
-        >>> bc.selic_over("31-05-2024")
-        0.104
-    """
-    if any_is_empty(data):
-        return float("nan")
-    return _extrair_taxa(selic_over_serie(data, data))
-
-
-def selic_meta_serie(
-    inicio: DateLike,
-    fim: DateLike | None = None,
-) -> pl.DataFrame:
-    """Taxa SELIC Meta (série SGS 432).
-
-    Taxa de juros oficial definida pelo COPOM.
-
-    Args:
-        inicio: Data inicial.
-        fim: Data final. Se ``None``, usa a data mais recente.
-
-    Returns:
-        DataFrame com colunas data e taxa, ou DataFrame vazio.
-
-    Examples:
-        >>> from pyield import bc
-        >>> bc.selic_meta_serie("31-05-2024", "31-05-2024")
-        shape: (1, 2)
-        ┌────────────┬───────┐
-        │ data       ┆ taxa  │
-        │ ---        ┆ ---   │
-        │ date       ┆ f64   │
-        ╞════════════╪═══════╡
-        │ 2024-05-31 ┆ 0.105 │
-        └────────────┴───────┘
-    """
-    if any_is_empty(inicio):
-        return pl.DataFrame()
-    df = _buscar_dados_url(SerieBC.SELIC_META, inicio, fim)
-    return df.with_columns(pl.col("taxa").round(CASAS_DECIMAIS_ANUALIZADA))
-
-
-def selic_meta(data: DateLike) -> float:
-    """Taxa SELIC Meta para uma data específica.
-
-    Args:
-        data: Data da consulta.
-
-    Returns:
-        Taxa SELIC Meta ou ``nan`` se não disponível.
-
-    Examples:
-        >>> from pyield import bc
-        >>> bc.selic_meta("31-05-2024")
-        0.105
-    """
-    if any_is_empty(data):
-        return float("nan")
-    return _extrair_taxa(selic_meta_serie(data, data))
-
-
-def di_over_serie(
-    inicio: DateLike,
-    fim: DateLike | None = None,
-    anualizada: bool = True,
-) -> pl.DataFrame:
-    """Taxa DI Over (série SGS 11).
-
-    Taxa de juros média dos empréstimos interbancários.
-
-    Args:
-        inicio: Data inicial.
-        fim: Data final. Se ``None``, usa a data mais recente.
-        anualizada: Se ``True``, retorna a taxa anualizada (base
-            252 d.u.). Caso contrário, retorna a taxa diária.
-
-    Returns:
-        DataFrame com colunas data e taxa, ou DataFrame vazio.
-
-    Examples:
-        >>> from pyield import bc
-        >>> # Retorna todos os dados desde 29-01-2025
-        >>> bc.di_over_serie("29-01-2025").head(5)  # Primeiras 5 linhas
-        shape: (5, 2)
-        ┌────────────┬────────┐
-        │ data       ┆ taxa   │
-        │ ---        ┆ ---    │
-        │ date       ┆ f64    │
-        ╞════════════╪════════╡
-        │ 2025-01-29 ┆ 0.1215 │
-        │ 2025-01-30 ┆ 0.1315 │
-        │ 2025-01-31 ┆ 0.1315 │
-        │ 2025-02-03 ┆ 0.1315 │
-        │ 2025-02-04 ┆ 0.1315 │
-        └────────────┴────────┘
-    """
-    if any_is_empty(inicio):
-        return pl.DataFrame()
-    df = _buscar_dados_url(SerieBC.DI_OVER, inicio, fim)
-    if anualizada:
-        return df.with_columns(
-            taxa=(((pl.col("taxa") + 1).pow(252)) - 1).round(CASAS_DECIMAIS_ANUALIZADA)
-        )
-    return df.with_columns(taxa=pl.col("taxa").round(CASAS_DECIMAIS_DIARIA))
-
-
-def di_over(data: DateLike, anualizada: bool = True) -> float:
-    """Taxa DI Over para uma data específica.
-
-    Args:
-        data: Data da consulta.
-        anualizada: Se ``True``, retorna a taxa anualizada (base
-            252 d.u.). Caso contrário, retorna a taxa diária.
-
-    Returns:
-        Taxa DI Over ou ``nan`` se não disponível.
-
-    Examples:
-        >>> from pyield import bc
-        >>> bc.di_over("31-05-2024")
-        0.104
-
-        >>> bc.di_over("28-01-2025", anualizada=False)
-        0.00045513
-    """
-    if any_is_empty(data):
-        return float("nan")
-    return _extrair_taxa(di_over_serie(data, data, anualizada))