PYield 0.23.0__tar.gz → 0.23.2__tar.gz

{pyield-0.23.0 → pyield-0.23.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: PYield
-Version: 0.23.0
+Version: 0.23.2
 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.2/pyield/__about__.py

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

{pyield-0.23.0 → pyield-0.23.2}/pyield/bday.py

@@ -239,10 +239,6 @@ def count(
             for counting.
         end (ScalarDateTypes | ArrayDateTypes): The end date(s) for counting, which
             is excluded from the count themselves.
-        holiday_option (Literal["old", "new", "infer"], optional):
-            Specifies which set of holidays to consider in the count. 'old' or 'new'
-            refer to predefined holiday lists, while 'infer' automatically selects the
-            list based on the most recent date in the input. Defaults to "infer".
 
     Returns:
         int | pd.Series: Returns an integer if `start` and `end` are single dates,

{pyield-0.23.0 → pyield-0.23.2}/pyield/bonds/ltn.py

@@ -1,9 +1,8 @@
 import pandas as pd
 
-from pyield import anbima, bday
+from pyield import anbima, bday, di
 from pyield import date_converter as dc
 from pyield.bonds import bond_tools as bt
-from pyield.di import DIFutures
 
 FACE_VALUE = 1000
 
@@ -219,8 +218,8 @@ def historical_premium(
     ltn_rate = float(ltn_rates.iloc[0])
 
     # Retrieve DI rate for the reference date and maturity
-    di = DIFutures(trade_date=reference_date)
-    di_rate = di.rate(expiration=maturity)
+    dif = di.DIFutures(trade_date=reference_date)
+    di_rate = dif.rate(expiration=maturity)
     if pd.isnull(di_rate):  # Check if the DI rate is NaN
         return float("NaN")
 

{pyield-0.23.0 → pyield-0.23.2}/pyield/bonds/ntnb.py

@@ -1,10 +1,10 @@
 import numpy as np
 import pandas as pd
 
+import pyield.bonds.bond_tools as bt
+import pyield.date_converter as dc
+import pyield.interpolator as ip
 from pyield import anbima, bday
-from pyield import date_converter as dc
-from pyield.bonds import bond_tools as bt
-from pyield.interpolator import Interpolator
 
 """
 Constants calculated as per Anbima Rules and in base 100
@@ -397,7 +397,7 @@ def spot_rates(
     _check_maturities(maturities)
 
     # Create the interpolator object
-    ff_interpolator = Interpolator(
+    ff_interpolator = ip.Interpolator(
         method="flat_forward",
         known_bdays=bday.count(settlement, maturities),
         known_rates=rates,
@@ -495,7 +495,7 @@ def bei_rates(
     df["BDays"] = bday.count(settlement, df["MaturityDate"])
     df = df.rename(columns={"SpotRate": "RIR"})
 
-    nir_interplator = Interpolator(
+    nir_interplator = ip.Interpolator(
         method="flat_forward",
         known_bdays=bday.count(settlement, nominal_maturities),
         known_rates=nominal_rates,

{pyield-0.23.0 → pyield-0.23.2}/pyield/bonds/ntnf.py

@@ -3,11 +3,10 @@ from collections.abc import Callable
 import numpy as np
 import pandas as pd
 
-from pyield import anbima, bday
+from pyield import anbima, bday, di
 from pyield import date_converter as dc
+from pyield import interpolator as ip
 from pyield.bonds import bond_tools as bt
-from pyield.di import DIFutures
-from pyield.interpolator import Interpolator
 
 """
 Constants calculated as per Anbima Rules
@@ -260,12 +259,12 @@ def spot_rates(  # noqa
     settlement = dc.convert_input_dates(settlement)
 
     # Create flat forward interpolators for LTN and NTN-F rates
-    ltn_rate_interpolator = Interpolator(
+    ltn_rate_interpolator = ip.Interpolator(
         method="flat_forward",
         known_bdays=bday.count(settlement, ltn_maturities),
         known_rates=ltn_rates,
     )
-    ntnf_rate_interpolator = Interpolator(
+    ntnf_rate_interpolator = ip.Interpolator(
         method="flat_forward",
         known_bdays=bday.count(settlement, ntnf_maturities),
         known_rates=ntnf_rates,
@@ -445,7 +444,7 @@ def di_net_spread(  # noqa
     settlement = dc.convert_input_dates(settlement)
     ntnf_maturity = dc.convert_input_dates(ntnf_maturity)
 
-    ff_interpolator = Interpolator(
+    ff_interpolator = ip.Interpolator(
         "flat_forward",
         bday.count(settlement, di_expirations),
         di_rates,
@@ -497,10 +496,9 @@ def premium(
         ntnf_maturity (str | pd.Timestamp): The maturity date of the NTN-F bond in
             'DD-MM-YYYY' format or a pandas Timestamp.
         ntnf_rate (float): The yield to maturity (YTM) of the NTN-F bond.
-        di_expirations (pd.Series): Series containing the expiration dates for DI
-        rates. di_rates (pd.Series): Series containing the DI rates corresponding to
-        the
-            expiration dates.
+        di_expirations (pd.Series): Series containing the expiration dates for DI rates.
+        di_rates (pd.Series): Series containing the DI rates corresponding to
+            the expiration dates.
 
     Returns:
         float: The premium of the NTN-F bond over the DI curve, expressed as a
@@ -531,7 +529,7 @@ def premium(
     df["BDays"] = bday.count(settlement, df["PaymentDate"])
     df["BYears"] = df["BDays"] / 252
 
-    ff_interpolator = Interpolator(
+    ff_interpolator = ip.Interpolator(
         "flat_forward",
         bday.count(settlement, di_expirations),
         di_rates,
@@ -579,8 +577,8 @@ def historical_premium(
     df = cash_flows(reference_date, maturity, adj_payment_dates=True)
     df["BDays"] = bday.count(reference_date, df["PaymentDate"])
     df["BYears"] = df["BDays"] / 252
-    di = DIFutures(reference_date)
-    df["DIRate"] = df["PaymentDate"].apply(di.rate)
+    dif = di.DIFutures(reference_date)
+    df["DIRate"] = df["PaymentDate"].apply(dif.rate)
 
     # Calculate the present value of the cash flows using the DI rate
     bond_price = bt.calculate_present_value(

{pyield-0.23.0 → pyield-0.23.2}/pyield/di.py

@@ -1,13 +1,44 @@
 import pandas as pd
 
+import pyield.b3_futures as b3
+import pyield.date_converter as dc
+import pyield.tools as tl
 from pyield import bday, interpolator
-from pyield import date_converter as dc
-from pyield.b3_futures import futures
 from pyield.data_cache import get_anbima_dataset, get_di_dataset
-from pyield.tools import forward_rates
 
 
 class DIFutures:
+    """
+    Class to retrieve and manipulate DI futures contract data.
+
+    This class provides access to DI futures data for a specified trade date, and
+    includes options to adjust expiration dates and apply filters based on LTN and
+    NTN-F bond maturities.
+
+    Examples:
+        To create a `DIFutures` instance and retrieve data:
+
+        >>> di = yd.DIFutures(trade_date="16-10-2024", adj_expirations=True)
+        >>> df = di.data  # Retrieve DI contract dataframe for the specified date
+        >>> df.iloc[:5, :5]  # Show the first five rows and columns
+          TickerSymbol ExpirationDate  BDaysToExp  OpenContracts  TradeCount
+        0       DI1X24     2024-11-01          12        1744269         635
+        1       DI1Z24     2024-12-01          31        1429375        1012
+        2       DI1F25     2025-01-01          52        5423969        6812
+        3       DI1G25     2025-02-01          74         279491          97
+        4       DI1H25     2025-03-01          94         344056         221
+
+        You can also retrieve forward rates for the DI contracts:
+
+        >>> di.forwards.iloc[:5]  # Show the first five rows
+          ExpirationDate  SettlementRate  ForwardRate
+        0     2024-11-01         0.10653      0.10653
+        1     2024-12-01          0.1091     0.110726
+        2     2025-01-01         0.11164       0.1154
+        3     2025-02-01         0.11362     0.118314
+        4     2025-03-01          0.1157      0.12343
+    """
+
     trade_dates = (
         get_di_dataset()
         .drop_duplicates(subset=["TradeDate"])["TradeDate"]
@@ -50,7 +81,7 @@ class DIFutures:
         )
 
         if df.empty:
-            df = futures(contract_code="DI1", trade_date=self._trade_date)
+            df = b3.futures(contract_code="DI1", trade_date=self._trade_date)
 
         if df.empty:
             return pd.DataFrame()
@@ -120,7 +151,7 @@ class DIFutures:
         if df.empty:
             return pd.DataFrame()
 
-        df["ForwardRate"] = forward_rates(
+        df["ForwardRate"] = tl.forward_rates(
             business_days=bday.count(self._trade_date, df["ExpirationDate"]),
             zero_rates=df["SettlementRate"],
         )
@@ -174,11 +205,15 @@ class DIFutures:
     @property
     def trade_date(self) -> pd.Timestamp:
         """
-        Get or set the trade date for this DIFutures instance.
+        The trade date to retrieve the DI contract data.
+
+        This property can be both read and set. When setting a value, it automatically
+        converts the input date format to a `pd.Timestamp`.
 
         Returns:
             pd.Timestamp: The trade date set for this instance.
         """
+
         return self._trade_date
 
     @trade_date.setter
@@ -188,7 +223,11 @@ class DIFutures:
     @property
     def adj_expirations(self) -> bool:
         """
-        Get or set the adj_expirations flag for this DIFutures instance.
+        Adjusts the expiration dates to the start of the month.
+
+        This property can be both read and set. When set to `True`, all expiration dates
+        are adjusted to the first day of the month. For example, an expiration date of
+        02/01/2025 will be adjusted to 01/01/2025.
 
         Returns:
             bool: Whether expiration dates are adjusted to the start of the month.
@@ -202,7 +241,10 @@ class DIFutures:
     @property
     def prefixed_filter(self) -> bool:
         """
-        Get or set the prefixed_filter flag for this DIFutures instance.
+        Filters DI Futures to match prefixed TN bond maturities.
+
+        This property can be both read and set. When set to `True`, DI Futures will be
+        filtered to match the maturities of LTN and NTN-F bonds from the Anbima dataset.
 
         Returns:
             bool: Whether DI Futures are filtered to match prefixed Anbima bond

{pyield-0.23.0 → pyield-0.23.2}/pyield/indicators.py

@@ -1,15 +1,17 @@
 import logging
+import time
 from typing import Literal
 
 import pandas as pd
 import requests
-from requests.adapters import HTTPAdapter
-from urllib3.util import Retry
+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(
@@ -91,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()
@@ -123,31 +125,29 @@ def _selic_target(reference_date: pd.Timestamp) -> float:
     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}"
 
-    s = requests.Session()
-    retries = Retry(
-        total=5,  # Retry 5 times
-        backoff_factor=1,  # Exponential backoff: 1, 2, 4, 8, 16 seconds
-        status_forcelist=[500, 502, 503, 504],  # Retry on these HTTP status codes
-    )
-    s.mount("https://", HTTPAdapter(max_retries=retries))
+    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:
-        response = s.get(api_url, timeout=(5, 20))
-        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()
 
-        if selic_date not in response.text:
-            return float("nan")
+            # Access the value directly, any issue will raise an exception
+            value = data[0]["valor"]
+            return round(float(value) / 100, 4)
 
-        data = response.json()
-        if not data or "valor" not in data[0]:
-            return float("nan")
+        except (RequestException, KeyError, IndexError, ValueError) as e:
+            msg = f"Error fetching SELIC Target rate (attempt {attempt + 1}): {e}"
+            logging.error(msg)
 
-        value = data[0]["valor"]
-        return round(float(value) / 100, 4)
+        # 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
 
-    except requests.exceptions.RequestException as e:
-        logging.error(f"Error fetching SELIC Target rate: {e}")
-        return float("nan")
+    # After all retries, return NaN
+    return float("nan")
 
 
 def _selic_over(reference_date: pd.Timestamp) -> float:
@@ -169,37 +169,37 @@ def _selic_over(reference_date: pd.Timestamp) -> float:
     # 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}"
 
-    s = requests.Session()
-    retries = Retry(
-        total=5,
-        backoff_factor=1,
-        status_forcelist=[500, 502, 503, 504],
-    )
-    s.mount("https://", HTTPAdapter(max_retries=retries))
-    try:
-        response = s.get(api_url, timeout=(5, 20))
-        response.raise_for_status()  # Raise an error for bad HTTP response
-
-        if formatted_date not in response.text:
-            return float("nan")
-
-        data = response.json()
-        if not data or "valor" not in data[0]:
-            return float("nan")
-
-        value = data[0]["valor"]
-        return round(float(value) / 100, 4)
-
-    except requests.exceptions.RequestException as e:
-        logging.error(f"Error fetching SELIC Over rate: {e}")
-        return float("nan")
+    attempt = 0
+
+    while attempt < MAX_ATTEMPTS:
+        try:
+            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()
+
+            # 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 Over 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 _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:
@@ -216,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.23.0 → pyield-0.23.2}/pyield/interpolator.py

@@ -6,45 +6,46 @@ import pandas as pd
 
 
 class Interpolator:
-    def __init__(
-        self,
-        method: Literal["flat_forward", "linear"],
-        known_bdays: pd.Series | list,
-        known_rates: pd.Series | list,
-        extrapolate: bool = False,
-    ):
-        """
-        Initialize the Interpolator with given atributes.
+    """
+    Interpolator class for interest rate interpolation.
 
-        Args:
-            method (Literal["flat_forward", "linear"]): Interpolation method.
-            known_bdays (pd.Series | pd.Index | list): Series of known business days.
-            known_rates (pd.Series | pd.Index | list): Series of known interest rates.
-            extrapolate (bool, optional): Whether to extrapolate beyond the known data.
+    Args:
+        method (Literal["flat_forward", "linear"]): The interpolation method to use.
+        known_bdays (pd.Series | pd.Index | list): Series of known business days.
+        known_rates (pd.Series | pd.Index | list): Series of known interest rates.
+        extrapolate (bool, optional): Whether to extrapolate beyond known business days.
 
-        Raises:
-            ValueError: If known_bdays and known_rates do not have the same length.
-            ValueError: If the interpolation method is not recognized
+    Raises:
+        ValueError: If known_bdays and known_rates do not have the same length.
+        ValueError: If the interpolation method is not recognized
 
-        Returns:
-            Interpolator: An instance of the Interpolator
+    Returns:
+        Interpolator: An instance of the Interpolator
 
-        Note:
-            This class uses a 252 business days per year convention.
-        Examples:
-            >>> from pyield import Interpolator
-            >>> known_bdays = [30, 60, 90]
-            >>> known_rates = [0.045, 0.05, 0.055]
+    Note:
+        This class uses a 252 business days per year convention.
 
-            >>> lin_interp = Interpolator("linear", known_bdays, known_rates)
-            >>> lin_interp(45)
-            0.0475
+    Examples:
+        >>> from pyield import Interpolator
+        >>> known_bdays = [30, 60, 90]
+        >>> known_rates = [0.045, 0.05, 0.055]
 
-            >>> ffo_interp = Interpolator("flat_forward", known_bdays, known_rates)
-            >>> ffo_interp(45)
-            0.04833068080970859
+        >>> lin_interp = Interpolator("linear", known_bdays, known_rates)
+        >>> lin_interp(45)
+        0.0475
 
-        """
+        >>> ffo_interp = Interpolator("flat_forward", known_bdays, known_rates)
+        >>> ffo_interp(45)
+        0.04833068080970859
+    """
+
+    def __init__(
+        self,
+        method: Literal["flat_forward", "linear"],
+        known_bdays: pd.Series | list,
+        known_rates: pd.Series | list,
+        extrapolate: bool = False,
+    ):
         self.method = method
         self.known_bdays = known_bdays
         self.known_rates = known_rates

{pyield-0.23.0 → pyield-0.23.2}/pyproject.toml

@@ -32,7 +32,7 @@ dependencies = [
     "types-requests",
 ]
 dynamic = []
-version = "0.23.0"
+version = "0.23.2"
 
 [project.license]
 file = "LICENSE"
@@ -61,6 +61,7 @@ dev = [
     "mkdocs",
     "mkdocs-material",
     "mkdocstrings[python]",
+    "mkdocs-autorefs",
 ]
 
 [tool.ruff]

pyield-0.23.0/pyield/__about__.py

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