pyield 0.58.0__tar.gz → 0.58.2__tar.gz

{pyield-0.58.0 → pyield-0.58.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyield
-Version: 0.58.0
+Version: 0.58.2
 Summary: Polars-powered toolkit for Brazilian fixed income analysis
 Keywords: fixed-income,brazil,finance,analysis,bonds
 Author: Carlos Carvalho
@@ -78,7 +78,7 @@ uv add pyield
 | `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`, `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`, `vna`, `rentabilidade`, `rentabilidade_expr` |
+| `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`, `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` |
@@ -142,7 +142,7 @@ ou de versões anteriores estão no histórico das
 | `pyield.tpf.vna.calcular_vna(...)` | `yd.vna.calcular_vna(...)` |
 | `yd.ntnb.vna(data)` | `yd.vna.valor("NTN-B", data)` |
 | `yd.ntnb.vnas()` | `yd.vna.historico("NTN-B")` |
-| `vna_projetado(...)` nos módulos de títulos | `yd.vna.projetado(titulo, data, vna_base, inflacao)` |
+| `vna_projetado(...)` nos módulos de títulos | `yd.vna.projetado(titulo, data, vna_base, inflacao)`; para LFT, use `selic=` |
 | `vigencia(data)` nos módulos de títulos | `yd.vna.vigencia(titulo, data)` |
 
 O namespace público segue a autonomia semântica do conceito que o usuário

{pyield-0.58.0 → pyield-0.58.2}/README.md

@@ -53,7 +53,7 @@ uv add pyield
 | `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`, `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`, `vna`, `rentabilidade`, `rentabilidade_expr` |
+| `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`, `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` |
@@ -117,7 +117,7 @@ ou de versões anteriores estão no histórico das
 | `pyield.tpf.vna.calcular_vna(...)` | `yd.vna.calcular_vna(...)` |
 | `yd.ntnb.vna(data)` | `yd.vna.valor("NTN-B", data)` |
 | `yd.ntnb.vnas()` | `yd.vna.historico("NTN-B")` |
-| `vna_projetado(...)` nos módulos de títulos | `yd.vna.projetado(titulo, data, vna_base, inflacao)` |
+| `vna_projetado(...)` nos módulos de títulos | `yd.vna.projetado(titulo, data, vna_base, inflacao)`; para LFT, use `selic=` |
 | `vigencia(data)` nos módulos de títulos | `yd.vna.vigencia(titulo, data)` |
 
 O namespace público segue a autonomia semântica do conceito que o usuário

{pyield-0.58.0 → pyield-0.58.2}/pyield/b3/boletim.py

@@ -436,10 +436,6 @@ def buscar(
         >>> # Múltiplos contratos de uma vez
         >>> df = yd.b3.boletim.buscar("26-04-2024", ["DI1", "DAP"])
 
-        >>> # Feriado ou fim de semana (retorna DataFrame vazio)
-        >>> df = yd.b3.boletim.buscar("25-12-2023", "DI1")
-        >>> df.is_empty()
-        True
     """
     if any_is_empty(data):
         return pl.DataFrame()

{pyield-0.58.0 → pyield-0.58.2}/pyield/bc/sgs.py

@@ -2,6 +2,7 @@
 
 Séries disponíveis:
     - PTAX Venda (SGS 1)
+    - SELIC Diária (SGS 11)
     - SELIC Meta (SGS 432)
     - SELIC Over (SGS 1178)
 
@@ -16,7 +17,7 @@ Exemplo de resposta JSON da API do BCB:
 
 Notas de implementação:
     - Intervalos longos são divididos automaticamente em blocos seguros.
-    - SELIC Over e Meta: valores percentuais convertidos para decimal
+        - SELIC Diária, Over e Meta: valores percentuais convertidos para decimal
       (divididos por 100) e arredondados para 10 casas decimais.
     - PTAX Venda: valor absoluto em R$ arredondado para 4 casas.
 """
@@ -54,6 +55,7 @@ class SerieSGS(Enum):
     """Enum para as séries disponíveis no SGS do Banco Central."""
 
     PTAX_VENDA = 1
+    SELIC_DIARIA = 11
     SELIC_META = 432
     SELIC_OVER = 1178
 

{pyield-0.58.0 → pyield-0.58.2}/pyield/tpf/titulos/_utils.py

@@ -302,3 +302,18 @@ def encontrar_raiz(
     if not math.isfinite(a) or not math.isfinite(b) or a > b:
         raise ValueError("Os limites do intervalo devem ser finitos e ordenados.")
     return _metodo_bissecao(func_diferenca_preco, a, b)
+
+
+def cotacao_por_taxas(pagamentos: pl.DataFrame) -> float:
+    """
+    Soma os valores presentes dos fluxos, arredondados na 10ª casa decimal.
+
+    Args:
+        pagamentos: DataFrame com uma linha por fluxo e as colunas
+            ``valor_pagamento`` (Float64), ``dias_uteis`` (Int64) e
+            ``taxa`` (Float64) alinhadas por linha.
+    """
+    anos_uteis = truncar(pagamentos["dias_uteis"] / 252, 14)
+    fatores = (1 + pagamentos["taxa"]) ** anos_uteis
+    valores_presentes = pagamentos["valor_pagamento"] / fatores
+    return float(valores_presentes.round(10).sum())

{pyield-0.58.0 → pyield-0.58.2}/pyield/tpf/titulos/lft.py

@@ -129,11 +129,13 @@ def cotacao(
         data_vencimento: Data de vencimento do título.
         taxa: Taxa anualizada do título em formato decimal.
             Aceita também percentual explícito: "5.75%" ou "5,75%".
+            Antes do cálculo, é truncada em oito casas decimais (seis na
+            forma percentual), descartando as casas excedentes sem arredondar.
 
     Returns:
         Decimal: Cotação em base 100, truncada em 4 casas decimais.
-            Retorna ``Decimal("NaN")`` quando o prazo até o vencimento não é
-            positivo.
+            Retorna ``Decimal("NaN")`` para entradas nulas ou quando o prazo
+            até o vencimento não é positivo.
 
     Notes:
         A cotação é calculada e retornada na escala percentual (base 100),
@@ -149,14 +151,7 @@ def cotacao(
         ...     taxa="0.1717%",
         ... )
         Decimal('98.9645')
-        >>> lft.cotacao("21-05-2008", "07-03-2014", "-0.0200009%")
-        Decimal('100.1158')
 
-        Entradas nulas retornam Decimal('NaN'):
-        >>> lft.cotacao(
-        ...     data_liquidacao=None, data_vencimento="01-09-2030", taxa="0.1717%"
-        ... )
-        Decimal('NaN')
     """
     taxa = _utils.converter_taxa(taxa)
     if any_is_empty(data_liquidacao, data_vencimento, taxa):
@@ -306,8 +301,10 @@ def pu(
     Calcula o PU da LFT pela metodologia da STN para leilões primários.
 
     Args:
-        vna: Valor nominal atualizado (VNA).
+        vna: Valor nominal atualizado (VNA), truncado em seis casas decimais
+            antes do cálculo, sem arredondar.
         cotacao: Cotação da LFT em base 100.
+            Truncada em quatro casas decimais antes do cálculo, sem arredondar.
 
     Returns:
         Decimal: Preço da LFT truncado em 6 casas decimais.
@@ -321,7 +318,5 @@ def pu(
         >>> from pyield import lft
         >>> lft.pu(15785.324502, 99.9291)
         Decimal('15774.132706')
-        >>> lft.pu(3451.2153459, 100.11589)
-        Decimal('3455.211852')
     """
     return _calcular_pu(vna, cotacao)

{pyield-0.58.0 → pyield-0.58.2}/pyield/tpf/titulos/ltn.py

@@ -138,6 +138,8 @@ def pu(
         data_vencimento: Data de vencimento.
         taxa: Taxa de desconto (YTM) do título em formato decimal.
             Aceita também percentual explícito: "5.75%" ou "5,75%".
+            Antes do cálculo, é truncada em oito casas decimais (seis na
+            forma percentual), descartando as casas excedentes sem arredondar.
 
     Returns:
         Decimal: PU da LTN truncado em seis casas decimais. Retorna

{pyield-0.58.0 → pyield-0.58.2}/pyield/tpf/titulos/ntnb.py

@@ -9,10 +9,10 @@ Convenções de precificação (STN, tabela 3):
       equivalente a 6 casas em termos percentuais.
     - Cada fluxo descontado: arredondado a 10 casas.
 
-Constantes calculadas conforme regras da STN, exibidas em base 100.
+Valores de referência derivados conforme as regras da STN, exibidos em base 100:
 TAXA_CUPOM = ((0.06 + 1) ** 0.5 - 1) * 100  # 6% a.a. com capitalização semestral
 VALOR_CUPOM = round(TAXA_CUPOM, 6) -> 2.956301
-VALOR_FINAL = principal + último cupom = 100 + 2.956301
+VALOR_FINAL = 102.956301
 DIA_CUPOM = 15
 MESES_CUPOM = {2, 5, 8, 11}
 """
@@ -35,7 +35,7 @@ from . import _utils
 
 BASE_COTACAO = 100
 VALOR_CUPOM = 2.956301
-VALOR_FINAL = BASE_COTACAO + VALOR_CUPOM
+VALOR_FINAL = 102.956301
 
 logger = logging.getLogger(__name__)
 
@@ -291,6 +291,8 @@ def cotacao(
         data_vencimento (DateLike): Data de vencimento da NTN-B.
         taxa: Taxa de desconto (TIR) em formato decimal.
             Aceita também percentual explícito: "5.75%" ou "5,75%".
+            Antes do cálculo, é truncada em oito casas decimais (seis na
+            forma percentual), descartando as casas excedentes sem arredondar.
 
     Returns:
         Decimal: Cotação em base 100, truncada em 4 casas. Retorna
@@ -364,8 +366,10 @@ def pu(
     Calcula o PU da NTN-B pela metodologia da STN para leilões primários.
 
     Args:
-        vna: Valor nominal atualizado (VNA).
+        vna: Valor nominal atualizado (VNA), truncado em seis casas decimais
+            antes do cálculo, sem arredondar.
         cotacao: Cotação da NTN-B em base 100.
+            Truncada em quatro casas decimais antes do cálculo, sem arredondar.
 
     Returns:
         Decimal: Preço da NTN-B truncado em 6 casas decimais.
@@ -381,8 +385,6 @@ def pu(
         Decimal('4271.864805')
         >>> ntnb.pu(4315.498383, 100.6409)
         Decimal('4343.156412')
-        >>> ntnb.pu(1728.4611369, 97.08139)
-        Decimal('1678.012540')
     """
     return _calcular_pu(vna, cotacao)
 

{pyield-0.58.0 → pyield-0.58.2}/pyield/tpf/titulos/ntnb1.py

@@ -227,6 +227,7 @@ def cotacao(
         data_vencimento: Data de vencimento da NTN-B1.
         taxa: Taxa de desconto (YTM) usada no valor presente.
             Aceita também percentual explícito: "5.75%" ou "5,75%".
+            A taxa de entrada não é truncada antes do cálculo.
         nome_comercial: Nome comercial (Renda+ ou Educa+).
 
     Returns:
@@ -285,21 +286,6 @@ def _validar_curva_zero(curva_zero: pl.DataFrame) -> pl.DataFrame:
     )
 
 
-def _cotacao_por_taxas(pagamentos: pl.DataFrame) -> float:
-    """
-    Soma os valores presentes dos fluxos, arredondados na 10ª casa decimal.
-
-    Args:
-        pagamentos: DataFrame com uma linha por fluxo e as colunas
-            ``valor_pagamento`` (Float64), ``dias_uteis`` (Int64) e
-            ``taxa`` (Float64) alinhadas por linha.
-    """
-    anos_uteis = _utils.truncar(pagamentos["dias_uteis"] / 252, 14)
-    fatores = (1 + pagamentos["taxa"]) ** anos_uteis
-    valores_presentes = pagamentos["valor_pagamento"] / fatores
-    return float(valores_presentes.round(10).sum())
-
-
 def cotacao_curva_zero(
     data_liquidacao: DateLike,
     data_vencimento: DateLike,
@@ -347,7 +333,7 @@ def cotacao_curva_zero(
         extrapolar=True,
     )
     pagamentos = fluxos.with_columns(dias_uteis=dias_fluxos, taxa=taxas_fluxos)
-    return _cotacao_por_taxas(pagamentos)
+    return _utils.cotacao_por_taxas(pagamentos)
 
 
 def _resolver_taxa_equivalente(
@@ -368,7 +354,7 @@ def _resolver_taxa_equivalente(
 
     def erro(taxa: float) -> float:
         pagamentos = pagamentos_base.with_columns(taxa=pl.lit(taxa, dtype=pl.Float64))
-        return _cotacao_por_taxas(pagamentos) - cotacao_alvo
+        return _utils.cotacao_por_taxas(pagamentos) - cotacao_alvo
 
     limite_inferior = -0.99
     limite_superior = max(1.0, 2 * taxa_inicial + 0.01)
@@ -435,7 +421,7 @@ def taxa_curva_zero(
         extrapolar=True,
     )
     pagamentos_base = fluxos.with_columns(dias_uteis=dias_fluxos)
-    cotacao_alvo = _cotacao_por_taxas(pagamentos_base.with_columns(taxa=taxas_zero))
+    cotacao_alvo = _utils.cotacao_por_taxas(pagamentos_base.with_columns(taxa=taxas_zero))
     return _resolver_taxa_equivalente(
         cotacao_alvo,
         pagamentos_base,
@@ -451,8 +437,10 @@ def pu(
     Calcula o preço (PU) da NTN-B1 pelas regras do Tesouro Nacional.
 
     Args:
-        vna: Valor nominal atualizado (VNA).
+        vna: Valor nominal atualizado (VNA), truncado em seis casas decimais
+            antes do cálculo, sem arredondar.
         cotacao: Cotação da NTN-B1 em base 100.
+            Truncada em quatro casas decimais antes do cálculo, sem arredondar.
 
     Returns:
         Decimal: Preço da NTN-B1 truncado em 6 casas decimais.

{pyield-0.58.0 → pyield-0.58.2}/pyield/tpf/titulos/ntnbp.py

@@ -1,4 +1,22 @@
-"""Precificação de NTN-B Principal."""
+"""Precificação de NTN-B Principal (Tesouro IPCA+ sem cupons).
+
+Convenções de cálculo:
+    - Fluxo único no vencimento, atualizado pelo IPCA via VNA.
+    - Prazo de desconto: dias úteis / 252, truncado a 14 casas.
+    - Cotação: base 100, truncada a 4 casas.
+    - VNA de entrada e PU retornado: truncados a 6 casas.
+    - Taxa da curva: float interpolado por flat-forward, sem arredondamento.
+
+O exemplo de precificação do Tesouro Direto (páginas 2 a 4) usa cotação com
+4 casas, embora o texto da página 4 mencione 2. O PU da biblioteca mantém
+6 casas; o preço em centavos do documento exige truncamento adicional.
+O documento parte de uma taxa pactuada e não especifica a regra de
+arredondamento da taxa obtida por curva zero.
+
+References:
+    - Tesouro Direto — Cálculo da Rentabilidade: Tesouro IPCA+.
+      <https://www.tesourodireto.com.br/documents/d/guest/tesouro_ipca_juros_semestrais>
+"""
 
 from decimal import Decimal
 
@@ -24,6 +42,7 @@ def cotacao(
         data_vencimento: Data de vencimento.
         taxa_tir: Taxa interna de retorno anualizada do título.
             Aceita também percentual explícito: "5.75%" ou "5,75%".
+            A taxa de entrada não é truncada antes do cálculo.
 
     Returns:
         Decimal: Cotação em base 100, truncada em 4 casas decimais. Retorna
@@ -33,6 +52,16 @@ def cotacao(
         >>> from pyield import ntnbp
         >>> ntnbp.cotacao("02-12-2025", "15-05-2029", "7.77%")
         Decimal('77.4630')
+
+        Exemplo do Tesouro Direto, páginas 2 a 4: liquidação em 03/01/2012,
+        vencimento em 15/05/2015, prazo de 846 dias úteis e taxa de 5,17% a.a.
+
+        >>> ntnbp.cotacao("03-01-2012", "15-05-2015", "5.17%")
+        Decimal('84.4317')
+
+    References:
+        - Tesouro Direto — Tesouro IPCA+, páginas 2 a 4.
+          <https://www.tesourodireto.com.br/documents/d/guest/tesouro_ipca_juros_semestrais>
     """
     if isinstance(taxa_tir, str):
         taxa_tir = float(_utils.converter_taxa(taxa_tir))
@@ -52,8 +81,10 @@ def pu(vna: float | Decimal, cotacao: float | Decimal) -> Decimal:
     Calcula o preço (PU) da NTN-B Principal.
 
     Args:
-        vna: Valor nominal atualizado (VNA).
+        vna: Valor nominal atualizado (VNA), truncado em seis casas decimais
+            antes do cálculo, sem arredondar.
         cotacao: Cotação da NTN-B Principal em base 100.
+            Truncada em quatro casas decimais antes do cálculo, sem arredondar.
 
     Returns:
         Decimal: Preço da NTN-B Principal truncado em 6 casas decimais.
@@ -63,6 +94,18 @@ def pu(vna: float | Decimal, cotacao: float | Decimal) -> Decimal:
         >>> cot = ntnbp.cotacao("02-12-2025", "15-05-2029", "7.77%")
         >>> ntnbp.pu(4567.033825, cot)
         Decimal('3537.761411')
+
+        Exemplo do Tesouro Direto, página 4, com o VNA projetado publicado.
+        O retorno preserva seis casas; truncado em centavos, corresponde
+        ao preço de R$ 1.776,77 apresentado no documento.
+
+        >>> cot = ntnbp.cotacao("03-01-2012", "15-05-2015", "5.17%")
+        >>> ntnbp.pu(Decimal("2104.390122"), cot)
+        Decimal('1776.772354')
+
+    References:
+        - Tesouro Direto — Tesouro IPCA+, página 4.
+          <https://www.tesourodireto.com.br/documents/d/guest/tesouro_ipca_juros_semestrais>
     """
     if any_is_empty(vna, cotacao):
         return Decimal("NaN")
@@ -97,10 +140,13 @@ def taxa(
     """
     Obtém a TIR da NTN-B Principal a partir da curva zero informada.
 
-    A taxa zero correspondente ao vencimento é interpolada por flat-forward e
-    arredondada em quatro casas decimais. Como a NTN-B Principal possui um único
+    A taxa zero correspondente ao vencimento é interpolada por flat-forward,
+    sem arredondamento. Como a NTN-B Principal possui um único
     fluxo no vencimento, essa taxa zero também é a TIR do título.
 
+    Arredondamentos comerciais e spreads de compra ou venda ficam a cargo
+    do consumidor.
+
     A curva pode ser produzida por :func:`pyield.ntnb.taxas_zero`. Para
     cálculos em lote, ela deve ser construída uma única vez e reutilizada entre
     os títulos.
@@ -111,7 +157,7 @@ def taxa(
         curva_zero: DataFrame com as colunas ``dias_uteis`` e ``taxa_zero``.
 
     Returns:
-        float: TIR anualizada, arredondada em quatro casas decimais.
+        float: TIR anualizada em formato decimal, sem arredondamento.
             Retorna ``NaN`` se a liquidação for igual ou posterior ao vencimento.
     """
     if any_is_empty(data_liquidacao, data_vencimento):
@@ -122,12 +168,11 @@ def taxa(
         return float("nan")
 
     curva = _normalizar_curva_zero(curva_zero)
-    taxa_zero = interpolador.Interpolador(
+    return interpolador.Interpolador(
         curva["dias_uteis"],
         curva["taxa_zero"],
         metodo="flat_forward",
     ).interpolar(dias_uteis)
-    return round(taxa_zero, 4)
 
 
 def dv01(

{pyield-0.58.0 → pyield-0.58.2}/pyield/tpf/titulos/ntnc.py

@@ -1,28 +1,40 @@
+"""Cálculos e dados de NTN-C.
+
+Convenções de precificação (STN, tabela 3):
+    - Cotação em base 100, truncada a 4 casas.
+    - VNA recebido no cálculo do PU: truncado a 6 casas.
+    - Prazo de desconto: dias úteis / 252, truncado a 14 casas.
+    - PU: truncado a 6 casas.
+    - Taxa implícita retornada: decimal, truncada a 8 casas,
+      equivalente a 6 casas em termos percentuais.
+    - Cada fluxo descontado: arredondado a 10 casas.
+
+Valores de referência derivados conforme as regras da STN, exibidos em base 100.
+Para NTN-C com vencimento em 01-01-2031:
+    PRINCIPAL = 100
+    TAXA_CUPOM = ((0.12 + 1) ** 0.5 - 1) * 100  # 12% a.a. com capitalização semestral
+    VALOR_CUPOM_2031 = round(TAXA_CUPOM, 6) -> 5.830052
+    VALOR_FINAL_2031 = 105.830052
+
+Para as demais NTN-C:
+    TAXA_CUPOM = ((0.06 + 1) ** 0.5 - 1) * 100  # 6% a.a. com capitalização semestral
+    VALOR_CUPOM = round(TAXA_CUPOM, 6) -> 2.956301
+    VALOR_FINAL = 102.956301
+"""
+
 import datetime as dt
+import math
 from decimal import Decimal
 
 import polars as pl
 
 import pyield._internal.converters as conversores
-from pyield import du
+from pyield import du, interpolador
 from pyield._internal.numbers import truncar_decimal
 from pyield._internal.types import DateLike, any_is_empty
 
 from . import _utils
 
-"""
-Constantes calculadas conforme regras da STN, exibidas em base 100.
-Válido para NTN-C com vencimento 01-01-2031:
-PRINCIPAL = 100
-TAXA_CUPOM = ((0.12 + 1) ** 0.5 - 1) * 100  # 12% a.a. com capitalização semestral
-VALOR_CUPOM_2031 = round(TAXA_CUPOM, 6) -> 5.830052
-VALOR_FINAL_2031 = principal + último cupom = 100 + 5.830052
-
-Para as demais NTN-C:
-TAXA_CUPOM = ((0.06 + 1) ** 0.5 - 1) * 100  # 6% a.a. com capitalização semestral
-VALOR_CUPOM = round(TAXA_CUPOM, 6) -> 2.956301
-VALOR_FINAL = principal + último cupom = 100 + 2.956301
-"""
 # Valores usados nos cálculos, em base 100, com 6 casas decimais
 VALOR_CUPOM_2031 = 5.830052
 VALOR_FINAL_2031 = 105.830052
@@ -242,6 +254,8 @@ def cotacao(
         data_vencimento: Data de vencimento da NTN-C.
         taxa: Taxa de desconto (YTM) em formato decimal.
             Aceita também percentual explícito: "5.75%" ou "5,75%".
+            Antes do cálculo, é truncada em oito casas decimais (seis na
+            forma percentual), descartando as casas excedentes sem arredondar.
 
     Returns:
         Decimal: Cotação em base 100, truncada em 4 casas decimais.
@@ -263,8 +277,6 @@ def cotacao(
         >>> from pyield import ntnc
         >>> ntnc.cotacao("21-03-2025", "01-01-2031", "6.7626%")
         Decimal('126.4958')
-        >>> ntnc.cotacao("21-05-2008", "01-03-2011", "6.9000009%")
-        Decimal('99.0981')
     """
     taxa = _utils.converter_taxa(taxa)
     if any_is_empty(data_liquidacao, data_vencimento, taxa):
@@ -287,6 +299,137 @@ def cotacao(
     return truncar_decimal(cotacao_total, 4)
 
 
+def _pagamentos_curva_zero(
+    data_liquidacao: DateLike,
+    data_vencimento: DateLike,
+    curva_zero: pl.DataFrame,
+) -> pl.DataFrame:
+    """Prepara fluxos e taxas da curva fornecida, sem escolher seu indexador."""
+    if not {"dias_uteis", "taxa_zero"}.issubset(curva_zero.columns):
+        raise ValueError(
+            "Curva zero deve conter as colunas 'dias_uteis' e 'taxa_zero'."
+        )
+    curva = curva_zero.select(
+        pl.col("dias_uteis").cast(pl.Float64),
+        pl.col("taxa_zero").cast(pl.Float64),
+    )
+    if (
+        curva.is_empty()
+        or curva.select(
+            (
+                pl.col("dias_uteis").is_null()
+                | ~pl.col("dias_uteis").is_finite()
+                | (pl.col("dias_uteis") <= 0)
+                | (pl.col("dias_uteis") != pl.col("dias_uteis").floor())
+                | pl.col("taxa_zero").is_null()
+                | ~pl.col("taxa_zero").is_finite()
+                | (pl.col("taxa_zero") <= -1)
+            ).any()
+        ).item()
+    ):
+        raise ValueError(
+            "Curva deve ter prazos inteiros positivos e taxas finitas > -1."
+        )
+    if curva["dias_uteis"].n_unique() != curva.height:
+        raise ValueError("Curva zero não pode conter prazos duplicados.")
+
+    fluxos = fluxos_caixa(data_liquidacao, data_vencimento)
+    dias = du.contar(data_liquidacao, fluxos["data_pagamento"])
+    taxas = interpolador.interpolar(
+        dias, curva["dias_uteis"].cast(pl.Int64), curva["taxa_zero"], extrapolar=True
+    )
+    return fluxos.with_columns(dias_uteis=dias, taxa=taxas)
+
+
+def cotacao_curva_zero(
+    data_liquidacao: DateLike,
+    data_vencimento: DateLike,
+    curva_zero: pl.DataFrame,
+) -> float:
+    """Calcula a cotação da NTN-C descontando seus fluxos pela curva informada.
+
+    Args:
+        data_liquidacao: Data de liquidação, exclusiva para seleção dos fluxos.
+        data_vencimento: Data de vencimento da NTN-C.
+        curva_zero: DataFrame com ``dias_uteis`` (prazos inteiros positivos,
+            únicos) e ``taxa_zero`` (taxas anuais decimais finitas maiores que -1).
+            A curva deve conter ao menos um vértice; a ordem é indiferente.
+
+    Returns:
+        float: Cotação em base 100, sem truncamento final. Retorna NaN para
+            datas ausentes, ausência de fluxos ou resultado não finito.
+
+    Raises:
+        ValueError: Curva vazia, colunas ausentes ou vértices inválidos.
+
+    Notes:
+        Usa os fluxos contratuais de ``fluxos_caixa``, sem deslocar suas datas.
+        O prazo em dias úteis / 252 é truncado em 14 casas. A interpolação é
+        flat-forward, com taxa constante nas duas pontas da curva. Cada valor
+        presente é arredondado em 10 casas, como em ``cotacao``; a soma não é
+        truncada, pois serve de alvo para a TIR equivalente.
+
+        A curva é uma hipótese do consumidor. A biblioteca não escolhe uma
+        curva de IPCA como aproximação para IGP-M nem aplica piso ANBIMA.
+        Esta operação não representa uma cotação consultada em fonte externa.
+    """
+    if any_is_empty(data_liquidacao, data_vencimento):
+        return float("nan")
+    pagamentos = _pagamentos_curva_zero(data_liquidacao, data_vencimento, curva_zero)
+    if pagamentos.is_empty():
+        return float("nan")
+    cotacao = _utils.cotacao_por_taxas(pagamentos)
+    return cotacao if math.isfinite(cotacao) else float("nan")
+
+
+def taxa_curva_zero(
+    data_liquidacao: DateLike,
+    data_vencimento: DateLike,
+    curva_zero: pl.DataFrame,
+) -> float:
+    """Calcula a TIR equivalente à cotação da NTN-C pela curva zero informada.
+
+    Args:
+        data_liquidacao: Data de liquidação.
+        data_vencimento: Data de vencimento da NTN-C.
+        curva_zero: DataFrame com ``dias_uteis`` e ``taxa_zero``, com os mesmos
+            requisitos de ``cotacao_curva_zero``.
+
+    Returns:
+        float: TIR anualizada decimal, sem arredondamento comercial. Retorna
+            NaN para datas ausentes, ausência de fluxos com prazo positivo,
+            resultado não finito ou falha de convergência.
+
+    Raises:
+        ValueError: Curva vazia, colunas ausentes ou vértices inválidos.
+
+    Notes:
+        Usa datas, interpolação e precisão de ``cotacao_curva_zero``. Resolve
+        por bisseção a taxa única que reproduz sua cotação, sem truncar a taxa
+        durante a busca. Não inverte um PU nem a cotação truncada de ``cotacao``.
+        O intervalo é delimitado pelas menores e maiores taxas interpoladas
+        dos fluxos. A busca para por erro de cotação zero ou meia largura do
+        intervalo inferior a 1e-12, com limite de 100 iterações.
+        A escolha da curva e eventuais spreads ou pisos ficam com o consumidor.
+    """
+    if any_is_empty(data_liquidacao, data_vencimento):
+        return float("nan")
+    pagamentos = _pagamentos_curva_zero(data_liquidacao, data_vencimento, curva_zero)
+    if pagamentos.is_empty() or not (pagamentos["dias_uteis"] > 0).any():
+        return float("nan")
+    alvo = _utils.cotacao_por_taxas(pagamentos)
+    if not math.isfinite(alvo):
+        return float("nan")
+
+    def erro(taxa: float) -> float:
+        return (
+            _utils.cotacao_por_taxas(pagamentos.with_columns(taxa=pl.lit(taxa))) - alvo
+        )
+
+    taxas = pagamentos["taxa"].sort()
+    return _utils.encontrar_raiz(erro, intervalo=(float(taxas[0]), float(taxas[-1])))
+
+
 def _calcular_pu(
     vna: float | Decimal,
     cotacao: float | Decimal,
@@ -309,8 +452,10 @@ def pu(
     pu = VNA * cotacao / 100
 
     Args:
-        vna: Valor nominal atualizado (VNA).
+        vna: Valor nominal atualizado (VNA), truncado em seis casas decimais
+            antes do cálculo, sem arredondar.
         cotacao: Cotação da NTN-C em base 100.
+            Truncada em quatro casas decimais antes do cálculo, sem arredondar.
 
     Returns:
         Decimal: Preço da NTN-C truncado em 6 casas decimais.
@@ -324,8 +469,6 @@ def pu(
         >>> from pyield import ntnc
         >>> ntnc.pu(6598.913723, 126.4958)
         Decimal('8347.348705')
-        >>> ntnc.pu(2126.4737349, 99.09819)
-        Decimal('2107.295067')
     """
     return _calcular_pu(vna, cotacao)
 

{pyield-0.58.0 → pyield-0.58.2}/pyield/tpf/titulos/ntnf.py

@@ -7,7 +7,7 @@ Convenções de precificação (STN, tabela 3):
       equivalente a 6 casas em termos percentuais.
     - Cada fluxo descontado: arredondado a 9 casas.
 
-Constantes calculadas conforme regras da STN
+Valores de referência derivados conforme as regras da STN:
 TAXA_CUPOM = (0.10 + 1) ** 0.5 - 1  -> 10% a.a. com capitalização semestral
 VALOR_FACE = 1000
 VALOR_CUPOM = round(VALOR_FACE * TAXA_CUPOM, 5)
@@ -40,7 +40,7 @@ from .pre import premios_pre as _premios_pre
 
 VALOR_FACE = 1000
 VALOR_CUPOM = 48.80885
-VALOR_FINAL = VALOR_FACE + VALOR_CUPOM
+VALOR_FINAL = 1048.80885
 
 logger = logging.getLogger(__name__)
 
@@ -340,6 +340,8 @@ def pu(
         data_vencimento (DateLike): Data de vencimento do título.
         taxa: Taxa de desconto (TIR) em formato decimal.
             Aceita também percentual explícito: "5.75%" ou "5,75%".
+            Antes do cálculo, é truncada em oito casas decimais (seis na
+            forma percentual), descartando as casas excedentes sem arredondar.
 
     Returns:
         Decimal: Preço da NTN-F truncado em seis casas decimais.
@@ -357,8 +359,6 @@ def pu(
         Decimal('895.359254')
         >>> ntnf.pu("01-07-2024", "01-01-2027", "10%")
         Decimal('999.931303')
-        >>> ntnf.pu("21-05-2008", "01-01-2014", "13.6600009%")
-        Decimal('903.075616')
     """
     return truncar_decimal(_calcular_pu(data_liquidacao, data_vencimento, taxa), 6)
 

{pyield-0.58.0 → pyield-0.58.2}/pyield/vna/__init__.py

@@ -10,4 +10,12 @@ from pyield.vna._consulta import (
     vigencia,
 )
 
-__all__ = ["calcular_vna", "TipoTitulo", "historico", "projetado", "ultimo", "valor", "vigencia"]
+__all__ = [
+    "calcular_vna",
+    "TipoTitulo",
+    "historico",
+    "projetado",
+    "ultimo",
+    "valor",
+    "vigencia",
+]

{pyield-0.58.0 → pyield-0.58.2}/pyield/vna/_consulta.py

@@ -6,6 +6,7 @@ from typing import Literal
 
 import polars as pl
 
+from pyield import du
 from pyield._internal.converters import converter_datas
 from pyield._internal.types import DateLike, any_is_empty
 from pyield.vna import _lft, _ntnb, _ntnc
@@ -171,26 +172,73 @@ def projetado(
     titulo: TipoTitulo,
     data: DateLike,
     vna_base: float | Decimal,
-    inflacao: float | Decimal,
+    inflacao: float | Decimal | None = None,
+    *,
+    selic: float | Decimal | str | None = None,
 ) -> Decimal:
-    """Projeta o VNA mensal com base e inflação fornecidas pelo consumidor.
+    """Projeta o VNA do título conforme sua metodologia.
 
     Args:
-        titulo: NTN-B ou NTN-C. Projeção de LFT não está disponível.
+        titulo: LFT, NTN-B ou NTN-C.
         data: Data para a qual projetar o VNA.
-        vna_base: VNA no início da vigência que contém a data.
-        inflacao: Variação mensal percentual; 0.45 representa 0,45%.
+        vna_base: VNA-base correspondente ao início da vigência ou ao último
+            dia útil anterior à data, conforme o título.
+        inflacao: Para NTN-B e NTN-C, variação mensal percentual; ``0.45``
+            representa 0,45%. Para LFT, taxa anual decimal, finita e maior
+            que -1; informe-a em ``selic``.
+        selic: Obrigatória apenas para LFT. Aceita taxa decimal ou
+            percentual explícito, como ``"13.65%"``. Para reproduzir o
+            acruamento oficial da LFT, use a taxa Selic diária publicada pelo
+            SGS 11. Como ela é publicada em percentual, ``0,050788%`` equivale
+            à taxa decimal ``0,00050788`` e ao fator derivado ``1,00050788``.
+            Converta essa taxa diária para uma taxa anual equivalente. A Selic
+            Over do SGS 1178 é anualizada e serve apenas como aproximação. Para
+            NTN-B e NTN-C, deve ser omitida.
 
     Returns:
         Decimal: VNA projetado com seis casas; NaN para entradas nulas.
 
     Notes:
-        Segue a metodologia STN das funções de projeção de NTN-B e NTN-C:
-        base truncada em seis casas, inflação arredondada em duas e expoente
-        em dias corridos truncado em catorze. Não busca projeções externas.
+        NTN-B e NTN-C seguem a metodologia STN: base truncada em seis casas,
+        inflação arredondada em duas e expoente em dias corridos truncado em
+        catorze. LFT usa dias úteis, base 252 e capitalização pela taxa anual
+        informada. A taxa Selic diária publicada pelo SGS 11 é a referência
+        exata para o acruamento; o fator usado no cálculo é ``1 + taxa`` em
+        formato decimal. A função não busca a taxa automaticamente nem faz
+        projeções externas.
 
     Raises:
-        ValueError: Se o título não for NTN-B ou NTN-C, a base não for positiva
-            ou a inflação for menor ou igual a -100%.
+        ValueError: Se o título for inválido, a taxa for informada para o
+            título errado, ou houver violação dos limites da metodologia
+            específica.
+
+    Examples:
+        >>> import pyield as yd
+        >>> yd.vna.projetado("NTN-B", "30-06-2026", 4731.856412, 0.45)
+        Decimal('4742.491138')
+        >>> yd.vna.projetado(
+        ...     "LFT",
+        ...     "18-09-2026",
+        ...     19905.773236,
+        ...     selic="13.65%",
+        ... )
+        Decimal('19915.882987')
     """
+    if titulo not in {"LFT", "NTN-B", "NTN-C"}:
+        raise ValueError("Título deve ser LFT, NTN-B ou NTN-C.")
+    if titulo == "LFT":
+        if inflacao is not None:
+            raise ValueError("Use selic para a projeção da LFT.")
+        if selic is None:
+            return Decimal("NaN")
+        if any_is_empty(selic):
+            return Decimal("NaN")
+        data_convertida = converter_datas(data)
+        if du.eh_dia_util(data_convertida):
+            data_base = du.deslocar(data_convertida, -1, ajuste="anterior")
+        else:
+            data_base = du.deslocar(data_convertida, 0, ajuste="anterior")
+        return _lft.projetado_lft(data_base, data, vna_base, selic)
+    if selic is not None:
+        raise ValueError("selic aplica-se apenas à projeção da LFT.")
     return _modulo_mensal(titulo).vna_projetado(data, vna_base, inflacao)

{pyield-0.58.0 → pyield-0.58.2}/pyield/vna/_lft.py

@@ -16,16 +16,99 @@ valores e retorna o VNA único.
 """
 
 import datetime as dt
-from decimal import Decimal
+import logging
+from decimal import Decimal, localcontext
 
 import requests
 
+from pyield import du
 from pyield._internal.cache import ttl_cache
 from pyield._internal.converters import converter_datas, data_referencia_valida
+from pyield._internal.numbers import truncar_decimal
 from pyield._internal.retry import retry_padrao
 from pyield._internal.types import DateLike, any_is_empty
+from pyield.tpf.titulos._utils import converter_taxa
 
 CODIGO_LFT = "210100"
+_LOGGER = logging.getLogger(__name__)
+
+
+def projetado_lft(
+    data_base: DateLike,
+    data: DateLike,
+    vna_base: float | Decimal,
+    taxa_anual: float | Decimal | str,
+) -> Decimal:
+    """Projeta o VNA da LFT com uma taxa anual constante fornecida pelo consumidor.
+
+    Args:
+        data_base: Data à qual corresponde o VNA-base.
+        data: Data do próximo dia útil de acruamento após a data-base.
+        vna_base: VNA-base em reais, positivo e finito.
+        taxa_anual: Taxa anual decimal, finita e maior que -1. Aceita também
+            percentual explícito, como ``"13.65%"`` ou ``"13,65%"``.
+
+    Returns:
+        Decimal: VNA projetado, truncado em seis casas decimais. Retorna
+            ``Decimal('NaN')`` para entradas ausentes ou NaN.
+
+    Notes:
+        Calcula ``vna_base * (1 + taxa_anual) ** (dias_uteis / 252)``.
+        Usa ``yd.du.contar`` com calendário automático de feriados brasileiros:
+        data-base inclusiva e data final exclusiva, sem deslocar as datas.
+        Com zero dias úteis, retorna o VNA-base truncado em seis casas.
+
+        O cálculo usa Decimal com 28 dígitos de precisão. Entradas float são
+        convertidas pela representação decimal textual. Percentuais explícitos
+        são convertidos para decimal sem truncamento. Não há truncamentos
+        intermediários nem arredondamento comercial da taxa.
+
+        Não consulta fontes externas nem escolhe automaticamente uma taxa. Para
+        reproduzir o acruamento oficial da LFT, use a taxa Selic diária
+        publicada pela série SGS 11. Como ela é publicada em percentual,
+        ``0,050788%`` corresponde à taxa decimal ``0,00050788`` e ao fator
+        derivado ``1,00050788``. Converta essa taxa diária para uma taxa anual
+        equivalente antes de informar ``taxa_anual``. A Selic Over da série
+        SGS 1178 é anualizada e serve apenas como aproximação. O resultado é
+        uma projeção sob a taxa informada, não um VNA oficial realizado. A
+        taxa pode ser negativa, desde que maior que -100%.
+
+    Raises:
+        ValueError: Data final anterior à base, VNA não positivo ou não finito,
+            taxa não finita ou menor ou igual a -100%, ou data malformada.
+
+    Examples:
+        >>> from decimal import Decimal
+        >>> projetado_lft(
+        ...     "17-09-2026",
+        ...     "18-09-2026",
+        ...     Decimal("19905.773236"),
+        ...     "13.65%",
+        ... )
+        Decimal('19915.882987')
+    """
+    if any_is_empty(data_base, data, vna_base, taxa_anual):
+        return Decimal("NaN")
+    inicio = converter_datas(data_base)
+    fim = converter_datas(data)
+    if fim < inicio:
+        raise ValueError("A data de projeção não pode ser anterior à data-base.")
+    dias_uteis = du.contar(inicio, fim)
+    if dias_uteis != 1:
+        _LOGGER.warning(
+            "A projeção da LFT avançou uma quantidade diferente de um dia útil.",
+        )
+    base = vna_base if isinstance(vna_base, Decimal) else Decimal(str(vna_base))
+    taxa_anual = converter_taxa(taxa_anual)
+    taxa = taxa_anual if isinstance(taxa_anual, Decimal) else Decimal(str(taxa_anual))
+    if not base.is_finite() or base <= 0:
+        raise ValueError("O VNA-base deve ser positivo e finito.")
+    if not taxa.is_finite() or taxa <= -1:
+        raise ValueError("A taxa anual deve ser finita e maior que -100%.")
+    with localcontext() as contexto:
+        contexto.prec = 28
+        expoente = Decimal(dias_uteis) / 252
+        return truncar_decimal(base * (1 + taxa) ** expoente, 6)
 
 
 @ttl_cache()

{pyield-0.58.0 → pyield-0.58.2}/pyproject.toml

@@ -25,7 +25,7 @@ dependencies = [
     "fastexcel>=0.19.0",
     "tzdata>=2024.1; platform_system == 'Windows'",
 ]
-version = "0.58.0"
+version = "0.58.2"
 
 [[project.authors]]
 name = "Carlos Carvalho"

{pyield-0.58.0 → pyield-0.58.2}/pyproject.toml.orig

@@ -20,7 +20,7 @@ dependencies = [
     "fastexcel>=0.19.0",
     "tzdata>=2024.1; platform_system == 'Windows'",
 ]
-version = "0.58.0"
+version = "0.58.2"
 
 [project.urls]
 Homepage = "https://github.com/crdcj/PYield"