pyield 0.58.1__tar.gz → 0.59.0__tar.gz

{pyield-0.58.1 → pyield-0.59.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyield
-Version: 0.58.1
+Version: 0.59.0
 Summary: Polars-powered toolkit for Brazilian fixed income analysis
 Keywords: fixed-income,brazil,finance,analysis,bonds
 Author: Carlos Carvalho
@@ -76,7 +76,7 @@ uv add pyield
 | `yd.forwards(...)` | função | Curva de taxas a termo | |
 | `yd.futuro` | módulo | Contratos futuros da B3 | `di1`, `historico`, `intradia`, `datas_disponiveis`, `vencimento`, `enriquecer`, `vencimento_expr` |
 | `yd.di1` | módulo | Curva DI1 e interpolação | `dados`, `interpolar_taxas`, `interpolar_taxa`, `datas_disponiveis` |
-| `yd.tpf` | módulo | Títulos públicos federais | `taxas`, `taxas_historicas`, `vencimentos`, `estoque`, `leiloes`, `benchmarks`, `curva_pre`, `premios_pre`, `secundario` |
+| `yd.tpf` | módulo | Títulos públicos federais | `taxas`, `taxas_historicas`, `vencimentos`, `estoque`, `leiloes`, `leiloes_bcb`, `benchmarks`, `curva_pre`, `premios_pre`, `secundario` |
 | `yd.rmd(aba)` | função | Relatório Mensal da Dívida do Tesouro Nacional | |
 | `yd.lft` | módulo | LFT | `dados`, `vencimentos`, `cotacao`, `pu`, `taxa`, `rentabilidade`, `rentabilidade_expr` |
 | `yd.ltn` | módulo | LTN | `dados`, `vencimentos`, `pu`, `taxa`, `duration_expr`, `dv01`, `dv01_expr`, `rentabilidade`, `rentabilidade_expr`, `taxas_forward` |
@@ -89,8 +89,9 @@ uv add pyield
 | `yd.copom` | módulo | Calendário automático do Copom | `calendario`, `proxima_reuniao` |
 | `yd.compromissadas(...)` | função | Leilões de operações compromissadas do BCB | `inicio`, `fim` |
 | `yd.selic` | módulo | Selic e política monetária | `over`, `over_serie`, `meta`, `meta_serie` |
-| `yd.cpm` | módulo | Opções digitais do COPOM e análises derivadas | `data`, `probabilidades` |
-| `yd.ipca` | módulo | IPCA histórico e projetado | `indice`, `indices`, `indices_ultimos`, `taxa`, `taxas`, `taxas_ultimas`, `taxa_projetada` |
+| `yd.cpm` | módulo | Opções digitais do COPOM e análises derivadas | `contratos`, `probabilidades` |
+| `yd.ipca` | módulo | IPCA histórico e projetado | `indice`, `indice_serie`, `taxa`, `taxa_serie`, `taxa_projetada` |
+| `yd.igpm` | módulo | Taxas mensais do IGP-M via SGS/BCB | `taxa`, `taxa_serie` |
 | `yd.ptax(data)` | função | PTAX para uma data | |
 | `yd.ptax_serie(inicio, fim)` | função | Série histórica da PTAX | |
 | `yd.di_over(data)` | função | Taxa DI Over | |
@@ -102,6 +103,35 @@ documentação detalhada e as assinaturas públicas.
 
 ## Compatibilidade da API
 
+### Séries do IPCA
+
+As consultas históricas do IPCA seguem o padrão das séries de Selic e PTAX:
+`taxa(data)` e `indice(data)` retornam um valor; `taxa_serie` e `indice_serie`
+retornam séries por intervalo ou pelos últimos meses.
+
+Para migrar, substitua `ipca.taxas(inicio, fim)` por
+`ipca.taxa_serie(inicio, fim)` e `ipca.indices(inicio, fim)` por
+`ipca.indice_serie(inicio, fim)`. Substitua `ipca.taxas_ultimas(n)` por
+`ipca.taxa_serie(ultimos=n)` e `ipca.indices_ultimos(n)` por
+`ipca.indice_serie(ultimos=n)`. Os nomes antigos foram removidos; colunas,
+unidades e valores retornados permanecem iguais.
+
+Nas séries, `fim=None` usa a data atual no Brasil. Informe `inicio` ou
+`ultimos`; quando informado, `ultimos` tem prioridade sobre as datas.
+`taxa_projetada` permanece inalterada.
+
+### Taxas e DV01 analíticos — 0.59.0
+
+As funções `taxa` de `yd.ltn`, `yd.ntnf`, `yd.ntnb`, `yd.ntnc` e `yd.lft`
+passam a retornar `float` sem truncamento, em vez de `Decimal` truncado em oito
+casas. Entradas inválidas retornam `float("nan")`; use `math.isnan` no lugar de
+`.is_nan()`.
+
+`taxa` e `dv01` de todos os títulos descontam os fluxos com `dias úteis / 252`,
+sem os truncamentos intermediários da STN. Os valores mudam levemente em
+relação à versão anterior, e `taxa(pu(...))` recupera a taxa original apenas
+aproximadamente. `pu` e `cotacao` seguem a metodologia oficial e não mudaram.
+
 ### Cotações em base 100 — 0.58.0
 
 As funções escalares de cálculo dos títulos também aceitam taxas percentuais

{pyield-0.58.1 → pyield-0.59.0}/README.md

@@ -51,7 +51,7 @@ uv add pyield
 | `yd.forwards(...)` | função | Curva de taxas a termo | |
 | `yd.futuro` | módulo | Contratos futuros da B3 | `di1`, `historico`, `intradia`, `datas_disponiveis`, `vencimento`, `enriquecer`, `vencimento_expr` |
 | `yd.di1` | módulo | Curva DI1 e interpolação | `dados`, `interpolar_taxas`, `interpolar_taxa`, `datas_disponiveis` |
-| `yd.tpf` | módulo | Títulos públicos federais | `taxas`, `taxas_historicas`, `vencimentos`, `estoque`, `leiloes`, `benchmarks`, `curva_pre`, `premios_pre`, `secundario` |
+| `yd.tpf` | módulo | Títulos públicos federais | `taxas`, `taxas_historicas`, `vencimentos`, `estoque`, `leiloes`, `leiloes_bcb`, `benchmarks`, `curva_pre`, `premios_pre`, `secundario` |
 | `yd.rmd(aba)` | função | Relatório Mensal da Dívida do Tesouro Nacional | |
 | `yd.lft` | módulo | LFT | `dados`, `vencimentos`, `cotacao`, `pu`, `taxa`, `rentabilidade`, `rentabilidade_expr` |
 | `yd.ltn` | módulo | LTN | `dados`, `vencimentos`, `pu`, `taxa`, `duration_expr`, `dv01`, `dv01_expr`, `rentabilidade`, `rentabilidade_expr`, `taxas_forward` |
@@ -64,8 +64,9 @@ uv add pyield
 | `yd.copom` | módulo | Calendário automático do Copom | `calendario`, `proxima_reuniao` |
 | `yd.compromissadas(...)` | função | Leilões de operações compromissadas do BCB | `inicio`, `fim` |
 | `yd.selic` | módulo | Selic e política monetária | `over`, `over_serie`, `meta`, `meta_serie` |
-| `yd.cpm` | módulo | Opções digitais do COPOM e análises derivadas | `data`, `probabilidades` |
-| `yd.ipca` | módulo | IPCA histórico e projetado | `indice`, `indices`, `indices_ultimos`, `taxa`, `taxas`, `taxas_ultimas`, `taxa_projetada` |
+| `yd.cpm` | módulo | Opções digitais do COPOM e análises derivadas | `contratos`, `probabilidades` |
+| `yd.ipca` | módulo | IPCA histórico e projetado | `indice`, `indice_serie`, `taxa`, `taxa_serie`, `taxa_projetada` |
+| `yd.igpm` | módulo | Taxas mensais do IGP-M via SGS/BCB | `taxa`, `taxa_serie` |
 | `yd.ptax(data)` | função | PTAX para uma data | |
 | `yd.ptax_serie(inicio, fim)` | função | Série histórica da PTAX | |
 | `yd.di_over(data)` | função | Taxa DI Over | |
@@ -77,6 +78,35 @@ documentação detalhada e as assinaturas públicas.
 
 ## Compatibilidade da API
 
+### Séries do IPCA
+
+As consultas históricas do IPCA seguem o padrão das séries de Selic e PTAX:
+`taxa(data)` e `indice(data)` retornam um valor; `taxa_serie` e `indice_serie`
+retornam séries por intervalo ou pelos últimos meses.
+
+Para migrar, substitua `ipca.taxas(inicio, fim)` por
+`ipca.taxa_serie(inicio, fim)` e `ipca.indices(inicio, fim)` por
+`ipca.indice_serie(inicio, fim)`. Substitua `ipca.taxas_ultimas(n)` por
+`ipca.taxa_serie(ultimos=n)` e `ipca.indices_ultimos(n)` por
+`ipca.indice_serie(ultimos=n)`. Os nomes antigos foram removidos; colunas,
+unidades e valores retornados permanecem iguais.
+
+Nas séries, `fim=None` usa a data atual no Brasil. Informe `inicio` ou
+`ultimos`; quando informado, `ultimos` tem prioridade sobre as datas.
+`taxa_projetada` permanece inalterada.
+
+### Taxas e DV01 analíticos — 0.59.0
+
+As funções `taxa` de `yd.ltn`, `yd.ntnf`, `yd.ntnb`, `yd.ntnc` e `yd.lft`
+passam a retornar `float` sem truncamento, em vez de `Decimal` truncado em oito
+casas. Entradas inválidas retornam `float("nan")`; use `math.isnan` no lugar de
+`.is_nan()`.
+
+`taxa` e `dv01` de todos os títulos descontam os fluxos com `dias úteis / 252`,
+sem os truncamentos intermediários da STN. Os valores mudam levemente em
+relação à versão anterior, e `taxa(pu(...))` recupera a taxa original apenas
+aproximadamente. `pu` e `cotacao` seguem a metodologia oficial e não mudaram.
+
 ### Cotações em base 100 — 0.58.0
 
 As funções escalares de cálculo dos títulos também aceitam taxas percentuais

{pyield-0.58.1 → pyield-0.59.0}/pyield/__init__.py

@@ -3,7 +3,7 @@
 import logging
 from importlib.metadata import PackageNotFoundError, version
 
-from pyield import b3, du, ipca
+from pyield import b3, du, igpm, ipca
 from pyield.b3.di_over import di_over
 from pyield import futuro
 from pyield.futuro import di1
@@ -39,6 +39,7 @@ __all__ = [
     "forwards_expr",
     "futuro",
     "hoje",
+    "igpm",
     "Interpolador",
     "interpolar",
     "ipca",

{pyield-0.58.1 → pyield-0.59.0}/pyield/bc/sgs.py

@@ -1,6 +1,7 @@
 """Séries do Sistema Gerenciador de Séries (SGS) do Banco Central.
 
 Séries disponíveis:
+    - IGP-M mensal (SGS 189)
     - PTAX Venda (SGS 1)
     - SELIC Diária (SGS 11)
     - SELIC Meta (SGS 432)
@@ -56,6 +57,7 @@ class SerieSGS(Enum):
 
     PTAX_VENDA = 1
     SELIC_DIARIA = 11
+    IGPM = 189
     SELIC_META = 432
     SELIC_OVER = 1178
 
@@ -184,6 +186,74 @@ def _extrair_escalar(df: pl.DataFrame, coluna: str) -> float:
     return df[coluna].item(0)
 
 
+def igpm_taxa_serie(
+    inicio: DateLike | None = None,
+    fim: DateLike | None = None,
+    *,
+    ultimos: int | None = None,
+) -> pl.DataFrame:
+    """Obtém as taxas mensais do IGP-M via SGS do Banco Central (série 189).
+
+    O índice é produzido pela FGV. A série representa a variação mensal,
+    não o número-índice nem a variação acumulada em 12 meses.
+
+    Args:
+        inicio: Qualquer data no primeiro mês do intervalo.
+        fim: Qualquer data no último mês do intervalo. Se ``None``, usa a
+            data atual no Brasil.
+        ultimos: Número de meses mais recentes a recuperar. Se informado,
+            tem prioridade sobre ``inicio`` e ``fim``.
+
+    Returns:
+        DataFrame com as taxas mensais em decimal, ou vazio se não houver dados.
+
+    Output Columns:
+        * periodo (Int64): competência mensal no formato YYYYMM.
+        * taxa (Float64): variação mensal em decimal (0.005 = 0,50%).
+
+    Raises:
+        ValueError: Se não informar ``inicio`` nem ``ultimos``, ou se
+            ``ultimos`` for menor ou igual a 0.
+
+    Examples:
+        >>> df = yd.igpm.taxa_serie("01-01-2025", "31-03-2025")
+        >>> df = yd.igpm.taxa_serie(ultimos=12)
+    """
+    if ultimos is not None:
+        if ultimos <= 0:
+            raise ValueError("O número de meses deve ser maior que 0.")
+    else:
+        if inicio is None:
+            raise ValueError("Informe 'inicio' ou 'ultimos'.")
+        inicio = converter_datas(inicio).replace(day=1)
+        fim = converter_datas(fim).replace(day=1) if fim is not None else None
+    return (
+        _buscar_serie(SerieSGS.IGPM, inicio, fim, ultimos)
+        .select(
+            periodo=pl.col("data").dt.strftime("%Y%m").cast(pl.Int64),
+            taxa=pct_para_decimal(pl.col("valor")),
+        )
+        .sort("periodo")
+    )
+
+
+def igpm_taxa(data: DateLike) -> float:
+    """Taxa mensal do IGP-M via SGS do Banco Central (série 189, fonte FGV).
+
+    Args:
+        data: Qualquer data dentro do mês desejado.
+
+    Returns:
+        Variação mensal em decimal ou ``nan`` se não disponível.
+
+    Examples:
+        >>> taxa = yd.igpm.taxa("15-01-2025")
+    """
+    if any_is_empty(data):
+        return float("nan")
+    return _extrair_escalar(igpm_taxa_serie(data, data), "taxa")
+
+
 # ── SELIC Over ───────────────────────────────────────────────────────
 
 

pyield-0.59.0/pyield/cpm/__init__.py

@@ -0,0 +1,14 @@
+"""CPM: opções digitais da B3 sobre a decisão do COPOM.
+
+Membros:
+    contratos: contratos CPM negociados em uma data.
+    probabilidades: probabilidades implícitas de cada reunião do COPOM.
+"""
+
+from pyield.cpm._contratos import contratos
+from pyield.cpm._probabilidades import probabilidades
+
+__all__ = [
+    "contratos",
+    "probabilidades",
+]

pyield-0.59.0/pyield/cpm/_contratos.py

@@ -0,0 +1,186 @@
+"""Contratos CPM: opções digitais da B3 sobre a decisão do COPOM.
+
+Formato do código de negociação: ``CPM{mes}{ano2}{C|P}{strike6}``, por exemplo
+``CPMZ25C099500``: mês ``Z`` (dezembro), ano 2025, call, strike 99,500. A
+variação da Selic em pontos-base é ``(strike - 100) * 100`` (aqui, -50 bps).
+
+O CPM expira no primeiro dia útil após o fim da reunião do COPOM, e não no
+primeiro dia útil do mês. Por isso, as datas da reunião e de expiração vêm do
+calendário do COPOM, unido pelo mês e ano do código. A junção é ``left`` para
+não descartar contratos de reuniões ainda ausentes do calendário.
+"""
+
+import datetime as dt
+
+import polars as pl
+import requests
+
+from pyield import copom, du
+from pyield._internal.converters import converter_datas
+from pyield._internal.retry import retry_padrao
+from pyield._internal.types import DateLike
+from pyield.b3 import boletim
+from pyield.futuro.contratos import _MAPA_MESES
+
+# Mapeamento mínimo para consumo do módulo CPM a partir do schema XML bruto.
+_RENOMEAR_COLUNAS_CPM = {
+    "TckrSymb": "codigo_negociacao",
+}
+
+
+def _df_vazio() -> pl.DataFrame:
+    return pl.DataFrame(
+        schema={
+            "data_referencia": pl.Date,
+            "codigo_negociacao": pl.String,
+            "data_fim_reuniao": pl.Date,
+            "data_expiracao": pl.Date,
+            "tipo_opcao": pl.String,
+            "variacao_strike_bps": pl.Int32,
+            "preco_ajuste": pl.Float64,
+            "dias_uteis": pl.Int32,
+        }
+    )
+
+
+_CSV_ESQUEMA = {"Instrumento financeiro": pl.String, "Preço de referência": pl.Float64}
+
+
+@retry_padrao
+def _buscar_csv(data: dt.date) -> bytes:
+    """Busca o CSV diário de derivativos consolidados na B3."""
+    url = "https://arquivos.b3.com.br/bdi/table/export/csv"
+    parametros = {"lang": "pt-BR"}
+    data_str = data.strftime("%Y-%m-%d")
+    carga = {
+        "Name": "ConsolidatedTradesDerivatives",
+        "Date": data_str,
+        "FinalDate": data_str,
+        "ClientId": "",
+        "Filters": {},
+    }
+    cabecalhos = {
+        "Content-Type": "application/json",
+        "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",  # noqa: E501
+        "Accept": "application/json, text/plain, */*",
+    }
+    resposta = requests.post(
+        url, params=parametros, json=carga, headers=cabecalhos, timeout=(5, 30)
+    )
+    resposta.raise_for_status()
+    return resposta.content
+
+
+def _parsear_precos_referencia(csv_bytes: bytes) -> pl.DataFrame:
+    """Extrai o Preço de Referência dos contratos CPM do CSV da B3."""
+    try:
+        df = pl.read_csv(
+            csv_bytes.replace(b".", b""),
+            separator=";",
+            skip_lines=2,
+            null_values=["-"],
+            decimal_comma=True,
+            schema_overrides=_CSV_ESQUEMA,
+            encoding="utf-8-sig",
+        )
+    except pl.exceptions.NoDataError:
+        # Para datas antigas, a B3 devolve apenas o cabeçalho, sem preâmbulo.
+        return pl.DataFrame(
+            schema={"codigo_negociacao": pl.String, "preco_ajuste": pl.Float64}
+        )
+
+    return df.select(
+        codigo_negociacao="Instrumento financeiro",
+        preco_ajuste="Preço de referência",
+    ).filter(pl.col("codigo_negociacao").str.starts_with("CPM"))
+
+
+def contratos(data: DateLike) -> pl.DataFrame:
+    """Busca os contratos CPM negociados em uma data.
+
+    Fonte: B3. A lista de contratos vem do boletim de preços (SPR) e o preço de
+    ajuste vem do "Preço de Referência" do boletim de derivativos consolidados,
+    o mesmo exibido no painel "Probabilidades da Taxa Selic Meta" da B3. As
+    datas da reunião e de expiração vêm do calendário do COPOM.
+
+    Args:
+        data: Data de negociação.
+
+    Returns:
+        DataFrame Polars ordenado por ``data_expiracao`` e
+        ``variacao_strike_bps``. Retorna DataFrame vazio, com o schema abaixo,
+        se não houver contratos CPM na data.
+
+    Output Columns:
+        * data_referencia (Date): data de negociação.
+        * codigo_negociacao (String): código do contrato (ex.: ``CPMZ25C099500``).
+        * data_fim_reuniao (Date): último dia da reunião do COPOM.
+        * data_expiracao (Date): primeiro dia útil após ``data_fim_reuniao``,
+            data de liquidação do contrato.
+        * tipo_opcao (String): ``"call"`` ou ``"put"``.
+        * variacao_strike_bps (Int32): variação da Selic Meta, em pontos-base,
+            associada ao strike.
+        * preco_ajuste (Float64): Preço de Referência da B3, em pontos (0–100).
+        * dias_uteis (Int32): dias úteis de ``data_referencia`` até
+            ``data_expiracao``.
+
+    Notes:
+        A B3 só publica o Preço de Referência de datas recentes (cerca de um
+        mês). Para datas mais antigas, ``preco_ajuste`` é nulo.
+
+    Examples:
+        >>> df = yd.cpm.contratos("29-01-2025")  # doctest: +SKIP
+    """
+    data_negociacao = converter_datas(data)
+    df = boletim.buscar(data_negociacao, prefixo_ticker="CPM")
+    if df.is_empty():
+        return _df_vazio()
+
+    df = df.rename(_RENOMEAR_COLUNAS_CPM, strict=False).with_columns(
+        data_referencia=data_negociacao,
+        tipo_opcao=pl.col("codigo_negociacao")
+        .str.slice(6, 1)
+        .replace({"C": "call", "P": "put"}),
+        variacao_strike_bps=(
+            pl.col("codigo_negociacao")
+            .str.slice(7, 6)
+            .cast(pl.Int64, strict=False)
+            .floordiv(10)
+            .sub(10_000)
+            .cast(pl.Int32)
+        ),
+        _mes_reuniao=pl.col("codigo_negociacao")
+        .str.slice(3, 1)
+        .replace_strict(_MAPA_MESES, default=None, return_dtype=pl.Int32),
+        _ano_reuniao=(
+            pl.col("codigo_negociacao")
+            .str.slice(4, 2)
+            .cast(pl.Int32, strict=False)
+            .add(2000)
+        ),
+    )
+
+    cal = copom.calendario().select(
+        _mes_reuniao=pl.col("data_decisao").dt.month().cast(pl.Int32),
+        _ano_reuniao=pl.col("data_decisao").dt.year().cast(pl.Int32),
+        data_fim_reuniao=pl.col("data_decisao"),
+        data_expiracao=pl.col("data_efetividade"),
+    )
+
+    df = df.join(cal, on=["_mes_reuniao", "_ano_reuniao"], how="left").drop(
+        "_mes_reuniao", "_ano_reuniao"
+    )
+
+    # O SPR não traz o Preço de Referência das opções; ele vem do CSV consolidado.
+    precos = _parsear_precos_referencia(_buscar_csv(data_negociacao))
+
+    return (
+        df.join(precos, on="codigo_negociacao", how="left")
+        .with_columns(
+            dias_uteis=du.contar_expr("data_referencia", "data_expiracao").cast(
+                pl.Int32
+            )
+        )
+        .select(_df_vazio().columns)
+        .sort("data_expiracao", "variacao_strike_bps")
+    )