Novidades na versão 0.62.0
Estas notas descrevem a 0.62.0. Os ajustes posteriores de escalas decimais, a série de DI Over, os índices no contexto de VNA e o corte histórico do IGP-M estão nas notas da 0.63.0.
Esta versão remove o cache automático das consultas às fontes externas e o
parâmetro atualizar. Os downloads passam a usar uma política compartilhada de
retentativa leve, com no máximo duas tentativas para falhas transitórias.
O cache diário dos históricos em Parquet de TPF e futuros permanece. A mudança
é incompatível com chamadas que ainda passam atualizar, mesmo quando o valor
é False.
O Polars 2.0 passa a ser a versão mínima exigida. Ambientes com Polars 1.x precisam atualizar essa dependência para instalar esta versão do PYield.
Selic Over, Selic Meta, DI Over e PTAX passam a retornar Decimal, preservando
os valores publicados sem passagem por float. As taxas Over também ganham
a opção diária com anualizada=False, e DI Over passa do FTP da CETIP para
a API HTTPS do Banco Central. Os novos tipos de retorno exigem atenção na
migração, conforme as seções abaixo.
Por que a política mudou
O cache das consultas externas foi criado para reduzir requisições repetidas e
proteger as APIs das fontes. Entretanto, ele podia devolver uma resposta anterior
quando o consumidor precisava consultar os dados disponíveis naquele momento.
No VNA, isso levou à criação de atualizar para ignorar o cache. O consumidor
precisava conhecer os prazos de expiração e quais downloads esse parâmetro
renovava; os índices de inflação usados no mesmo fluxo tinham caches separados.
A política de reutilização de respostas passa a ser responsabilidade de quem consome a biblioteca. A PYield busca e processa os dados; a aplicação decide se quer armazená-los, por quanto tempo e quando consultá-los novamente. Isso elimina os prazos implícitos e a necessidade de um parâmetro para ignorá-los.
Comportamento das consultas
Os downloads de BCB, ANBIMA, B3, IBGE, Tesouro Nacional e FGV deixam de manter cache entre chamadas. Isso abrange os indicadores, calendários, VNA, boletins, dados intradia, leilões, estoque, benchmarks, dealers, mercado secundário e RMD. Funções que dependem dessas consultas também passam a receber os dados dos novos downloads. Os timeouts permanecem; o retry segue a política leve abaixo.
Chamadas repetidas podem fazer mais requisições e levar mais tempo. Se sua aplicação consulta o mesmo dado em um laço, obtenha-o uma vez e reutilize o resultado, ou aplique sua própria política de cache considerando os limites da fonte.
Um novo download pode retornar os mesmos dados. A atualização depende da publicação pela fonte, incluindo eventuais atrasos. Datas de referência e horários informados nos dados mantêm seu significado; não representam necessariamente o momento da consulta.
Indicadores SGS com Decimal
As consultas yd.selic.over, yd.selic.meta, yd.di_over e yd.ptax passam
a retornar decimal.Decimal. As séries yd.selic.over_serie,
yd.selic.meta_serie e yd.ptax_serie passam a retornar colunas Polars
Decimal, inclusive quando vazias:
| Dado | Tipo da coluna | Unidade |
|---|---|---|
| Selic Over, Selic Meta e DI Over | Decimal(18, 10) |
Taxa em unidade decimal |
| PTAX | Decimal(18, 4) |
R\(/US\) |
Os valores são lidos diretamente do texto do SGS, sem passagem por float.
As taxas percentuais são divididas por 100 em aritmética decimal. A escala
10 preserva até oito casas decimais do percentual publicado; zeros adicionais
não representam precisão adicional da fonte. A PTAX preserva quatro casas.
A mudança é incompatível com código que depende de float ou Float64.
Escalares sem dados passam de float("nan") para Decimal("NaN"); use
valor.is_nan() para identificá-los. Séries sem dados continuam vazias,
com seus novos esquemas decimais. Para uma conversão explícita:
taxa = yd.selic.over("28-02-2025")
taxa_float = float(taxa)
serie_float = yd.selic.over_serie(ultimos=5).with_columns(
taxa=pl.col("taxa").cast(pl.Float64)
)
A conversão para ponto flutuante pode introduzir aproximação binária.
Em cálculos com Decimal, crie constantes a partir de texto, por exemplo,
Decimal("0.01"); precisão e arredondamento dos cálculos continuam dependendo
da metodologia. Integrações com NumPy e serializadores JSON podem exigir
conversão explícita. Os cálculos e o esquema de leilões de TPF permanecem em
Float64, com a PTAX convertida explicitamente ao entrar nesse fluxo.
Taxas Over anuais e diárias
yd.selic.over, yd.selic.over_serie e yd.di_over aceitam o parâmetro
opcional anualizada, exclusivo por palavra-chave. O padrão True preserva
a unidade atual: taxas ao ano, em base 252 dias úteis, agora do tipo Decimal.
Com anualizada=False, retornam taxas em decimal ao dia útil:
taxa_anual = yd.selic.over("28-02-2025")
taxa_diaria = yd.selic.over("28-02-2025", anualizada=False)
serie_diaria = yd.selic.over_serie("27-02-2025", "28-02-2025", anualizada=False)
di_diaria = yd.di_over("28-02-2025", anualizada=False)
A modalidade seleciona a série publicada pelo Banco Central: Selic Over usa SGS 1178 (anualizada) ou 11 (diária); DI Over usa SGS 4389 (anualizada) ou 12 (diária). A biblioteca converte o percentual da fonte para decimal, sem recalcular uma modalidade a partir da outra. A frequência das observações é diária em ambos os casos. Selic Meta mantém seu contrato anual.
Falhas de rede e retentativas
A PYield faz no máximo duas tentativas por download. Timeout, falha de conexão, transferência interrompida e HTTP 502, 503 ou 504 permitem uma única repetição, após uma espera aleatória entre 0,5 e 1 segundo. Se a segunda tentativa falhar, a exceção é propagada. A retentativa não mantém cache entre chamadas.
A regra é compartilhada pelos downloads HTTP de BCB, ANBIMA, B3, IBGE, Tesouro Nacional, FGV e históricos em Parquet do projeto. Os POSTs de consulta do IMA-Q e de exportação do CSV de derivativos da B3 também usam a regra por serem operações de leitura seguras de repetir. Não há habilitação automática de retry para qualquer POST.
A consulta yd.di_over(data) passa do FTP da CETIP para a API HTTPS do
Banco Central, série SGS 4389 por padrão ou SGS 12 com anualizada=False.
O padrão continua sendo a taxa anualizada em base 252, agora do tipo Decimal
(por exemplo, Decimal("0.1315000000") representa 13,15% a.a.).
O histórico passa a alcançar 06/03/1986, em vez de 20/08/2012. Datas sem dados
retornam Decimal("NaN"); HTTP 404 no SGS representa ausência de dados.
Falhas de transporte passam a propagar exceções de requests, como nas
demais consultas SGS, em lugar de ConnectionError do adaptador FTP.
Erros de entrada, parsing, validação de arquivos e demais erros HTTP, incluindo
429, não são repetidos. Nos status elegíveis, Retry-After é respeitado quando
pede até um segundo, tanto em segundos inteiros quanto em data HTTP. Um valor
inválido ou que exige espera maior impede a retentativa; a biblioteca propaga
o erro sem antecipar o prazo pedido pela fonte.
O retry envolve apenas o transporte. Em consultas paginadas, repete somente a página que falhou, preservando as anteriores. Downloads de anexos e blocos de séries recebem seu próprio limite, sem repetir todo o fluxo de consulta ou o processamento dos dados.
Antes, o retry padrão fazia até três tentativas com esperas crescentes. A nova regra procura absorver um soluço de comunicação com uma única oportunidade adicional. Recuperar um processo noturno por minutos ou horas continua sendo responsabilidade da aplicação. Esta separação também evita a multiplicação de tentativas em várias camadas, discutida na Amazon Builders' Library.
Consultas longas de Selic Meta passam a buscar os blocos sequencialmente, como as demais séries SGS. Esgotada a retentativa de um bloco, os seguintes não são enviados. Consultas bem-sucedidas com vários blocos podem levar mais tempo que antes, pois deixam de usar downloads paralelos. Paginação, anexos e consultas a fontes alternativas previstas no fluxo continuam podendo exigir downloads distintos.
Nas demais consultas, os tipos das exceções existentes são preservados. Por exemplo, o consumidor pode tratar uma falha do SGS sem reimplementar a consulta:
import requests
import pyield as yd
try:
dados = yd.selic.meta_serie(ultimos=1)
except requests.RequestException as erro:
registrar_falha(erro) # tratamento definido pela aplicação
else:
processar(dados)
Quem precisar de recuperação prolongada deve limitar o número de execuções e
o tempo total do processo, considerar Retry-After e evitar repetir erros de
entrada ou certificado. Quando a fonte já estiver reconhecidamente indisponível,
a aplicação pode suspender novas consultas até a próxima verificação.
As consultas HTTP separam os timeouts: conexão de 5 segundos e leitura com o limite de cada endpoint, de 10, 30 ou 60 segundos. A DI over passa a usar conexão de 5 segundos e leitura de 30 segundos, como as demais consultas SGS.
Espera curta entre tentativas não significa prazo total curto. Os timeouts se aplicam a cada tentativa. Um timeout de leitura de 60 segundos pode ser consumido novamente na segunda tentativa. No Requests, os timeouts limitam a conexão e a inatividade de leitura, e não o tempo total da chamada; DNS, múltiplos endereços, redirects e transferências que continuam recebendo bytes podem ampliar a duração. Não há garantia de um prazo total rígido. Veja a documentação de timeouts do Requests.
Migração: remova atualizar
O parâmetro foi removido das seguintes funções:
| Namespace | Funções |
|---|---|
yd.vna |
valor, historico, ultimo, contexto |
yd.ipca |
calendario |
yd.igpm |
calendario |
Antes:
valor = yd.vna.valor("LFT", "31-05-2024", atualizar=True)
historico = yd.vna.historico("NTN-C", vencimento="01-01-2031", atualizar=True)
ultimo = yd.vna.ultimo("NTN-B", atualizar=False)
contexto = yd.vna.contexto("NTN-B", "22-10-2026", atualizar=True)
calendario_ipca = yd.ipca.calendario(2026, atualizar=True)
calendario_igpm = yd.igpm.calendario(2026, atualizar=False)
Agora:
valor = yd.vna.valor("LFT", "31-05-2024")
historico = yd.vna.historico("NTN-C", vencimento="01-01-2031")
ultimo = yd.vna.ultimo("NTN-B")
contexto = yd.vna.contexto("NTN-B", "22-10-2026")
calendario_ipca = yd.ipca.calendario(2026)
calendario_igpm = yd.igpm.calendario(2026)
Não há parâmetro substituto. Passar atualizar gera TypeError.
Históricos em Parquet
O mecanismo de carregamento dos datasets anbima_tpf.parquet e
b3_futures.parquet continua com cache em memória por processo. A chave muda
quando vira a data em America/Sao_Paulo; a primeira consulta do novo dia carrega
o dataset novamente. Essa renovação é por dia de calendário, não por 24 horas
contadas desde o download.
Esses datasets são publicados e mantidos pelo projeto, com um ciclo de
distribuição próprio. O mecanismo permanece em yd.tpf.taxas_historicas, nas
consultas de taxas que usam esse histórico, em yd.futuro.historico e nas
consultas de DI1 que usam o histórico de futuros. yd.tpf.taxas continua buscando
diretamente na ANBIMA quando a data não está disponível no dataset; essa consulta
direta não mantém cache.
As mudanças de cache e retry não alteram fórmulas ou unidades. Os indicadores SGS passam a usar os tipos decimais descritos acima, e as taxas Over ganham a opção de retorno ao dia útil. As notas da 0.60.0 continuam disponíveis para migrações anteriores.