pyield 0.58.2__tar.gz → 0.60.0__tar.gz

pyield-0.60.0/PKG-INFO

@@ -0,0 +1,221 @@
+Metadata-Version: 2.4
+Name: pyield
+Version: 0.60.0
+Summary: Polars-powered toolkit for Brazilian fixed income analysis
+Keywords: fixed-income,brazil,finance,analysis,bonds
+Author: Carlos Carvalho
+Author-email: Carlos Carvalho <carlos.carvalho.jr@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Dist: polars>=1.39.0
+Requires-Dist: lxml>=6.0.0
+Requires-Dist: requests>=2.31.0
+Requires-Dist: fastexcel>=0.19.0
+Requires-Dist: tzdata>=2024.1 ; sys_platform == 'win32'
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/crdcj/PYield
+Project-URL: Documentation, https://crdcj.github.io/PYield
+Project-URL: Source, https://github.com/crdcj/PYield
+Project-URL: Bug Tracker, https://github.com/crdcj/PYield/issues
+Description-Content-Type: text/markdown
+
+[![PyPI version](https://img.shields.io/pypi/v/pyield.svg)](https://pypi.python.org/pypi/pyield)
+[![Made with Python](https://img.shields.io/badge/Python->=3.12-blue?logo=python&logoColor=white)](https://python.org "Go to Python homepage")
+[![Powered by Polars](https://img.shields.io/badge/Powered%20by-Polars-blue)](https://pola.rs/)
+[![License](https://img.shields.io/badge/License-MIT-blue)](https://github.com/crdcj/PYield/blob/main/LICENSE)
+[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue?logo=readthedocs&logoColor=white)](https://crdcj.github.io/PYield/)
+
+# PYield: Toolkit de Renda Fixa Brasileira
+
+Português | [English](https://github.com/crdcj/PYield/blob/main/README.en.md)
+
+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, retornando tipos nativos do Python, `polars.Series` ou
+`polars.DataFrame`, conforme a operação.
+
+Embora inclua dados e ferramentas de outros mercados, como DI1, DAP e PTAX,
+esses recursos apoiam o objetivo central da biblioteca: análise, precificação e
+acompanhamento de títulos públicos brasileiros.
+
+## Instalação
+
+Com `pip`:
+
+```sh
+pip install pyield
+```
+
+Em um projeto gerenciado pelo `uv`:
+
+```sh
+uv add pyield
+```
+
+## Próximos passos
+
+- [Quickstart](https://crdcj.github.io/PYield/quickstart/): primeiros usos da biblioteca.
+- [Documentação completa](https://crdcj.github.io/PYield/): conceitos e referência por módulo.
+- [Mapa da API](https://crdcj.github.io/PYield/api-map/): namespaces e funções públicas.
+- [Desenvolvimento e publicação](https://crdcj.github.io/PYield/desenvolvimento/): ambiente, verificações, build e PyPI.
+- [Gerar e publicar a documentação](docs/desenvolvimento.md#documentação): geração, visualização local e GitHub Pages.
+- [Notebook no Colab](https://colab.research.google.com/github/crdcj/PYield/blob/main/examples/pyield_quickstart.ipynb): exploração interativa.
+- [Pacote no PyPI](https://pypi.org/project/pyield/).
+
+## Mapa da API
+
+| 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, com métodos `linear` e `flat_forward` | `interpolar`, `interpolar_expr` |
+| `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`, `leiloes_bcb`, `benchmarks`, `dealers`, `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` |
+| `yd.ntnb` | módulo | NTN-B | `dados`, `vencimentos`, `datas_pagamento`, `fluxos_caixa`, `cotacao`, `pu`, `taxa`, `taxas_zero`, `duration`, `duration_expr`, `dv01`, `dv01_expr`, `implicitas` |
+| `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 | `cotacao`, `taxa`, `pu`, `dv01` |
+| `yd.ntnc` | módulo | NTN-C | `dados`, `datas_pagamento`, `fluxos_caixa`, `cotacao`, `cotacao_curva_zero`, `taxa_curva_zero`, `pu`, `taxa`, `duration`, `duration_expr`, `dv01`, `dv01_expr` |
+| `yd.ntnf` | módulo | NTN-F | `dados`, `vencimentos`, `datas_pagamento`, `fluxos_caixa`, `pu`, `taxa`, `taxas_zero`, `taxas_zero_forwards`, `premio_limpo`, `premio_limpo_expr`, `rentabilidade`, `rentabilidade_expr`, `duration`, `duration_expr`, `dv01`, `dv01_expr` |
+| `yd.vna` | módulo | Valores nominais atualizados dos títulos públicos | `valor`, `historico`, `ultimo`, `projetado`, `vigencia`, `contexto`, `calcular_vna`, `calcular_base` |
+| `yd.copom` | módulo | Calendário automático do Copom | `calendario`, `proxima_reuniao` |
+| `yd.compromissadas(inicio, fim)` | função | Leilões de operações compromissadas do BCB | |
+| `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 | `contratos`, `probabilidades` |
+| `yd.ipca` | módulo | IPCA histórico e projetado | `indice`, `indice_serie`, `taxa`, `taxa_serie`, `taxa_projetada`, `calendario` |
+| `yd.igpm` | módulo | Taxas e números-índice do IGP-M | `taxa`, `taxa_serie`, `indice`, `indice_serie`, `calendario` |
+| `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 | |
+
+O [mapa completo da API](https://crdcj.github.io/PYield/api-map/) inclui a
+documentação detalhada e as assinaturas públicas.
+
+## Novidades na versão 0.60.0
+
+Esta seção cobre apenas as mudanças da `0.59.0` para a `0.60.0`. Consulte também as
+[notas de migração](https://crdcj.github.io/PYield/release-0.60.0/).
+
+### Contratos com Decimal
+
+Os históricos e cálculos de VNA e os indicadores de inflação passam a preservar
+precisão decimal. Revise operações que misturam esses retornos com `float`:
+use `Decimal("0.0045")` para constantes exatas e `.is_nan()` para verificar
+um retorno escalar `Decimal("NaN")`. Converta para `float` explicitamente
+apenas quando a aplicação aceitar perder essa precisão.
+
+| Operação | Retorno na 0.60.0 |
+|---|---|
+| `vna.valor`, `vna.projetado`, `vna.calcular_vna`, `vna.calcular_base` | `Decimal` |
+| Coluna `vna` de `vna.historico` e `vna.ultimo` | `Decimal(18, 6)` |
+| `ipca.indice` / coluna `indice` de `ipca.indice_serie` | `Decimal` / `Decimal(18, 2)` |
+| `ipca.taxa` / coluna `taxa` de `ipca.taxa_serie` | `Decimal` / `Decimal(18, 4)` |
+| `ipca.taxa_projetada().valor_projetado` | `Decimal` com quatro casas |
+| `igpm.taxa` / coluna `taxa` de `igpm.taxa_serie` | `Decimal` / `Decimal(18, 4)` |
+| `igpm.indice` / coluna `indice` de `igpm.indice_serie` | `Decimal` / `Decimal(18, 10)` |
+
+`vna.calcular_vna` também passa de `float("nan")` para `Decimal("NaN")`
+na ausência de dados. Os cálculos de VNA usam 28 dígitos de precisão e aplicam
+os truncamentos e arredondamentos da metodologia; resultados intermediários
+podem diferir dos obtidos anteriormente com `float`.
+
+### 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. As colunas e unidades são preservadas;
+os tipos numéricos mudam conforme descrito acima.
+
+O número-índice agora usa `Decimal`: `ipca.indice(data)` retorna `Decimal`
+(ou `Decimal("NaN")` quando indisponível), e a coluna `indice` de
+`ipca.indice_serie(...)` usa `Decimal(18, 2)`. A conversão parte do texto do
+IBGE, sem passar por `float`.
+
+As taxas também usam `Decimal`: `ipca.taxa(data)` retorna `Decimal` (ou
+`Decimal("NaN")`), e a coluna `taxa` de `ipca.taxa_serie(...)` usa
+`Decimal(18, 4)`. O campo `valor_projetado` de `ipca.taxa_projetada()` passa a
+ser `Decimal` com quatro casas. A unidade permanece decimal: 0,45% corresponde
+a `Decimal("0.0045")`.
+
+Nas séries, `fim=None` usa a data atual no Brasil. Informe `inicio` ou
+`ultimos`; quando informado, `ultimos` tem prioridade sobre as datas.
+
+### Contexto de VNA e calendários de inflação
+
+- `yd.vna.contexto(...)` reúne os parâmetros da vigência de NTN-B ou NTN-C:
+  VNAs publicados, competência, inflação e pendências. Exige `vencimento` para
+  NTN-C e aceita uma projeção explícita quando a inflação realizada não existe.
+  As entradas de inflação em `contexto` e `projetado` aceitam números decimais
+  (`0.0045`) ou percentuais explícitos (`"0.45%"` ou `"0,45%"`). A coluna
+  `inflacao` de `contexto` usa Decimal e pode ser passada diretamente a
+  `projetado`.
+  Migração: substitua o antigo `inflacao=0.45` por `inflacao="0.45%"` ou
+  `inflacao=0.0045`; números puros agora representam taxas decimais.
+- `yd.ipca.calendario(ano, atualizar=False)` consulta as datas previstas de
+  divulgação no IBGE pelo ano da competência, incluindo dezembro divulgado no
+  ano seguinte.
+- `yd.igpm.calendario(ano, atualizar=False)` consulta as divulgações mensais
+  na FGV IBRE, excluindo prévias decendiais. Os calendários não comprovam
+  que os índices já foram publicados.
+
+### Outras mudanças
+
+- `yd.vna.calcular_base(titulo, indice_atual, vencimento=None)` calcula a base
+  mensal da NTN-B ou NTN-C com o número-índice realizado do IPCA ou IGP-M,
+  ou o VNA da LFT com o fator Selic acumulado desde 01/07/2000, sem acesso
+  à rede. As origens e os índices iniciais são constantes internas;
+  NTN-C exige vencimento para selecionar a série e seu ajuste de emissão.
+  Para LFT, arredonda o fator em dezesseis casas; para NTN-B e NTN-C, trunca
+  o fator nessa precisão. Trunca o VNA em seis casas, preservando a
+  precisão da origem e evitando encadear VNAs mensais já truncados.
+- Novo módulo `yd.igpm`, com `taxa` e `taxa_serie` para consultar taxas mensais
+  do IGP-M via SGS/BCB. `taxa` retorna `Decimal` (ou `Decimal("NaN")` quando
+  indisponível), e a coluna `taxa` de `taxa_serie` usa `Decimal(18, 4)`.
+  A unidade é decimal: 0,27% corresponde a `Decimal("0.0027")`.
+  `indice` e `indice_serie` fornecem os números-índice da FGV via Ipeadata
+  (série `IGP12_IGPM12`), como `Decimal` e coluna `Decimal(18, 10)`.
+  As dez casas preservam o histórico anterior a 1994. As séries aceitam
+  intervalo ou `ultimos`, com competência `periodo` no formato `YYYYMM`.
+- No CPM, substitua `yd.cpm.data(data)` por `yd.cpm.contratos(data)` e use
+  `yd.cpm.probabilidades(data, tipo_opcao="call")` para as probabilidades.
+  Esta última retorna todas as reuniões disponíveis; filtre o DataFrame para
+  selecionar uma reunião.
+- Leilões do BCB passam de `yd.bc.leiloes` para `yd.tpf.leiloes_bcb`, com nomes
+  de colunas alinhados aos de `yd.tpf.leiloes`.
+- No mercado secundário, `yd.tpf.secundario.ler(fonte)` substitui `ler_zip` e
+  `zip_para_silver`: aceita caminho ou bytes de ZIP e inclui `financeiro` na
+  saída. `nome_arquivo_mensal` deixa de ser público.
+- `yd.ntnf.premio` foi removida. Use `yd.tpf.premios_pre(data)` e filtre
+  `titulo == "NTN-F"` para obter o prêmio bruto.
+- `yd.tpf.taxas` e as consultas `dados` de LFT, LTN, NTN-B, NTN-C e NTN-F
+  preservam colunas e tipos quando não há dados. Nos leilões do Tesouro, PU
+  mínimo informado como zero passa a ser nulo, e o financeiro ofertado usa o
+  PU médio calculado quando necessário.
+- `yd.rmd` passa a propagar erros de download e processamento, em vez de
+  retornar um DataFrame vazio nessas situações.
+
+Consulte as [releases do GitHub](https://github.com/crdcj/PYield/releases)
+para o histórico completo e as notas de migração de versões anteriores.
+
+## Projeto
+
+- [Código-fonte](https://github.com/crdcj/PYield)
+- [Issues](https://github.com/crdcj/PYield/issues)
+- [Licença MIT](LICENSE)

pyield-0.60.0/README.md

@@ -0,0 +1,196 @@
+[![PyPI version](https://img.shields.io/pypi/v/pyield.svg)](https://pypi.python.org/pypi/pyield)
+[![Made with Python](https://img.shields.io/badge/Python->=3.12-blue?logo=python&logoColor=white)](https://python.org "Go to Python homepage")
+[![Powered by Polars](https://img.shields.io/badge/Powered%20by-Polars-blue)](https://pola.rs/)
+[![License](https://img.shields.io/badge/License-MIT-blue)](https://github.com/crdcj/PYield/blob/main/LICENSE)
+[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue?logo=readthedocs&logoColor=white)](https://crdcj.github.io/PYield/)
+
+# PYield: Toolkit de Renda Fixa Brasileira
+
+Português | [English](https://github.com/crdcj/PYield/blob/main/README.en.md)
+
+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, retornando tipos nativos do Python, `polars.Series` ou
+`polars.DataFrame`, conforme a operação.
+
+Embora inclua dados e ferramentas de outros mercados, como DI1, DAP e PTAX,
+esses recursos apoiam o objetivo central da biblioteca: análise, precificação e
+acompanhamento de títulos públicos brasileiros.
+
+## Instalação
+
+Com `pip`:
+
+```sh
+pip install pyield
+```
+
+Em um projeto gerenciado pelo `uv`:
+
+```sh
+uv add pyield
+```
+
+## Próximos passos
+
+- [Quickstart](https://crdcj.github.io/PYield/quickstart/): primeiros usos da biblioteca.
+- [Documentação completa](https://crdcj.github.io/PYield/): conceitos e referência por módulo.
+- [Mapa da API](https://crdcj.github.io/PYield/api-map/): namespaces e funções públicas.
+- [Desenvolvimento e publicação](https://crdcj.github.io/PYield/desenvolvimento/): ambiente, verificações, build e PyPI.
+- [Gerar e publicar a documentação](docs/desenvolvimento.md#documentação): geração, visualização local e GitHub Pages.
+- [Notebook no Colab](https://colab.research.google.com/github/crdcj/PYield/blob/main/examples/pyield_quickstart.ipynb): exploração interativa.
+- [Pacote no PyPI](https://pypi.org/project/pyield/).
+
+## Mapa da API
+
+| 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, com métodos `linear` e `flat_forward` | `interpolar`, `interpolar_expr` |
+| `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`, `leiloes_bcb`, `benchmarks`, `dealers`, `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` |
+| `yd.ntnb` | módulo | NTN-B | `dados`, `vencimentos`, `datas_pagamento`, `fluxos_caixa`, `cotacao`, `pu`, `taxa`, `taxas_zero`, `duration`, `duration_expr`, `dv01`, `dv01_expr`, `implicitas` |
+| `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 | `cotacao`, `taxa`, `pu`, `dv01` |
+| `yd.ntnc` | módulo | NTN-C | `dados`, `datas_pagamento`, `fluxos_caixa`, `cotacao`, `cotacao_curva_zero`, `taxa_curva_zero`, `pu`, `taxa`, `duration`, `duration_expr`, `dv01`, `dv01_expr` |
+| `yd.ntnf` | módulo | NTN-F | `dados`, `vencimentos`, `datas_pagamento`, `fluxos_caixa`, `pu`, `taxa`, `taxas_zero`, `taxas_zero_forwards`, `premio_limpo`, `premio_limpo_expr`, `rentabilidade`, `rentabilidade_expr`, `duration`, `duration_expr`, `dv01`, `dv01_expr` |
+| `yd.vna` | módulo | Valores nominais atualizados dos títulos públicos | `valor`, `historico`, `ultimo`, `projetado`, `vigencia`, `contexto`, `calcular_vna`, `calcular_base` |
+| `yd.copom` | módulo | Calendário automático do Copom | `calendario`, `proxima_reuniao` |
+| `yd.compromissadas(inicio, fim)` | função | Leilões de operações compromissadas do BCB | |
+| `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 | `contratos`, `probabilidades` |
+| `yd.ipca` | módulo | IPCA histórico e projetado | `indice`, `indice_serie`, `taxa`, `taxa_serie`, `taxa_projetada`, `calendario` |
+| `yd.igpm` | módulo | Taxas e números-índice do IGP-M | `taxa`, `taxa_serie`, `indice`, `indice_serie`, `calendario` |
+| `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 | |
+
+O [mapa completo da API](https://crdcj.github.io/PYield/api-map/) inclui a
+documentação detalhada e as assinaturas públicas.
+
+## Novidades na versão 0.60.0
+
+Esta seção cobre apenas as mudanças da `0.59.0` para a `0.60.0`. Consulte também as
+[notas de migração](https://crdcj.github.io/PYield/release-0.60.0/).
+
+### Contratos com Decimal
+
+Os históricos e cálculos de VNA e os indicadores de inflação passam a preservar
+precisão decimal. Revise operações que misturam esses retornos com `float`:
+use `Decimal("0.0045")` para constantes exatas e `.is_nan()` para verificar
+um retorno escalar `Decimal("NaN")`. Converta para `float` explicitamente
+apenas quando a aplicação aceitar perder essa precisão.
+
+| Operação | Retorno na 0.60.0 |
+|---|---|
+| `vna.valor`, `vna.projetado`, `vna.calcular_vna`, `vna.calcular_base` | `Decimal` |
+| Coluna `vna` de `vna.historico` e `vna.ultimo` | `Decimal(18, 6)` |
+| `ipca.indice` / coluna `indice` de `ipca.indice_serie` | `Decimal` / `Decimal(18, 2)` |
+| `ipca.taxa` / coluna `taxa` de `ipca.taxa_serie` | `Decimal` / `Decimal(18, 4)` |
+| `ipca.taxa_projetada().valor_projetado` | `Decimal` com quatro casas |
+| `igpm.taxa` / coluna `taxa` de `igpm.taxa_serie` | `Decimal` / `Decimal(18, 4)` |
+| `igpm.indice` / coluna `indice` de `igpm.indice_serie` | `Decimal` / `Decimal(18, 10)` |
+
+`vna.calcular_vna` também passa de `float("nan")` para `Decimal("NaN")`
+na ausência de dados. Os cálculos de VNA usam 28 dígitos de precisão e aplicam
+os truncamentos e arredondamentos da metodologia; resultados intermediários
+podem diferir dos obtidos anteriormente com `float`.
+
+### 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. As colunas e unidades são preservadas;
+os tipos numéricos mudam conforme descrito acima.
+
+O número-índice agora usa `Decimal`: `ipca.indice(data)` retorna `Decimal`
+(ou `Decimal("NaN")` quando indisponível), e a coluna `indice` de
+`ipca.indice_serie(...)` usa `Decimal(18, 2)`. A conversão parte do texto do
+IBGE, sem passar por `float`.
+
+As taxas também usam `Decimal`: `ipca.taxa(data)` retorna `Decimal` (ou
+`Decimal("NaN")`), e a coluna `taxa` de `ipca.taxa_serie(...)` usa
+`Decimal(18, 4)`. O campo `valor_projetado` de `ipca.taxa_projetada()` passa a
+ser `Decimal` com quatro casas. A unidade permanece decimal: 0,45% corresponde
+a `Decimal("0.0045")`.
+
+Nas séries, `fim=None` usa a data atual no Brasil. Informe `inicio` ou
+`ultimos`; quando informado, `ultimos` tem prioridade sobre as datas.
+
+### Contexto de VNA e calendários de inflação
+
+- `yd.vna.contexto(...)` reúne os parâmetros da vigência de NTN-B ou NTN-C:
+  VNAs publicados, competência, inflação e pendências. Exige `vencimento` para
+  NTN-C e aceita uma projeção explícita quando a inflação realizada não existe.
+  As entradas de inflação em `contexto` e `projetado` aceitam números decimais
+  (`0.0045`) ou percentuais explícitos (`"0.45%"` ou `"0,45%"`). A coluna
+  `inflacao` de `contexto` usa Decimal e pode ser passada diretamente a
+  `projetado`.
+  Migração: substitua o antigo `inflacao=0.45` por `inflacao="0.45%"` ou
+  `inflacao=0.0045`; números puros agora representam taxas decimais.
+- `yd.ipca.calendario(ano, atualizar=False)` consulta as datas previstas de
+  divulgação no IBGE pelo ano da competência, incluindo dezembro divulgado no
+  ano seguinte.
+- `yd.igpm.calendario(ano, atualizar=False)` consulta as divulgações mensais
+  na FGV IBRE, excluindo prévias decendiais. Os calendários não comprovam
+  que os índices já foram publicados.
+
+### Outras mudanças
+
+- `yd.vna.calcular_base(titulo, indice_atual, vencimento=None)` calcula a base
+  mensal da NTN-B ou NTN-C com o número-índice realizado do IPCA ou IGP-M,
+  ou o VNA da LFT com o fator Selic acumulado desde 01/07/2000, sem acesso
+  à rede. As origens e os índices iniciais são constantes internas;
+  NTN-C exige vencimento para selecionar a série e seu ajuste de emissão.
+  Para LFT, arredonda o fator em dezesseis casas; para NTN-B e NTN-C, trunca
+  o fator nessa precisão. Trunca o VNA em seis casas, preservando a
+  precisão da origem e evitando encadear VNAs mensais já truncados.
+- Novo módulo `yd.igpm`, com `taxa` e `taxa_serie` para consultar taxas mensais
+  do IGP-M via SGS/BCB. `taxa` retorna `Decimal` (ou `Decimal("NaN")` quando
+  indisponível), e a coluna `taxa` de `taxa_serie` usa `Decimal(18, 4)`.
+  A unidade é decimal: 0,27% corresponde a `Decimal("0.0027")`.
+  `indice` e `indice_serie` fornecem os números-índice da FGV via Ipeadata
+  (série `IGP12_IGPM12`), como `Decimal` e coluna `Decimal(18, 10)`.
+  As dez casas preservam o histórico anterior a 1994. As séries aceitam
+  intervalo ou `ultimos`, com competência `periodo` no formato `YYYYMM`.
+- No CPM, substitua `yd.cpm.data(data)` por `yd.cpm.contratos(data)` e use
+  `yd.cpm.probabilidades(data, tipo_opcao="call")` para as probabilidades.
+  Esta última retorna todas as reuniões disponíveis; filtre o DataFrame para
+  selecionar uma reunião.
+- Leilões do BCB passam de `yd.bc.leiloes` para `yd.tpf.leiloes_bcb`, com nomes
+  de colunas alinhados aos de `yd.tpf.leiloes`.
+- No mercado secundário, `yd.tpf.secundario.ler(fonte)` substitui `ler_zip` e
+  `zip_para_silver`: aceita caminho ou bytes de ZIP e inclui `financeiro` na
+  saída. `nome_arquivo_mensal` deixa de ser público.
+- `yd.ntnf.premio` foi removida. Use `yd.tpf.premios_pre(data)` e filtre
+  `titulo == "NTN-F"` para obter o prêmio bruto.
+- `yd.tpf.taxas` e as consultas `dados` de LFT, LTN, NTN-B, NTN-C e NTN-F
+  preservam colunas e tipos quando não há dados. Nos leilões do Tesouro, PU
+  mínimo informado como zero passa a ser nulo, e o financeiro ofertado usa o
+  PU médio calculado quando necessário.
+- `yd.rmd` passa a propagar erros de download e processamento, em vez de
+  retornar um DataFrame vazio nessas situações.
+
+Consulte as [releases do GitHub](https://github.com/crdcj/PYield/releases)
+para o histórico completo e as notas de migração de versões anteriores.
+
+## Projeto
+
+- [Código-fonte](https://github.com/crdcj/PYield)
+- [Issues](https://github.com/crdcj/PYield/issues)
+- [Licença MIT](LICENSE)

{pyield-0.58.2 → pyield-0.60.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.60.0/pyield/_internal/calendario_igpm.py

@@ -0,0 +1,115 @@
+"""Calendário de divulgação do IGP-M publicado pela FGV IBRE."""
+
+import datetime as dt
+import re
+import ssl
+
+import polars as pl
+import requests
+from lxml import html
+from requests.adapters import HTTPAdapter
+
+from pyield._internal.cache import ttl_cache
+from pyield._internal.retry import retry_padrao
+
+_URL = "https://portalibre.fgv.br/calendario-de-divulgacao"
+
+
+class _AdaptadorFGV(HTTPAdapter):
+    def init_poolmanager(self, *args, **kwargs):
+        contexto = ssl.create_default_context()
+        # O servidor da FGV negocia TLS 1.2 com RSA e AES-GCM, sem ECDHE.
+        cifras = ":".join(cifra["name"] for cifra in contexto.get_ciphers())
+        contexto.set_ciphers(f"{cifras}:AES128-GCM-SHA256")
+        kwargs["ssl_context"] = contexto
+        return super().init_poolmanager(*args, **kwargs)
+
+
+@ttl_cache()
+@retry_padrao
+def _buscar_calendario(ano: int) -> bytes:
+    with requests.Session() as sessao:
+        sessao.mount(_URL, _AdaptadorFGV())
+        resposta = sessao.get(
+            _URL,
+            params={
+                "field_indice_target_id": "128",
+                "field_divulgacao_data_value": f"{ano}-01-01",
+                "field_divulgacao_data_value_1": f"{ano}-12-31",
+            },
+            timeout=30,
+        )
+        resposta.raise_for_status()
+        return resposta.content
+
+
+def _parsear_calendario(conteudo: bytes) -> pl.DataFrame:
+    linhas = []
+    for item in html.fromstring(conteudo).iter("li"):
+        texto = " ".join(" ".join(str(trecho) for trecho in item.itertext()).split())
+        if not re.search(r"\bIGP-M e os componentes:", texto):
+            continue
+        data = re.search(r"\b\d{2}/\d{2}/\d{4}\b", texto)
+        if data is None:
+            raise ValueError("Divulgação do IGP-M sem data válida.")
+        linhas.append(data[0])
+    return pl.DataFrame(
+        {"data_divulgacao": linhas}, schema={"data_divulgacao": pl.String}
+    )
+
+
+def _processar_calendario(dados: pl.DataFrame) -> pl.DataFrame:
+    calendario = (
+        dados.with_columns(
+            data_divulgacao=pl.col("data_divulgacao").str.to_date("%d/%m/%Y")
+        )
+        .select(
+            competencia=pl.col("data_divulgacao").dt.month_start(),
+            data_divulgacao=pl.col("data_divulgacao"),
+        )
+        .unique()
+    )
+    if calendario["competencia"].is_duplicated().any():
+        raise ValueError("Datas conflitantes no calendário do IGP-M.")
+    return calendario.sort("competencia")
+
+
+def calendario(ano: int, *, atualizar: bool = False) -> pl.DataFrame:
+    """Consulta o calendário de divulgação mensal do IGP-M na FGV IBRE.
+
+    Args:
+        ano: Ano das divulgações e competências.
+        atualizar: Ignora e renova o cache de 60 segundos desse ano.
+
+    Returns:
+        DataFrame ordenado por competência. Sem registros, retorna vazio com
+        o mesmo esquema.
+
+    Output Columns:
+        competencia (Date): Primeiro dia do mês da divulgação mensal do IGP-M.
+        data_divulgacao (Date): Data prevista pela FGV IBRE.
+
+    Notes:
+        Fonte: calendário de divulgação da FGV IBRE. Seleciona o IGP-M mensal
+        com seus componentes, excluindo prévias decendiais e outros índices.
+        A competência corresponde ao mês da divulgação mensal. A data prevista
+        não comprova publicação. Não cria janelas estimadas quando faltam dados.
+        Erros de rede e payload inválido são propagados.
+
+    Raises:
+        ValueError: Ano inválido, data inválida ou datas conflitantes.
+
+    Examples:
+        Seleciona as divulgações previstas a partir de hoje, sem incluir
+        prévias decendiais. O resultado depende do calendário da FGV IBRE
+        e não comprova que os índices já tenham sido publicados:
+
+        >>> hoje = yd.hoje()
+        >>> agenda = yd.igpm.calendario(hoje.year)
+        >>> proximas = agenda.filter(pl.col("data_divulgacao") >= hoje)
+    """
+    if type(ano) is not int or not dt.MINYEAR <= ano <= dt.MAXYEAR:
+        raise ValueError("ano deve ser um inteiro entre 1 e 9999.")
+    return _processar_calendario(
+        _parsear_calendario(_buscar_calendario(ano, _atualizar=atualizar))
+    ).filter(pl.col("competencia").dt.year() == ano)