PYield 0.40.3__tar.gz → 0.40.4__tar.gz

{pyield-0.40.3 → pyield-0.40.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PYield
-Version: 0.40.3
+Version: 0.40.4
 Summary: A Python library for analysis of fixed income instruments in Brazil
 Project-URL: Source, https://github.com/crdcj/PYield
 Author-email: Carlos Carvalho <cr.cj@outlook.com>

pyield-0.40.4/pyield/__about__.py

@@ -0,0 +1 @@
+__version__ = "0.40.4"

{pyield-0.40.3 → pyield-0.40.4}/pyield/anbima/tpf.py

@@ -211,15 +211,14 @@ def _add_dv01(df_input: pl.DataFrame) -> pl.DataFrame:
     return df
 
 
-def _add_di_rate(df: pl.DataFrame) -> pl.DataFrame:
+def _add_di_rate(df: pl.DataFrame, ref_date: dt.date) -> pl.DataFrame:
     """Add the DI rate column to the DataFrame."""
-    reference_date = df["ReferenceDate"].item(0)
     di_rates = di1.interpolate_rates(
-        dates=reference_date,
+        dates=ref_date,
         expirations=df["MaturityDate"],
         extrapolate=True,
     )
-    df = df.with_columns(di_rates.alias("DIRate"))
+    df = df.with_columns(DIRate=di_rates)
     return df
 
 
@@ -298,7 +297,7 @@ def _fetch_tpf_data(date: dt.date) -> pl.DataFrame:
         df = _process_raw_df(df)
         df = _add_duration(df)
         df = _add_dv01(df)
-        df = _add_di_rate(df)
+        df = _add_di_rate(df, date)
         df = _custom_sort_and_order(df)
 
         return df

{pyield-0.40.3 → pyield-0.40.4}/pyield/b3/di1.py

@@ -5,7 +5,6 @@ import polars as pl
 
 import pyield.converters as cv
 from pyield import b3, bday, interpolator
-from pyield.config import TIMEZONE_BZ
 from pyield.data_cache import get_cached_dataset
 from pyield.types import DateArray, DateScalar, has_null_args
 
@@ -13,42 +12,40 @@ logger = logging.getLogger(__name__)
 
 
 def _load_with_intraday(dates: list[dt.date]) -> pl.DataFrame:
-    """Busca dados de DI, incluindo dados intraday para o dia corrente se necessário."""
+    """Busca dados de DI, incluindo dados intraday para datas ausentes no cache."""
     # 1. Busca inicial no cache com as datas solicitadas pelo usuário.
     df_cached = get_cached_dataset("di1").filter(pl.col("TradeDate").is_in(dates))
 
-    today = dt.datetime.now(TIMEZONE_BZ).date()
-    last_bday = bday.last_business_day()
+    # 2. Identifica datas solicitadas que não estão no cache
+    cached_dates = set(df_cached["TradeDate"].unique().to_list())
+    missing_dates = [d for d in dates if d not in cached_dates]
 
-    # 2. Lógica para buscar dados intraday.
-    #    Isso é necessário quando o usuário solicita os dados do dia corrente
-    #    e eles ainda não foram persistidos no cache (processo noturno).
-    # Condição 1: O dia de hoje foi solicitado.
-    has_today = today in dates
-    # Condição 2: E ainda não está no cache.
-    is_today_not_in_cache = df_cached.filter(pl.col("TradeDate") == today).is_empty()
-    # Condição 3: E hoje é o último dia útil.
-    is_today_last_bday = today == last_bday
+    # 3. Para cada data faltante, tenta buscar dados via API
+    dfs_to_concat = [df_cached] if not df_cached.is_empty() else []
 
-    if has_today and is_today_not_in_cache and is_today_last_bday:
+    for ref_date in missing_dates:
         try:
-            df_intraday = b3.futures(contract_code="DI1", date=today)
-            if "SettlementPrice" not in df_intraday.columns or df_intraday.is_empty():
+            df_missing = b3.futures(contract_code="DI1", date=ref_date)
+
+            # Só adiciona se tiver SettlementPrice
+            if "SettlementPrice" in df_missing.columns:
+                df_missing = df_missing.drop("DaysToExp", strict=False)
+                dfs_to_concat.append(df_missing)
+            else:
                 logger.warning(
-                    f"Ainda sem dados de ajustes intraday para {today}."
-                    " Retornando apenas dados do cache."
+                    f"Dados para {ref_date} não contêm 'SettlementPrice'. "
+                    "Pulando esta data."
                 )
-                df_intraday = df_intraday.drop("DaysToExp", strict=False)
-
-                return df_cached
-            if df_cached.is_empty():
-                return df_intraday
-            return pl.concat([df_cached, df_intraday], how="diagonal")
         except Exception as e:
-            logger.error(f"Falha ao buscar dados intraday para {today}: {e}")
-
-    # 3. Se a lógica intraday não for acionada ou falhar, retorna apenas dados do cache.
-    return df_cached
+            logger.error(f"Falha ao buscar dados para {ref_date}: {e}")
+
+    # 4. Retorna concatenação de todos os DataFrames disponíveis
+    if len(dfs_to_concat) == 0:
+        return pl.DataFrame()  # Retorna DataFrame vazio se nada foi encontrado
+    elif len(dfs_to_concat) == 1:
+        return dfs_to_concat[0]
+    else:
+        return pl.concat(dfs_to_concat, how="diagonal")
 
 
 def _get_data(dates: DateScalar | DateArray) -> pl.DataFrame:

{pyield-0.40.3 → pyield-0.40.4}/pyield/tn/ntnb.py

@@ -1,4 +1,5 @@
 import datetime as dt
+import logging
 
 import pandas as pd
 import polars as pl
@@ -20,6 +21,8 @@ COUPON_MONTHS = {2, 5, 8, 11}
 COUPON_PMT = 2.956301
 FINAL_PMT = 102.956301
 
+logger = logging.getLogger(__name__)
+
 
 def data(date: DateScalar) -> pl.DataFrame:
     """
@@ -152,7 +155,8 @@ def payment_dates(
         maturity (DateScalar): The maturity date.
 
     Returns:
-        pl.Series: Series of coupon dates within the specified range.
+        pl.Series: Series of coupon dates within the specified range. Returns an empty
+            Series if the maturity date is before or equal to the settlement date.
 
     Examples:
         >>> from pyield import ntnb
@@ -171,7 +175,7 @@ def payment_dates(
     maturity = cv.convert_dates(maturity)
 
     if maturity <= settlement:
-        raise ValueError("Maturity date must be after the settlement date.")
+        return pl.Series(dtype=pl.Date)
 
     coupon_date = maturity
     coupon_dates = []
@@ -198,6 +202,7 @@ def cash_flows(
 
     Returns:
         pl.DataFrame: DataFrame with columns "PaymentDate" and "CashFlow".
+            Returns empty DataFrame if settlement >= maturity.
 
     Returned columns:
         - PaymentDate: The payment date of the cash flow
@@ -226,6 +231,10 @@ def cash_flows(
     # Get the coupon dates between the settlement and maturity dates
     p_dates = payment_dates(settlement, maturity)
 
+    # Return empty DataFrame if no payment dates (settlement >= maturity)
+    if p_dates.is_empty():
+        return pl.DataFrame(schema={"PaymentDate": pl.Date, "CashFlow": pl.Float64})
+
     df = pl.DataFrame({"PaymentDate": p_dates}).with_columns(
         pl.when(pl.col("PaymentDate") == maturity)
         .then(FINAL_PMT)
@@ -251,7 +260,8 @@ def quotation(
             the cash flows, which is the yield to maturity (YTM) of the NTN-B.
 
     Returns:
-        float: The NTN-B quotation truncated to 4 decimal places.
+        float: The NTN-B quotation truncated to 4 decimal places. Returns float('nan')
+            if the calculation cannot be performed due to invalid inputs.
 
     References:
         - https://www.anbima.com.br/data/files/A0/02/CC/70/8FEFC8104606BDC8B82BA2A8/Metodologias%20ANBIMA%20de%20Precificacao%20Titulos%20Publicos.pdf
@@ -275,6 +285,9 @@ def quotation(
     maturity = cv.convert_dates(maturity)
 
     cf_df = cash_flows(settlement, maturity)
+    if cf_df.is_empty():
+        return float("nan")
+
     cf_dates = cf_df["PaymentDate"]
     cf_values = cf_df["CashFlow"]
 
@@ -322,6 +335,98 @@ def price(
     return tl.truncate(vna * quotation / 100, 6)
 
 
+def _validate_spot_rate_inputs(
+    settlement: DateScalar,
+    maturities: DateArray,
+    rates: FloatArray,
+) -> tuple[dt.date, pl.Series, pl.Series]:
+    # Process and validate the input data
+    settlement = cv.convert_dates(settlement)
+    maturities = cv.convert_dates(maturities)
+
+    # Structural validation: ensure maturities and rates have the same length
+    if len(maturities) != len(rates):
+        raise ValueError(
+            f"Maturities and rates must have the same length. "
+            f"Got {len(maturities)} maturities and {len(rates)} rates."
+        )
+
+    # Create base dataframe and filter out invalid data
+    df_clean = pl.DataFrame(
+        data={"maturities": maturities, "rates": rates},
+        schema={"maturities": pl.Date, "rates": pl.Float64},
+    ).filter(pl.col("maturities") > settlement)
+
+    # Warn about filtered maturities
+    filtered_count = len(maturities) - df_clean.height
+    if filtered_count > 0:
+        logger.warning(
+            "Maturities on or before settlement were ignored: "
+            f"{filtered_count} entries removed."
+        )
+
+    return settlement, df_clean["maturities"], df_clean["rates"]
+
+
+def _create_bootstrap_dataframe(
+    settlement: dt.date,
+    rates: pl.Series,
+    maturities: pl.Series,
+) -> pl.DataFrame:
+    """Cria o DataFrame base para o bootstrap."""
+    # Create the interpolator to calculate the YTM rates for intermediate dates
+    flat_fwd = ip.Interpolator(
+        method="flat_forward",
+        known_bdays=bday.count(settlement, maturities),
+        known_rates=rates,
+    )
+
+    # Generate coupon dates up to the longest maturity date
+    all_coupon_dates = _generate_all_coupon_dates(settlement, maturities.max())
+    bdays_to_mat = bday.count(settlement, all_coupon_dates)
+
+    df = (
+        pl.DataFrame({"MaturityDate": all_coupon_dates, "BDToMat": bdays_to_mat})
+        .with_columns(
+            BYears=pl.col("BDToMat") / 252,
+            YTM=pl.col("BDToMat").map_elements(flat_fwd, return_dtype=pl.Float64),
+            Coupon=COUPON_PMT,
+            SpotRate=pl.lit(None, dtype=pl.Float64),
+        )
+        .sort("MaturityDate")
+    )
+
+    return df
+
+
+def _update_spot_rate(
+    df: pl.DataFrame, maturity: dt.date, spot_rate: float
+) -> pl.DataFrame:
+    """Helper function to update the spot rate inside the bootstrap loop."""
+    return df.with_columns(
+        pl.when(pl.col("MaturityDate") == maturity)
+        .then(spot_rate)
+        .otherwise(pl.col("SpotRate"))
+        .alias("SpotRate")
+    )
+
+
+def _calculate_coupons_present_value(
+    df: pl.DataFrame,
+    settlement: dt.date,
+    maturity: dt.date,
+) -> float:
+    """Calcula o valor presente dos cupons anteriores à maturidade."""
+    prev_cf_dates = payment_dates(settlement, maturity).to_list()[:-1]
+    df_temp = df.filter(pl.col("MaturityDate").is_in(prev_cf_dates))
+
+    return tl.calculate_present_value(
+        df_temp["Coupon"],
+        df_temp["SpotRate"],
+        df_temp["BYears"],
+    )
+
+
 def spot_rates(
     settlement: DateScalar,
     maturities: DateArray,
@@ -389,42 +494,12 @@ def spot_rates(
     """
     if has_null_args(settlement, maturities, rates):
         return pl.DataFrame()
-    # Process and validate the input data
-    settlement = cv.convert_dates(settlement)
-    maturities = cv.convert_dates(maturities)
 
-    # Create the interpolator to calculate the YTM rates for intermediate dates
-    flat_fwd = ip.Interpolator(
-        method="flat_forward",
-        known_bdays=bday.count(settlement, maturities),
-        known_rates=rates,
+    settlement, maturities, rates = _validate_spot_rate_inputs(
+        settlement, maturities, rates
     )
 
-    # Generate coupon dates up to the longest maturity date
-    all_coupon_dates = _generate_all_coupon_dates(settlement, maturities.max())
-    bdays_to_mat = bday.count(settlement, all_coupon_dates)
-
-    df = (
-        pl.DataFrame({"MaturityDate": all_coupon_dates, "BDToMat": bdays_to_mat})
-        .with_columns(
-            BYears=pl.col("BDToMat") / 252,
-            YTM=pl.col("BDToMat").map_elements(flat_fwd, return_dtype=pl.Float64),
-            Coupon=COUPON_PMT,
-            SpotRate=pl.lit(None, dtype=pl.Float64),
-        )
-        .sort("MaturityDate")
-    )
-
-    def _update_spot_rate(
-        df: pl.DataFrame, maturity: dt.date, spot_rate: float
-    ) -> pl.DataFrame:
-        """Helper function to update the spot rate inside the bootstrap loop."""
-        return df.with_columns(
-            pl.when(pl.col("MaturityDate") == maturity)
-            .then(spot_rate)
-            .otherwise(pl.col("SpotRate"))
-            .alias("SpotRate")
-        )
+    df = _create_bootstrap_dataframe(settlement, rates, maturities)
 
     # Bootstrap method to calculate spot rates iteratively
     df_dicts = df.to_dicts()
@@ -438,18 +513,10 @@ def spot_rates(
             df = _update_spot_rate(df, maturity, spot_rate)
             continue
 
-        # Get results for all previous cash flows already calculated
-        prev_cf_dates = payment_dates(settlement, maturity).to_list()[:-1]
-        df_temp = df.filter(pl.col("MaturityDate").is_in(prev_cf_dates))
-
         # Calculate the spot rate for the current maturity
-        present_value = tl.calculate_present_value(
-            df_temp["Coupon"],
-            df_temp["SpotRate"],
-            df_temp["BYears"],
-        )
+        coupons_pv = _calculate_coupons_present_value(df, settlement, maturity)
         bond_price = quotation(settlement, maturity, row["YTM"])
-        price_factor = FINAL_PMT / (bond_price - present_value)
+        price_factor = FINAL_PMT / (bond_price - coupons_pv)
         spot_rate = price_factor ** (1 / row["BYears"]) - 1
 
         df = _update_spot_rate(df, maturity, spot_rate)

{pyield-0.40.3 → pyield-0.40.4}/pyield/tn/ntnc.py

@@ -81,7 +81,8 @@ def payment_dates(
         maturity (DateScalar): The maturity date.
 
     Returns:
-        pl.Series: Series of coupon dates within the specified range.
+        pl.Series: Series of coupon dates within the specified range. Returns an
+            empty Series if the maturity date is before the settlement date.
 
     Examples:
         >>> from pyield import ntnc
@@ -110,7 +111,7 @@ def payment_dates(
 
     # Check if maturity date is after the start date
     if maturity < settlement:
-        raise ValueError("Maturity date must be after the start date.")
+        return pl.Series(dtype=pl.Date)
 
     # Initialize loop variables
     coupon_date = maturity
@@ -176,6 +177,10 @@ def cash_flows(
     # Get the coupon dates between the settlement and maturity dates
     pay_dates = payment_dates(settlement, maturity)
 
+    # Return empty DataFrame if no payment dates (settlement >= maturity)
+    if pay_dates.is_empty():
+        return pl.DataFrame(schema={"PaymentDate": pl.Date, "CashFlow": pl.Float64})
+
     # Get the right coupon payment and final payment values
     coupon_pmt = _get_coupon_pmt(maturity)
     final_pmt = _get_final_pmt(maturity)

{pyield-0.40.3 → pyield-0.40.4}/pyield/tn/ntnf.py

@@ -100,7 +100,8 @@ def payment_dates(
 
     Returns:
         pl.Series: A Series containing the coupon dates between the settlement
-            (exclusive) and maturity (inclusive) dates.
+            (exclusive) and maturity (inclusive) dates. Returns an empty Series if
+            the maturity date is before or equal to the settlement date.
 
     Examples:
         >>> from pyield import ntnf
@@ -124,7 +125,7 @@ def payment_dates(
 
     # Check if maturity date is after the start date
     if maturity <= settlement:
-        raise ValueError("Maturity date must be after the settlement date.")
+        return pl.Series(dtype=pl.Date)
 
     # Initialize loop variables
     coupon_date = maturity
@@ -185,6 +186,10 @@ def cash_flows(
     # Get the payment dates between the settlement and maturity dates
     pay_dates = payment_dates(settlement, maturity)
 
+    # Return empty DataFrame if no payment dates (settlement >= maturity)
+    if pay_dates.is_empty():
+        return pl.DataFrame(schema={"PaymentDate": pl.Date, "CashFlow": pl.Float64})
+
     # Set the cash flow at maturity to FINAL_PMT and the others to COUPON_PMT
     df = pl.DataFrame(data={"PaymentDate": pay_dates}).with_columns(
         pl.when(pl.col("PaymentDate") == maturity)
@@ -230,7 +235,11 @@ def price(
     """
     if has_null_args(settlement, maturity, rate):
         return float("nan")
+
     cf_df = cash_flows(settlement, maturity)
+    if cf_df.is_empty():
+        return float("nan")
+
     cf_values = cf_df["CashFlow"]
     bdays = bday.count(settlement, cf_df["PaymentDate"])
     byears = tools.truncate(bdays / 252, 14)
@@ -553,7 +562,7 @@ def premium(  # noqa
 
     Returns:
         float: The premium of the NTN-F bond over the DI curve, expressed as a
-        factor.
+        factor. If calculation fails, returns NaN.
 
     Examples:
         >>> # Obs: only some of the DI rates will be used in the example.
@@ -584,6 +593,9 @@ def premium(  # noqa
         di_rates = pl.Series(di_rates)
 
     df_cf = cash_flows(settlement, ntnf_maturity, adj_payment_dates=True)
+    if df_cf.is_empty():
+        return float("nan")
+
     ff_interpolator = ip.Interpolator(
         "flat_forward",
         bday.count(settlement, di_expirations),
@@ -650,6 +662,7 @@ def di_net_spread(  # noqa
 
     Returns:
         float: The net DI spread in decimal format (e.g., 0.0012 for 12 bps).
+            If calculation fails, returns NaN.
 
     Examples:
         # Obs: only some of the DI rates will be used in the example.
@@ -678,7 +691,7 @@ def di_net_spread(  # noqa
 
     # 2. Validação dos inputs de DI
     if len(di_rates) != len(di_expirations):
-        raise ValueError("di_rates and di_expirations must have the same length.")
+        return float("nan")
 
     # 3. Criação do interpolador
     ff_interpolator = ip.Interpolator(
@@ -689,6 +702,8 @@ def di_net_spread(  # noqa
 
     # 4. Geração dos fluxos de caixa do NTN-F
     df = cash_flows(settlement, ntnf_maturity)
+    if df.is_empty():
+        return float("nan")
 
     bdays_to_payment = bday.count(settlement, df["PaymentDate"])
     byears_to_payment = bdays_to_payment / 252
@@ -730,7 +745,8 @@ def duration(
         rate (float): The yield to maturity (YTM) used to discount the cash flows.
 
     Returns:
-        float: The Macaulay duration in business business years.
+        float: The Macaulay duration in business business years. Returns NaN if
+            calculation is not possible due to invalid inputs.
 
     Examples:
         >>> from pyield import ntnf
@@ -744,6 +760,9 @@ def duration(
     maturity = cv.convert_dates(maturity)
 
     df = cash_flows(settlement, maturity)
+    if df.is_empty():
+        return float("nan")
+
     byears = bday.count(settlement, df["PaymentDate"]) / 252
     dcf = df["CashFlow"] / (1 + rate) ** byears
     duration = (dcf * byears).sum() / dcf.sum()

pyield-0.40.3/pyield/__about__.py

@@ -1 +0,0 @@
-__version__ = "0.40.3"