pyield 0.50.1

Polars-powered toolkit for Brazilian fixed income analysis

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...
interp([30, 60]) # -> Series do Polars com taxas interpoladas

# Precificação de títulos públicos
yd.ntnb.cotacao("31-05-2024", "15-05-2035", 0.061490)  # -> 99.3651

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

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 de curvas	interpolar, __call__, linear, flat_forward
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	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, premio_pre, rmd, secundario_mensal, secundario_intradia
yd.lft	módulo	LFT	dados, vencimentos, cotacao, taxa, vna
yd.ltn	módulo	LTN	dados, vencimentos, pu, taxa, dv01, premio, rentabilidade, taxas_forward
yd.ntnb	módulo	NTN-B	dados, vencimentos, datas_pagamento, fluxos_caixa, cotacao, pu, taxa, taxas_zero, duration, dv01, inflacao_implicita
yd.ntnb1	módulo	NTN-B1	datas_pagamento, fluxos_caixa, cotacao, pu, duration, dv01
yd.ntnbprinc	módulo	NTN-B Principal	pu, dv01
yd.ntnc	módulo	NTN-C	dados, datas_pagamento, fluxos_caixa, cotacao, pu, taxa, duration
yd.ntnf	módulo	NTN-F	dados, vencimentos, datas_pagamento, fluxos_caixa, pu, taxa, taxas_zero, premio, premio_limpo, rentabilidade, duration, dv01
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

# Vetorizado
interp([15, 45, 75])  # -> pl.Series com 3 taxas

# Extrapolação (desabilitada por padrão, retorna NaN)
interp(100)  # -> nan
Interpolador(dias_uteis, taxas, metodo="flat_forward", extrapolar=True)(100)  # -> 0.055

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

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 100)
ntnb.cotacao("31-05-2024", "15-05-2035", 0.061490)  # -> 99.3651
ntnb.cotacao("31-05-2024", "15-08-2060", 0.061878)  # -> 99.5341

# 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

Quebra de API em leilões de TPF (v0.50.0)

yd.tpf.leilao(data) foi substituída por yd.tpf.leiloes(...). A nova função usa parâmetros nomeados e permite consultar uma data específica, uma lista de datas ou um período:

yd.tpf.leiloes(data="19-05-2026")
yd.tpf.leiloes(data=["14-05-2026", "19-05-2026"])
yd.tpf.leiloes(inicio="01-05-2026")
yd.tpf.leiloes(inicio="01-05-2026", fim="19-05-2026")

Testes

uv run pytest