PYield: Toolkit de Renda Fixa Brasileira

Português | English

PYield é uma biblioteca Python voltada para análise de títulos públicos brasileiros. Ela busca e processa dados da ANBIMA, BCB, IBGE, B3 e Tesouro Nacional.

PYield usa Polars para processar dados em tabelas e coleções. Saídas escalares retornam tipos nativos do Python, enquanto saídas não escalares retornam polars.Series ou polars.DataFrame, conforme a função.

Embora inclua dados e ferramentas de outros mercados (como DI1, DAP e PTAX), esses recursos são auxiliares para o objetivo central: análise, precificação e acompanhamento de títulos públicos.

Instalação

pip install pyield

Início Rápido

import pyield as yd

# Dias úteis (base de todos os cálculos)
yd.du.contar("02-01-2025", "15-01-2025")  # -> 9
yd.du.deslocar("29-12-2023", 1)           # -> datetime.date(2024, 1, 2)

# Curva de DI Futuro
df = yd.futuro.historico("31-05-2024", "DI1")
# Colunas: data_referencia, codigo_negociacao, data_vencimento, dias_uteis, taxa_ajuste, ...

# Interpolação de taxas (flat forward, convenção 252 dias úteis/ano)
interp = yd.Interpolador(df["dias_uteis"], df["taxa_ajuste"], metodo="flat_forward")
interp(45)  # -> 0.04833...

# Preçificar títulos públicos
yd.ntnb.cotacao("31-05-2024", "15-05-2035", 0.061490)  # -> 0.993651

# Indicadores do BCB
yd.selic.over("31-05-2024")  # -> 0.000414...

Datas escalares aceitam DD-MM-YYYY, DD/MM/YYYY e YYYY-MM-DD. Datas escalares malformadas levantam ValueError; em operações vetorizadas, elementos malformados tornam-se null para preservar o pipeline Polars.

Um notebook no Colab com mais exemplos:

Mapa da API

Veja o mapa completo da API na documentação.

Componente	Tipo	Finalidade	Funções públicas
`yd.du`	módulo	Dias úteis e calendário brasileiro	`contar`, `deslocar`, `eh_dia_util`, `gerar`, `ultimo_dia_util`, `contar_expr`, `deslocar_expr`, `eh_dia_util_expr`
`yd.Interpolador`	classe	Interpolação escalar e em pipelines Polars	`interpolar`, `interpolar_expr`, `linear`, `flat_forward`
`yd.interpolar(...)`	função	Interpolação vetorizada flat-forward, curva única ou multi-curva
`yd.forward(...)`	função	Taxa a termo entre dois vértices
`yd.forwards(...)`	função	Curva de taxas a termo
`yd.futuro`	módulo	Contratos futuros da B3	`di1`, `historico`, `intradia`, `datas_disponiveis`, `vencimento`, `enriquecer`, `vencimento_expr`
`yd.di1`	módulo	Curva DI1 e interpolação	`dados`, `interpolar_taxas`, `interpolar_taxa`, `datas_disponiveis`
`yd.tpf`	módulo	Títulos públicos federais	`taxas`, `vencimentos`, `estoque`, `leiloes`, `benchmarks`, `curva_pre`, `premios_pre`, `rmd`, `secundario`
`yd.lft`	módulo	LFT	`dados`, `vencimentos`, `cotacao`, `pu`, `taxa`, `vna`, `rentabilidade`, `rentabilidade_expr`
`yd.ltn`	módulo	LTN	`dados`, `vencimentos`, `pu`, `taxa`, `duration_expr`, `dv01`, `dv01_expr`, `rentabilidade`, `rentabilidade_expr`, `taxas_forward`
`yd.ntnb`	módulo	NTN-B	`dados`, `vencimentos`, `datas_pagamento`, `fluxos_caixa`, `cotacao`, `pu`, `taxa`, `taxas_zero`, `duration`, `duration_expr`, `dv01`, `dv01_expr`, `implicitas`, `curva`
`yd.ntnb1`	módulo	NTN-B1 (Educa+ e Renda+)	`NomeComercial`, `datas_pagamento`, `fluxos_caixa`, `cotacao`, `cotacao_curva_zero`, `taxa_curva_zero`, `pu`, `duration`, `dv01`
`yd.ntnbp`	módulo	NTN-B Principal	`taxas_zero`, `cotacao`, `taxa`, `pu`, `dv01`
`yd.ntnc`	módulo	NTN-C	`dados`, `datas_pagamento`, `fluxos_caixa`, `cotacao`, `pu`, `taxa`, `duration`, `duration_expr`, `dv01`, `dv01_expr`
`yd.ntnf`	módulo	NTN-F	`dados`, `vencimentos`, `datas_pagamento`, `fluxos_caixa`, `pu`, `taxa`, `taxas_zero`, `premio`, `premio_limpo`, `premio_limpo_expr`, `rentabilidade`, `rentabilidade_expr`, `duration`, `duration_expr`, `dv01`, `dv01_expr`
`yd.selic`	módulo	Selic, COPOM e política monetária	`over`, `over_serie`, `meta`, `meta_serie`, `compromissadas`, `copom`, `cpm`, `probabilities`
`yd.ipca`	módulo	IPCA histórico e projetado	`indice`, `indices`, `indices_ultimos`, `taxa`, `taxas`, `taxas_ultimas`, `taxa_projetada`
`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
`yd.hoje()`	função	Data atual no Brasil
`yd.agora()`	função	Data e hora atual no Brasil

Blocos Principais

Dias Úteis (`du`)

O módulo du é a base do PYield. Todos os cálculos com datas (preço, duration, taxas a termo) dependem da contagem correta de dias úteis com feriados brasileiros.

from pyield import du

# Conta dias úteis (início inclusivo, fim exclusivo)
du.contar("29-12-2023", "02-01-2024")  # -> 1

# Avança N dias úteis
du.deslocar("29-12-2023", 1)  # -> datetime.date(2024, 1, 2)

# Ajusta dia não útil para o próximo dia útil
du.deslocar("30-12-2023", 0)  # -> datetime.date(2024, 1, 2)

# Gera intervalo de dias úteis
du.gerar("22-12-2023", "02-01-2024")
# -> Series: [2023-12-22, 2023-12-26, 2023-12-27, 2023-12-28, 2023-12-29, 2024-01-02]

# Verifica se a data é dia útil
du.eh_dia_util("25-12-2023")  # -> False (Natal)

As principais funções de cálculo (contar, deslocar e eh_dia_util) suportam operações vetorizadas com listas, Series ou arrays.

Interpolação de Taxas (`Interpolador`)

A classe Interpolador interpola taxas usando a convenção de 252 dias úteis/ano, padrão no mercado brasileiro.

from pyield import Interpolador

dias_uteis = [30, 60, 90]
taxas = [0.045, 0.05, 0.055]

# Interpolação flat forward (padrão de mercado)
interp = Interpolador(dias_uteis, taxas, metodo="flat_forward")
interp(45)  # -> 0.04833...

# Interpolação linear
linear = Interpolador(dias_uteis, taxas, metodo="linear")
linear(45)  # -> 0.0475

# Extrapolação na ponta longa: desabilitada por padrão (NaN). A ponta
# curta sempre retorna a primeira taxa conhecida.
interp(100)  # -> nan
Interpolador(dias_uteis, taxas, metodo="flat_forward", extrapolar=True)(100)  # -> 0.055

Para interpolar uma coluna inteira dentro de um pipeline Polars, use interpolar_expr:

import polars as pl

df = pl.DataFrame({"du": [15, 45, 75]})
df.with_columns(taxa=interp.interpolar_expr("du"))

Quando os pontos alvo e a curva vêm de DataFrames diferentes (inclusive com múltiplas datas de referência), use a função top-level yd.interpolar:

import pyield as yd

taxas = yd.interpolar(
    dus_alvo=df_alvo["dias_uteis"],
    dus_curva=df_curva["dias_uteis"],
    taxas_curva=df_curva["taxa"],
    datas_alvo=df_alvo["data_referencia"],   # opcional (multi-curva)
    datas_curva=df_curva["data_referencia"], # opcional (multi-curva)
)

Taxas a Termo (`forward`, `forwards`)

Calcula taxas a termo a partir de curvas spot:

Convenção utilizada:

fwd_k = fwd_{j->k} (forward do vértice j para k)
f_k = 1 + tx_k (fator de capitalização no vértice k)
fwd_k = (f_k^au_k / f_j^au_j)^(1 / (au_k - au_j)) - 1, com au = du / 252

from pyield import forward, forwards

# Taxa a termo única entre dois pontos
forward(10, 20, 0.05, 0.06)  # -> 0.0700952...

# Curva a termo vetorizada a partir de taxas spot
dias_uteis = [10, 20, 30]
taxas = [0.05, 0.06, 0.07]
forwards(dias_uteis, taxas)  # -> Series: [0.05, 0.070095, 0.090284]

Títulos Públicos

Os módulos lft, ltn, ntnb, ntnb1, ntnbp, ntnf e ntnc fazem parte da família de Títulos Públicos Federais (tpf). Para uso direto dos títulos, prefira os atalhos públicos na raiz:

from pyield import ltn, ntnb, ntnf

# Busca taxas indicativas da ANBIMA
ltn.dados("23-08-2024")  # -> DataFrame com títulos LTN
ntnb.dados("23-08-2024")  # -> DataFrame com títulos NTN-B

# Calcula cotação do título (base 1)
ntnb.cotacao("31-05-2024", "15-05-2035", 0.061490)  # -> 0.993651
ntnb.cotacao("31-05-2024", "15-08-2060", 0.061878)  # -> 0.995341

# Prêmio sobre o DI (pontos_base=True multiplica por 10.000)
ntnf.premio("30-05-2025", pontos_base=True)
# -> DataFrame: titulo, data_vencimento, premio

Dados de Futuros

import pyield as yd

# DI1 (Futuro de Depósito Interfinanceiro)
yd.futuro.historico("31-05-2024", "DI1")

# Outros contratos disponíveis no cache histórico:
# - Juros: DI1, DDI, FRC, FRO, DAP
# - Moedas: DOL, WDO
# - Índices: IND, WIN
yd.futuro.historico("31-05-2024", "DAP")

# Múltiplas datas de uma vez
yd.futuro.historico(["29-05-2024", "31-05-2024"], "DI1")

# Dados intradia (quando o mercado estiver aberto)
yd.futuro.intradia("DI1")  # Retorna dados ao vivo durante o pregão

Tratamento de Datas

PYield aceita entradas de data flexíveis (DateLike):

Strings: "31-05-2024", "31/05/2024", "2024-05-31"
datetime.date, datetime.datetime

Funções escalares de data retornam datetime.date. Operações vetorizadas de data retornam polars.Series, enquanto consultas tabulares retornam polars.DataFrame.

O parsing de strings usa expressões vetorizadas do Polars, com fallback entre os formatos aceitos por linha. Strings inválidas são convertidas para valores nulos (None em saídas escalares e null em saídas vetorizadas).

Valores nulos de data são preservados: entradas escalares ausentes retornam None, e operações vetorizadas propagam null elemento a elemento.

from pyield import du

du.deslocar(None, 1)  # -> None
du.contar(["01-01-2024", None], "01-02-2024")  # -> Series: [22, null]

Consultas sem dados disponíveis (data futura, feriado, fim de semana ou fonte indisponível) retornam DataFrame vazio ou nan, sem lançar exceção:

import pyield as yd

yd.futuro.historico("01-01-2030", "DI1").is_empty()  # -> True
yd.tpf.secundario.mensal("01-01-2030").is_empty()    # -> True
yd.ptax("25-12-2025")                                # -> nan

Documentação

Documentação completa: crdcj.github.io/PYield

Quebras de API

Quebras acumuladas por versão desde a v0.52.0.

v0.54.0

LFT, NTN-B, NTN-C e NTN-B1 passaram a expor cotação e valores de fluxo em base 1 (fator decimal), em vez de base 100 (escala percentual da ANBIMA). A precisão numérica é preservada: o truncamento de 4 casas na escala ANBIMA equivale a 6 casas em base 1.
```
# Antes
yd.ntnb.cotacao("31-05-2024", "15-05-2035", 0.061490)  # -> 99.3651
yd.lft.pu(15785.324502, 99.9291)                       # -> 15774.132706

# Agora
yd.ntnb.cotacao("31-05-2024", "15-05-2035", 0.061490)  # -> 0.993651
yd.lft.pu(15785.324502, 0.999291)                      # -> 15774.132706
```
Também afeta fluxos_caixa(...) de NTN-B e NTN-C: o cupom semestral passou de 2,956301 para 0,02956301 (NTN-C 6% a.a.) e o pagamento final passou de 102,956301 para 1,02956301. Chamadas a pu(vna, cotacao) que dividiam por 100 (cotacao / 100) devem passar diretamente o fator em base 1. O PU final permanece na mesma escala financeira.
yd.ntnbprinc (e yd.tpf.ntnbprinc) foi renomeado para yd.ntnbp (e yd.tpf.ntnbp), alinhando o namespace público aos nomes curtos usados no restante da biblioteca (ntnb, ntnb1, ntnbp, ntnc, ntnf).
yd.tpf.premio_pre foi renomeado para yd.tpf.premios_pre, coerente com o retorno tabular (DataFrame com múltiplos prêmios).
Entradas escalares de data inválidas agora levantam ValueError em qualquer função pública que aceite DateLike. Antes, chamadas como yd.du.deslocar("31-02-2024", 1) retornavam None silenciosamente. Em operações vetorizadas o parse continua tolerante: elementos inválidos viram null para preservar o pipeline Polars. Strings vazias ou só com espaços continuam sendo tratadas como nulas.

v0.53.0

As funções secundárias de TPF migraram do yd.tpf para o namespace dedicado yd.tpf.secundario:
- yd.tpf.secundario_intradia(...) → yd.tpf.secundario.intradia(...)
- yd.tpf.secundario_mensal(...) → yd.tpf.secundario.mensal(...)

v0.52.0

Interpolador(...) e Interpolador.interpolar(...) agora aceitam apenas inteiro escalar. Chamadas com lista/pl.Series (interp([30, 60])), antes suportadas via sobrecarga vetorial, agora levantam TypeError. Substitua por Interpolador.interpolar_expr em pipelines Polars ou pela função top-level yd.interpolar(...) (curva única ou multi-curva).
yd.interpolar(...) passou a usar extrapolar=False como padrão, alinhado com Interpolador. Antes era True. Chamadas que dependiam da extrapolação implícita na ponta longa precisam passar extrapolar=True explicitamente.
As funções dv01(...) dos títulos públicos agora recebem pu como argumento explícito. Chamadas antigas que passavam apenas data, vencimento e taxa, ou que passavam VNA no caso da NTN-B, precisam ser atualizadas.
ntnf.taxas_zero(...) mudou os nomes dos parâmetros de curva para o padrão vencimentos_* / taxas_*. Chamadas por posição continuam com a mesma ordem; chamadas por keyword precisam usar os novos nomes.

`Interpolador(...)` não aceita mais lista/Series

O __call__ e o método interpolar da classe agora são estritamente escalares. O caminho vetorial foi dividido em duas APIs com semântica clara:

# Antes (v0.51.x)
interp = yd.Interpolador(dus, taxas, metodo="flat_forward")
interp([15, 45, 75])  # pl.Series

# Agora, dentro de um pipeline Polars
df.with_columns(taxa=interp.interpolar_expr("du"))

# Agora, ad-hoc (curva única ou multi-curva)
yd.interpolar(
    dus_alvo=pl.Series([15, 45, 75]),
    dus_curva=pl.Series(dus),
    taxas_curva=pl.Series(taxas),
)

`dv01(...)` agora recebe PU

As funções dv01(...) dos títulos públicos recebem o PU usado como base para o cálculo, não mais o VNA ou apenas a taxa. Se necessário, calcule o PU antes:

pu = yd.ntnb.pu(vna, yd.ntnb.cotacao(data, vencimento, taxa))
dv01 = yd.ntnb.dv01(data, vencimento, taxa, pu)

`ntnf.taxas_zero(...)` usa nomes por conceito

Os parâmetros de curva da NTN-F foram renomeados para manter o padrão vencimentos_* / taxas_*:

ltn_vencimentos → vencimentos_ltn
ltn_taxas → taxas_ltn
ntnf_vencimentos → vencimentos_ntnf
ntnf_taxas → taxas_ntnf

Testes

uv run pytest

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pyield-0.54.0.tar.gz (122.2 kB view details)

Uploaded Jul 12, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

pyield-0.54.0-py3-none-any.whl (162.8 kB view details)

Uploaded Jul 12, 2026 Python 3

File details

Details for the file pyield-0.54.0.tar.gz.

File metadata

Download URL: pyield-0.54.0.tar.gz
Upload date: Jul 12, 2026
Size: 122.2 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.11.28 {"installer":{"name":"uv","version":"0.11.28","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Bluefin","version":"44","id":"Deinonychus","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

File hashes

Hashes for pyield-0.54.0.tar.gz
Algorithm	Hash digest
SHA256	`3334a12f5ec56da91f0d02cf77f28a3259b2b6c4d9ad69416398436ef3216ad1`
MD5	`f194c0f5b6fb26c311db42bfb038752b`
BLAKE2b-256	`2664cd9d0129aa9378b7adadf63d9a915a014478e56601652e44222d3f3f0505`

See more details on using hashes here.

File details

Details for the file pyield-0.54.0-py3-none-any.whl.

File metadata

Download URL: pyield-0.54.0-py3-none-any.whl
Upload date: Jul 12, 2026
Size: 162.8 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.11.28 {"installer":{"name":"uv","version":"0.11.28","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Bluefin","version":"44","id":"Deinonychus","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

File hashes

Hashes for pyield-0.54.0-py3-none-any.whl
Algorithm	Hash digest
SHA256	`c3aefacacdee4092d5f1c242610a9661affd0fa0335d0e6aa3786787c20d74b9`
MD5	`073b8f52ba9c23f4619832218074709b`
BLAKE2b-256	`7f64db7e6201a1907b054154dbe7f67fc2325e00b6808a8c7d3f42b64bd23f6b`