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, taxas_historicas, 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)
Por padrão, calendario="auto" seleciona a lista de feriados com base na data de
referência de cada operação. Em entradas vetorizadas, a seleção ocorre por
elemento; em du.gerar, ela usa inicio. Use calendario="anterior" para
forçar o regime anterior a 26/12/2023 ou calendario="atual" para forçar a
lista vigente na versão instalada:
du.contar("20-11-2024", "21-11-2024", calendario="anterior") # -> 1
du.contar("20-11-2024", "21-11-2024", calendario="atual") # -> 0
Os parâmetros opcionais usam termos em português. ajuste define como tratar uma
data inicial não útil, enquanto limites_inclusivos controla quais extremos de um
intervalo gerado são incluídos:
du.deslocar("23-12-2023", 0, ajuste="anterior")
# -> datetime.date(2023, 12, 22)
du.gerar("08-01-2024", "10-01-2024", limites_inclusivos="inicio").to_list()
# -> [datetime.date(2024, 1, 8), datetime.date(2024, 1, 9)]
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érticejparak)f_k = 1 + tx_k(fator de capitalização no vérticek)fwd_k = (f_k^au_k / f_j^au_j)^(1 / (au_k - au_j)) - 1, comau = 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:
import pyield as yd
from pyield import ltn, ntnb, ntnf
# Taxas indicativas em uma data ou período
yd.tpf.taxas("23-08-2024", titulo="PRE")
yd.tpf.taxas_historicas(
inicio="01-08-2024", fim="31-08-2024", titulo="PRE"
)
# 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
Compatibilidade e mudanças da API
A versão atual é v0.56.0. As mudanças abaixo podem exigir atualização de código:
| Versão | Mudança principal |
|---|---|
v0.56.0 |
As funções de dias úteis adotaram calendario="auto" | "anterior" | "atual". Em du.gerar, substitua opcao_feriado por calendario; "inferir", "antigo" e "novo" correspondem agora a "auto", "anterior" e "atual". O parâmetro rolagem virou ajuste; "forward" e "backward" viraram "seguinte" e "anterior". O parâmetro fechamento virou limites_inclusivos, com os valores "ambos", "inicio", "fim" e "nenhum". O padrão de calendario passou a ser "auto". Interpolador agora levanta ValueError quando a curva não contém vértices válidos. |
v0.55.0 |
Funções de PU, cotação e VNA dos títulos passaram a retornar Decimal com seis casas. Entradas numéricas aceitam float ou Decimal. |
v0.54.5 |
fluxos_caixa não aceita mais ajustar_datas_pagamento; os cronogramas usam datas contratuais. |
v0.54.2 |
taxas_historicas foi adicionada e tpf.taxas(completo=True) foi removida. |
v0.54.0 |
Cotações e fluxos de LFT, NTN-B, NTN-C e NTN-B1 passaram de base 100 para base 1; ntnbprinc virou ntnbp; premio_pre virou premios_pre; datas escalares inválidas passaram a levantar ValueError. |
v0.53.0 |
O mercado secundário de TPF passou para yd.tpf.secundario.intradia e yd.tpf.secundario.mensal. |
v0.52.0 |
Interpolador passou a ser escalar; use interpolar_expr ou yd.interpolar para vetores. dv01 passou a exigir pu e ntnf.taxas_zero adotou nomes vencimentos_* / taxas_*. |
O histórico completo está disponível nas releases do GitHub.
Testes
uv run pytest
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file pyield-0.56.1.tar.gz.
File metadata
- Download URL: pyield-0.56.1.tar.gz
- Upload date:
- Size: 131.8 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
2884ef0e5a7880fd825b85b09bdd64ea6e61a3fb2ec2100f918dc9ee7c8a4fa3
|
|
| MD5 |
47e90d7d85a506334ca757d3f96a8dfa
|
|
| BLAKE2b-256 |
b19fe7a04df2eead536d83d7d7225a0cafadf7d7896bac1a23e5f06f652accba
|
File details
Details for the file pyield-0.56.1-py3-none-any.whl.
File metadata
- Download URL: pyield-0.56.1-py3-none-any.whl
- Upload date:
- Size: 178.8 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
5d2935678a0a3abc9dfc0cc60f2c3b976d8a45d93e66c2e46ed588c31ee3d9d8
|
|
| MD5 |
435d5d5d464e47d05aa77a279296c78b
|
|
| BLAKE2b-256 |
370f9b76449284a8a5135b132775ede070742d187abd464c6933e46ce0264189
|
