PYield 0.22.2__tar.gz → 0.23.1__tar.gz

{pyield-0.22.2 → pyield-0.23.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: PYield
-Version: 0.22.2
+Version: 0.23.1
 Summary: A Python library for analysis of fixed income instruments in Brazil
 Keywords: fixed-income, brazil, finance, analysis, bonds
 Author-Email: Carlos Carvalho <cr.cj@outlook.com>

pyield-0.23.1/pyield/__about__.py

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

{pyield-0.22.2 → pyield-0.23.1}/pyield/bonds/bond_tools.py

@@ -79,7 +79,7 @@ def di_spreads(reference_date: str | pd.Timestamp) -> pd.DataFrame:
     # Fetch DI rates for the reference date
     reference_date = dc.convert_input_dates(reference_date)
     di = DIFutures(reference_date, adj_expirations=True)
-    df_di = di.data()
+    df_di = di.data
     if "SettlementRate" not in df_di.columns:
         raise ValueError("DI rates data is missing the 'SettlementRate' column.")
 

{pyield-0.22.2 → pyield-0.23.1}/pyield/bonds/ntnb.py

@@ -60,6 +60,29 @@ def rates(reference_date: str | pd.Timestamp) -> pd.DataFrame:
 
     Returns:
         pd.DataFrame: DataFrame with columns "MaturityDate" and "IndicativeRate".
+
+    Returned columns:
+        - MaturityDate: The maturity date of the bond.
+        - IndicativeRate: The indicative rate for the bond.
+
+    Examples:
+        >>> yd.ntnb.rates("16-08-2024")
+           MaturityDate  IndicativeRate
+        0    2025-05-15        0.063893
+        1    2026-08-15        0.066095
+        2    2027-05-15        0.064164
+        3    2028-08-15        0.063199
+        4    2029-05-15        0.061753
+        5    2030-08-15        0.059997
+        6    2032-08-15        0.060025
+        7    2033-05-15        0.059876
+        8    2035-05-15        0.059557
+        9    2040-08-15        0.058873
+        10   2045-05-15        0.060013
+        11   2050-08-15        0.060247
+        12   2055-05-15        0.059926
+        13   2060-08-15        0.060179
+
     """
     ntnb_rates = anbima.rates(reference_date, "NTN-B")
     if ntnb_rates.empty:
@@ -76,9 +99,31 @@ def maturities(reference_date: str | pd.Timestamp) -> pd.Series:
 
     Returns:
         pd.Series: Series containing the maturity dates for the NTN-B bonds.
+
+    Examples:
+
+        >>> yd.ntnb.maturities("16-08-2024")
+        0    2025-05-15
+        1    2026-08-15
+        2    2027-05-15
+        3    2028-08-15
+        4    2029-05-15
+        5    2030-08-15
+        6    2032-08-15
+        7    2033-05-15
+        8    2035-05-15
+        9    2040-08-15
+        10   2045-05-15
+        11   2050-08-15
+        12   2055-05-15
+        13   2060-08-15
+        dtype: datetime64[ns]
+
     """
     df_rates = rates(reference_date)
-    return df_rates["MaturityDate"]
+    s_maturities = df_rates["MaturityDate"]
+    s_maturities.name = None
+    return s_maturities
 
 
 def _generate_coupon_dates_map(
@@ -236,6 +281,8 @@ def quotation(
         99.3651
         >>> yd.ntnb.quotation("31-05-2024", "15-08-2060", 0.061878)
         99.5341
+        >>> yd.ntnb.quotation("15-08-2024", "15-08-2032", 0.05929)
+        100.6409
     """
     # Validate and normalize dates
     settlement = dc.convert_input_dates(settlement)
@@ -281,6 +328,8 @@ def price(
     Examples:
         >>> yd.ntnb.price(4299.160173, 99.3651)
         4271.864805
+        >>> yd.ntnb.price(4315.498383, 100.6409)
+        4343.156412
     """
     return bt.truncate(vna * quotation / 100, 6)
 
@@ -298,7 +347,6 @@ def spot_rates(
     the spot rates that discount each bond's cash flows to its current
     price.
 
-
     Args:
         settlement (str | pd.Timestamp): The reference date for settlement.
         maturities (pd.Series): Series of maturity dates for the bonds.
@@ -307,6 +355,32 @@ def spot_rates(
     Returns:
         pd.DataFrame: DataFrame with columns "MaturityDate", "SpotRate".
 
+    Examples:
+        # Get the NTN-B rates for a specific reference date
+        >>> df_rates = yd.ntnb.rates("16-08-2024")
+
+        # Calculate the spot rates considering the settlement at the reference date
+        >>> yd.ntnb.spot_rates(
+        ...     settlement="16-08-2024",
+        ...     maturities=df_rates["MaturityDate"],
+        ...     rates=df_rates["IndicativeRate"],
+        ... )
+           MaturityDate  SpotRate
+        0    2025-05-15  0.063894
+        1    2026-08-15  0.066141
+        2    2027-05-15  0.064087
+        3    2028-08-15  0.063057
+        4    2029-05-15  0.061458
+        5    2030-08-15  0.059491
+        6    2032-08-15  0.059652
+        7    2033-05-15  0.059497
+        8    2035-05-15  0.059151
+        9    2040-08-15  0.058326
+        10   2045-05-15  0.060371
+        11   2050-08-15  0.060772
+        12   2055-05-15  0.059909
+        13   2060-08-15  0.060652
+
     Notes:
         The calculation of the spot rates for NTN-B bonds considers the following steps:
             - Map all all possible payment dates up to the longest maturity date.
@@ -315,7 +389,6 @@ def spot_rates(
             - Calculate the real spot rates for each maturity date.
             - Columns in the returned DataFrame:
                 - MaturityDate: The maturity date of the bond.
-                - YTM: The yield to maturity rate for the bond.
                 - SpotRate: The real spot rate for the bond.
     """
     # Process and validate the input data

{pyield-0.22.2 → pyield-0.23.1}/pyield/di.py

@@ -30,19 +30,19 @@ class DIFutures:
         Initialize the DIFutures instance with a specific trade date.
 
         Args:
-            trade_date (str | pd.Timestamp): The trade date for which DI data is
-                required.
-            adj_expirations (bool): If True, adjusts the expiration dates to
-                the start of the month.
-            prefixed_filter (bool): If True, filters the DI
-                contracts to match LTN and NTN-F bond maturities.
+            trade_date (str | pd.Timestamp): The date to retrieve the contract data.
+            adj_expirations (bool): If True, adjusts the expiration dates to the start
+                of the month.
+            prefixed_filter (bool): If True, filters the DI contracts to match LTN and
+                NTN-F bond maturities.
         """
         self._trade_date = dc.convert_input_dates(trade_date)
-        self.adj_expirations = adj_expirations
-        self.prefixed_filter = prefixed_filter
+        self._adj_expirations = adj_expirations
+        self._prefixed_filter = prefixed_filter
 
+    @property
     def data(self) -> pd.DataFrame:
-        """Retrieve DI contract data for the initialized trade date."""
+        """Retrieve DI contract DataFrame for the initialized trade date."""
         df = (
             get_di_dataset()
             .query("TradeDate == @self.trade_date")
@@ -51,6 +51,7 @@ class DIFutures:
 
         if df.empty:
             df = futures(contract_code="DI1", trade_date=self._trade_date)
+
         if df.empty:
             return pd.DataFrame()
 
@@ -58,10 +59,18 @@ class DIFutures:
         if "DaysToExpiration" in df.columns:
             df.drop(columns=["DaysToExpiration"], inplace=True)
 
-        if self.prefixed_filter:
+        if self._prefixed_filter:
+            df_anbima = get_anbima_dataset()
+
+            # Find the closest Anbima reference date to the trade date
+            anbima_dates = (
+                df_anbima["ReferenceDate"].drop_duplicates().reset_index(drop=True)
+            )
+            dates_diff = (anbima_dates - self._trade_date).abs()
+            closest_date = anbima_dates[dates_diff.idxmin()]  # noqa
+
             df_pre = (
-                get_anbima_dataset()
-                .query("ReferenceDate == @self.trade_date")
+                df_anbima.query("ReferenceDate == @closest_date")
                 .query("BondType in ['LTN', 'NTN-F']")
                 .drop_duplicates(ignore_index=True)
             )
@@ -69,7 +78,7 @@ class DIFutures:
             adj_pre_maturities = bday.offset(pre_maturities, 0)  # noqa
             df.query("ExpirationDate in @adj_pre_maturities", inplace=True)
 
-        if self.adj_expirations:
+        if self._adj_expirations:
             df["ExpirationDate"] = (
                 df["ExpirationDate"].dt.to_period("M").dt.to_timestamp()
             )
@@ -87,7 +96,7 @@ class DIFutures:
         Returns:
             pd.Series: A Series of unique expiration dates for DI contracts.
         """
-        df = self.data().drop_duplicates(subset=["ExpirationDate"])
+        df = self.data.drop_duplicates(subset=["ExpirationDate"])
         return df["ExpirationDate"].sort_values(ignore_index=True)
 
     @property
@@ -107,7 +116,7 @@ class DIFutures:
                 - ForwardRate: The forward rate calculated between successive expiration
                   dates.
         """
-        df = self.data()
+        df = self.data
         if df.empty:
             return pd.DataFrame()
 
@@ -125,21 +134,30 @@ class DIFutures:
         extrapolate: bool = False,
     ) -> float:
         """Retrieve the DI rate for a specified expiration date."""
-        expiration = bday.offset(expiration, 0)
+        expiration = dc.convert_input_dates(expiration)
+
+        if self._adj_expirations:
+            # Force the expiration date to be the start of the month
+            expiration = expiration.to_period("M").to_timestamp()
+        else:
+            # Force the expiration date to be a business day
+            expiration = bday.offset(expiration, 0)
 
         if not interpolate and extrapolate:
             raise ValueError("Extrapolation is not allowed without interpolation.")
 
-        df = self.data()
+        df = self.data
+
         if df.empty:
             return float("NaN")
 
         df_exp = df.query("ExpirationDate == @expiration")
+
         if df_exp.empty and not interpolate:
             return float("NaN")
 
         if expiration in df_exp["ExpirationDate"].values:
-            return float(df_exp["SettlementRate"].iloc[0])
+            return float(df_exp["SettlementRate"].iat[0])
 
         if not interpolate:
             return float("NaN")
@@ -166,7 +184,6 @@ class DIFutures:
     @trade_date.setter
     def trade_date(self, value: str | pd.Timestamp):
         self._trade_date = dc.convert_input_dates(value)
-        return self._trade_date
 
     @property
     def adj_expirations(self) -> bool:

{pyield-0.22.2 → pyield-0.23.1}/pyield/indicators.py

@@ -1,13 +1,17 @@
+import logging
 import time
 from typing import Literal
 
 import pandas as pd
 import requests
+from requests.exceptions import RequestException
 
 from pyield import date_converter as dc
 
 type IndicatorCode = Literal["IPCA_MR", "SELIC_TARGET", "SELIC_OVER", "DI", "VNA_LFT"]
-TIMEOUT = 10
+
+TIMEOUT = (5, 20)
+MAX_ATTEMPTS = 5
 
 
 def indicator(
@@ -89,7 +93,7 @@ def ipca_monthly_rate(reference_date: pd.Timestamp) -> float:
     api_url = f"https://servicodados.ibge.gov.br/api/v3/agregados/6691/periodos/{ipca_date}/variaveis/63?localidades=N1[all]"
 
     # Send a GET request to the API
-    response = requests.get(api_url, timeout=10)
+    response = requests.get(api_url, timeout=TIMEOUT)
 
     # Raises HTTPError, if one occurred
     response.raise_for_status()
@@ -105,59 +109,89 @@ def ipca_monthly_rate(reference_date: pd.Timestamp) -> float:
 
 
 def _selic_target(reference_date: pd.Timestamp) -> float:
+    """
+    Fetches the SELIC Target rate for a specific reference date.
+
+    The SELIC Target rate is the official rate set by the Central Bank of Brazil.
+
+    Args:
+        reference_date (pd.Timestamp): The date for which to fetch the SELIC Target.
+
+    Returns:
+        float: The SELIC Target rate as a float rounded to 4 decimal places or NaN if
+        the rate is not available.
+    """
     # https://api.bcb.gov.br/dados/serie/bcdata.sgs.432/dados?formato=json&dataInicial=12/04/2024&dataFinal=12/04/2024
     selic_date = reference_date.strftime("%d/%m/%Y")
     api_url = f"https://api.bcb.gov.br/dados/serie/bcdata.sgs.432/dados?formato=json&dataInicial={selic_date}&dataFinal={selic_date}"
-    response = requests.get(api_url, timeout=10)
-    response.raise_for_status()
 
-    if selic_date not in response.text:
-        return float("nan")
-    data = response.json()
-    return round(float(data[0]["valor"]) / 100, 4)
+    attempt = 0
+    while attempt < MAX_ATTEMPTS:
+        try:
+            response = requests.get(api_url, timeout=TIMEOUT)
+            response.raise_for_status()  # Raise an error for bad HTTP response
+
+            # Try parsing JSON, raises an error if response is not valid JSON
+            data = response.json()
+
+            # Access the value directly, any issue will raise an exception
+            value = data[0]["valor"]
+            return round(float(value) / 100, 4)
+
+        except (RequestException, KeyError, IndexError, ValueError) as e:
+            msg = f"Error fetching SELIC Target rate (attempt {attempt + 1}): {e}"
+            logging.error(msg)
+
+        # Increment attempt count and add backoff delay
+        attempt += 1
+        time.sleep(1.5**attempt)  # Exponential backoff: 1.5, 2.3, 3.9, 5.1, 7.6 seconds
+
+    # After all retries, return NaN
+    return float("nan")
 
 
 def _selic_over(reference_date: pd.Timestamp) -> float:
     """
-    The SELIC Over rate is the daily average interest rate effectively practiced between
-    banks in the interbank market, using public securities as collateral. This rate may
-    vary daily depending on the supply and demand for resources between financial
-    institutions.
+    Fetches the SELIC Over rate for a specific reference date.
+
+    The SELIC Over rate is the daily average interest rate effectively practiced
+    between banks in the interbank market, using public securities as collateral.
+
+    Args:
+        reference_date (pd.Timestamp): The date for which to fetch the SELIC Over rate.
+
+    Returns:
+        float: The SELIC Over rate as a float rounded to 4 decimal places or NaN if
+        the rate is not available.
     """
+
     formatted_date = reference_date.strftime("%d/%m/%Y")
     # https://api.bcb.gov.br/dados/serie/bcdata.sgs.1178/dados?formato=json&dataInicial=12/04/2024&dataFinal=12/04/2024
     api_url = f"https://api.bcb.gov.br/dados/serie/bcdata.sgs.1178/dados?formato=json&dataInicial={formatted_date}&dataFinal={formatted_date}"
 
-    # Implementação interna de retries e timeout
-    retries = 3
-    timeout = 10
-    backoff_factor = 2
+    attempt = 0
 
-    for attempt in range(retries):
+    while attempt < MAX_ATTEMPTS:
         try:
-            response = requests.get(api_url, timeout=timeout)
-            response.raise_for_status()  # Check for HTTP errors
-
-            if formatted_date not in response.text:
-                return float("nan")
+            response = requests.get(api_url, timeout=TIMEOUT)
+            response.raise_for_status()  # Handle 4xx/5xx HTTP errors
 
+            # Try parsing JSON, raises an error if response is not valid JSON
             data = response.json()
 
-            if not data or "valor" not in data[0]:
-                return float("nan")
+            # Access the value directly, any issue will raise an exception
             value = data[0]["valor"]
             return round(float(value) / 100, 4)
 
-        except requests.exceptions.Timeout:
-            print(f"Timeout on attempt {attempt + 1}. Retrying...")
-        except requests.exceptions.ConnectionError as e:
-            print(f"Connection error on attempt {attempt + 1}: {e}. Retrying...")
-        except requests.exceptions.RequestException as e:
-            print(f"An error occurred: {e}")
-            return float("nan")
+        except (RequestException, KeyError, IndexError, ValueError) as e:
+            msg = f"Error fetching SELIC Over rate (attempt {attempt + 1}): {e}"
+            logging.error(msg)
 
-        time.sleep(backoff_factor**attempt)
+        # Increment attempt count and add backoff delay
+        attempt += 1
+        time.sleep(1.5**attempt)  # Exponential backoff: 1.5, 2.3, 3.9, 5.1, 7.6 seconds
 
+    # After all retries, return NaN
     return float("nan")
 
 
@@ -165,7 +199,7 @@ def _di(reference_date: pd.Timestamp) -> float:
     # https://api.bcb.gov.br/dados/serie/bcdata.sgs.11/dados?formato=json&dataInicial=12/04/2024&dataFinal=12/04/2024
     di_date = reference_date.strftime("%d/%m/%Y")
     api_url = f"https://api.bcb.gov.br/dados/serie/bcdata.sgs.11/dados?formato=json&dataInicial={di_date}&dataFinal={di_date}"
-    response = requests.get(api_url, timeout=10)
+    response = requests.get(api_url, timeout=TIMEOUT)
     response.raise_for_status()
 
     if di_date not in response.text:
@@ -182,7 +216,7 @@ def _vna_lft(reference_date: pd.Timestamp) -> float:
     url_file = f"{reference_date.strftime('%Y%m%d')}APC238"
     url_vna = url_base + url_file
 
-    response = requests.get(url_vna, timeout=10)
+    response = requests.get(url_vna, timeout=TIMEOUT)
     response.raise_for_status()
     file_text = response.text
 

{pyield-0.22.2 → pyield-0.23.1}/pyproject.toml

@@ -32,7 +32,7 @@ dependencies = [
     "types-requests",
 ]
 dynamic = []
-version = "0.22.2"
+version = "0.23.1"
 
 [project.license]
 file = "LICENSE"

pyield-0.22.2/pyield/__about__.py

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