PYield 0.20.2__tar.gz → 0.22.0__tar.gz

{pyield-0.20.2 → pyield-0.22.0}/PKG-INFO

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

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

{pyield-0.20.2 → pyield-0.22.0}/pyield/__init__.py

@@ -2,6 +2,7 @@ from pyield import anbima, bday, di, tools
 from pyield.__about__ import __version__
 from pyield.b3_futures import futures
 from pyield.bonds import lft, ltn, ntnb, ntnf
+from pyield.di import DIFutures
 from pyield.indicators import indicator
 from pyield.interpolator import Interpolator
 from pyield.projections import projection
@@ -16,8 +17,10 @@ __all__ = [
     "ntnf",
     "ltn",
     "lft",
-    "di",
+    "DIFutures",
     "projection",
     "Interpolator",
     "tools",
+    "di",
+    "DIFutures",
 ]

{pyield-0.20.2 → pyield-0.22.0}/pyield/anbima.py

@@ -7,7 +7,7 @@ import requests
 
 from pyield import bday
 from pyield import date_converter as dc
-from pyield.data_cache import get_anbima_dataframe
+from pyield.data_cache import get_anbima_dataset
 
 # URL Constants
 ANBIMA_URL = "https://www.anbima.com.br/informacoes/merc-sec/arqs"
@@ -132,7 +132,7 @@ def rates(
     bond_type: str | None = None,
     adj_maturities: bool = False,
 ) -> pd.DataFrame:
-    df = get_anbima_dataframe()
+    df = get_anbima_dataset()
 
     reference_date = dc.convert_input_dates(reference_date)
     df.query("ReferenceDate == @reference_date", inplace=True)
@@ -158,7 +158,7 @@ def rates(
 def pre_maturities(
     reference_date: str | pd.Timestamp,
 ) -> pd.Series:
-    df = get_anbima_dataframe()
+    df = get_anbima_dataset()
     reference_date = dc.convert_input_dates(reference_date)
     df.query("ReferenceDate == @reference_date", inplace=True)
     df.query("BondType in ['LTN', 'NTN-F']", inplace=True)

{pyield-0.20.2 → pyield-0.22.0}/pyield/b3_futures/__init__.py

@@ -1,14 +1,15 @@
 import datetime as dt
+from zoneinfo import ZoneInfo
 
 import pandas as pd
-from pytz import timezone
 
 from .. import date_converter as dc
 from .historical import fetch_historical_df
 from .intraday import fetch_intraday_df
 
 SUPPORTED_FUTURES = ["DI1", "DDI", "FRC", "DAP", "DOL", "WDO", "IND", "WIN"]
-TIMEZONE_BZ = timezone("America/Sao_Paulo")
+
+TIMEZONE_BZ = ZoneInfo("America/Sao_Paulo")
 
 
 def futures(

{pyield-0.20.2 → pyield-0.22.0}/pyield/b3_futures/historical.py

@@ -73,7 +73,7 @@ def get_old_expiration_date(
         expiration_date = pd.Timestamp(year, month, 1)
         # Adjust to the next business day when the date is a weekend or a holiday.
         # Must use old holiday list, since this contract code was used until 2006.
-        return bday.offset(dates=expiration_date, offset=0, holiday_list="old")
+        return bday.offset(dates=expiration_date, offset=0)
 
     except (KeyError, ValueError):
         return pd.NaT  # type: ignore

{pyield-0.20.2 → pyield-0.22.0}/pyield/bday.py

@@ -10,8 +10,10 @@ from pyield.holidays import BrHolidays
 type ArrayIntTypes = np.ndarray | pd.Series | list | tuple
 type ScalarIntTypes = int | np.integer
 
-# Initialize the BrHolidays class
+# Initialize Brazilian holidays data
 br_holidays = BrHolidays()
+OLD_HOLIDAYS_ARRAY = br_holidays.get_holiday_array(holiday_option="old")
+NEW_HOLIDAYS_ARRAY = br_holidays.get_holiday_array(holiday_option="new")
 
 
 @overload
@@ -19,7 +21,6 @@ def offset(
     dates: ScalarDateTypes,
     offset: ScalarIntTypes,
     roll: Literal["forward", "backward"] = ...,
-    holiday_list: Literal["old", "new", "infer"] = ...,
 ) -> pd.Timestamp: ...
 
 
@@ -28,7 +29,6 @@ def offset(
     dates: ArrayDateTypes,
     offset: ArrayIntTypes,
     roll: Literal["forward", "backward"] = ...,
-    holiday_list: Literal["old", "new", "infer"] = ...,
 ) -> pd.Series: ...
 
 
@@ -37,7 +37,6 @@ def offset(
     dates: ScalarDateTypes,
     offset: ArrayIntTypes,
     roll: Literal["forward", "backward"] = ...,
-    holiday_list: Literal["old", "new", "infer"] = ...,
 ) -> pd.Series: ...
 
 
@@ -46,7 +45,6 @@ def offset(
     dates: ArrayDateTypes,
     offset: ScalarIntTypes,
     roll: Literal["forward", "backward"] = ...,
-    holiday_list: Literal["old", "new", "infer"] = ...,
 ) -> pd.Series: ...
 
 
@@ -54,14 +52,13 @@ def offset(
     dates: ScalarDateTypes | ArrayDateTypes,
     offset: ScalarIntTypes | ArrayIntTypes,
     roll: Literal["forward", "backward"] = "forward",
-    holiday_list: Literal["old", "new", "infer"] = "infer",
 ) -> pd.Timestamp | pd.Series:
     """
-    Offsets the dates to the next or previous business day, considering brazilian
-    holidays. This function supports both single dates and collections of dates,
-    handling them intelligently to return either a single offset date or a series of
-    offset dates. It is a wrapper for `numpy.busday_offset` adapted for Pandas data
-    types and holiday adjustments.
+    First adjusts the date to fall on a valid day according to the roll rule, then
+    applies offsets to the given dates to the next or previous business day, considering
+    brazilian holidays. This function supports both single dates and collections of
+    dates. It is a wrapper for `numpy.busday_offset` adapted for Pandas data types and
+    brazilian holidays.
 
     Args:
         dates (ScalarDateTypes | ArrayDateTypes):
@@ -69,16 +66,12 @@ def offset(
             `datetime`, `Timestamp`, etc.) or a collection of dates (list, tuple,
             `Series`, etc.).
         offset (int | Series | np.ndarray | list[int] | tuple[int], optional):
-            The number of business days to offset the dates. Positive for
-            future dates, negative for past dates. Zero will return the same date if
-            it's a business day, or the next business day otherwise.
+            The number of business days to offset the dates. Positive for future dates,
+            negative for past dates. Zero will return the same date if it's a business
+            day, or the next business day otherwise.
         roll (Literal["forward", "backward"], optional): Direction to roll the date if
             it falls on a holiday or weekend. 'forward' to the next business day,
             'backward' to the previous. Defaults to 'forward'.
-        holiday_list (Literal["old", "new", "infer"], optional):
-            The list of holidays to consider. 'old' or 'new' use predefined lists, while
-            'infer' determines the most appropriate list based on the input dates.
-            Defaults to "infer".
 
     Returns:
         pd.Timestamp | pd.Series: If a single date is provided, returns a single
@@ -86,7 +79,6 @@ def offset(
             `Series` of offset dates.
 
     Examples:
-        >>> from pandas import Timestamp
         >>> from pyield import bday
 
         Offset to the next business day if not a bday (offset=0 and roll="forward")
@@ -145,36 +137,68 @@ def offset(
         This function uses `numpy.busday_offset` under the hood, which means it follows
         the same conventions and limitations for business day calculations. For detailed
         information on error handling and behavior, refer to the `numpy.busday_offset`
-        documentation: https://numpy.org/doc/stable/reference/generated/numpy.busday_offset.html
+        documentation:
+        https://numpy.org/doc/stable/reference/generated/numpy.busday_offset.html
     """
-    converted_dates = dc.convert_input_dates(dates)
+    dates_pd = dc.convert_input_dates(dates)
+
+    if isinstance(dates_pd, pd.Series):
+        # Divide the input in order to apply the correct holiday list
+        dates1 = dates_pd[dates_pd < br_holidays.TRANSITION_DATE]
+        dates2 = dates_pd[dates_pd >= br_holidays.TRANSITION_DATE]
+        dates3 = dates_pd[dates_pd.isna()]
+
+        offsetted_dates1 = np.busday_offset(
+            dc.to_numpy_date_type(dates1),
+            offsets=offset,
+            roll=roll,
+            holidays=OLD_HOLIDAYS_ARRAY,
+        )
+
+        offsetted_dates2 = np.busday_offset(
+            dc.to_numpy_date_type(dates2),
+            offsets=offset,
+            roll=roll,
+            holidays=NEW_HOLIDAYS_ARRAY,
+        )
+
+        # Convert from numpy.datetime64 to pandas.Timestamp
+        offsetted_dates1 = pd.to_datetime(offsetted_dates1)
+        offsetted_dates2 = pd.to_datetime(offsetted_dates2)
+
+        # 'pd.to_datetime' does not necessarily return datetime64[ns] Series
+        offsetted_dates1 = pd.Series(offsetted_dates1).astype("datetime64[ns]")
+        offsetted_dates2 = pd.Series(offsetted_dates2).astype("datetime64[ns]")
+
+        # Use old index to rejoin the results
+        offsetted_dates1.index = dates1.index
+        offsetted_dates2.index = dates2.index
+
+        offsetted_dates = pd.concat([offsetted_dates1, offsetted_dates2, dates3])
+
+        # Reorder the result to match the original input order
+        return offsetted_dates.sort_index()
+
+    elif isinstance(dates_pd, pd.Timestamp):
+        offsetted_dates_np = np.busday_offset(
+            dc.to_numpy_date_type(dates_pd),
+            offsets=offset,
+            roll=roll,
+            holidays=br_holidays.get_holiday_array(dates_pd),
+        )
+        if isinstance(offsetted_dates_np, np.datetime64):
+            return pd.Timestamp(offsetted_dates_np).as_unit("ns")
+        else:
+            return pd.Series(offsetted_dates_np).astype("datetime64[ns]")
 
-    selected_holidays = br_holidays.get_applicable_holidays(
-        converted_dates, holiday_list
-    )
-    selected_holidays_np = dc.convert_to_numpy_date(selected_holidays)
-
-    dates_np = dc.convert_to_numpy_date(converted_dates)
-    offsetted_dates_np = np.busday_offset(
-        dates_np, offsets=offset, roll=roll, holidays=selected_holidays_np
-    )
-    if isinstance(offsetted_dates_np, np.datetime64):
-        result = pd.Timestamp(offsetted_dates_np)
-        # Force to datetime[ns] if the input was a single date
-        result = result.as_unit("ns")
     else:
-        result_dti = pd.to_datetime(offsetted_dates_np)
-        # Force the result to be a Series if the input was not a single date
-        result = pd.Series(result_dti).astype("datetime64[ns]")
-
-    return result
+        raise ValueError("Invalid input type for 'dates'.")
 
 
 @overload
 def count(
     start: ScalarDateTypes,
     end: ScalarDateTypes,
-    holiday_list: Literal["old", "new", "infer"] = "infer",
 ) -> int: ...
 
 
@@ -182,7 +206,6 @@ def count(
 def count(
     start: ArrayDateTypes,
     end: ScalarDateTypes,
-    holiday_list: Literal["old", "new", "infer"] = "infer",
 ) -> pd.Series: ...
 
 
@@ -190,7 +213,6 @@ def count(
 def count(
     start: ScalarDateTypes,
     end: ArrayDateTypes,
-    holiday_list: Literal["old", "new", "infer"] = "infer",
 ) -> pd.Series: ...
 
 
@@ -198,14 +220,12 @@ def count(
 def count(
     start: ArrayDateTypes,
     end: ArrayDateTypes,
-    holiday_list: Literal["old", "new", "infer"] = "infer",
 ) -> pd.Series: ...
 
 
 def count(
     start: ScalarDateTypes | ArrayDateTypes,
     end: ScalarDateTypes | ArrayDateTypes,
-    holiday_list: Literal["old", "new", "infer"] = "infer",
 ) -> int | pd.Series:
     """
     Counts the number of business days between a `start` date (inclusive) and an `end`
@@ -219,7 +239,7 @@ def count(
             for counting.
         end (ScalarDateTypes | ArrayDateTypes): The end date(s) for counting, which
             is excluded from the count themselves.
-        holiday_list (Literal["old", "new", "infer"], optional):
+        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".
@@ -263,31 +283,71 @@ def count(
         1    19
         dtype: Int64
     """
-    converted_start = dc.convert_input_dates(start)
-    converted_end = dc.convert_input_dates(end)
-
-    # Determine which list of holidays to use
-    selected_holidays = br_holidays.get_applicable_holidays(
-        converted_start, holiday_list
-    )
-    selected_holidays_np = dc.convert_to_numpy_date(selected_holidays)
-
-    # Convert inputs to numpy datetime64[D] before calling numpy.busday_count
-    start_np = dc.convert_to_numpy_date(converted_start)
-    end_np = dc.convert_to_numpy_date(converted_end)
-
-    result_np = np.busday_count(start_np, end_np, holidays=selected_holidays_np)
-    if isinstance(result_np, np.integer):
-        return int(result_np)
-    else:
-        return pd.Series(result_np, dtype="Int64")
+    start_pd = dc.convert_input_dates(start)
+    end_pd = dc.convert_input_dates(end)
+
+    # If inputs are Series, check if they have different lengths
+    if isinstance(start_pd, pd.Series) and isinstance(end_pd, pd.Series):
+        if start_pd.size != end_pd.size:
+            raise ValueError("Input Series must have the same length.")
+
+    # Only start is used to determine the holiday list
+    if isinstance(start_pd, pd.Series):
+        # Divide the input in order to apply the correct holiday list
+        start1 = start_pd[start_pd < br_holidays.TRANSITION_DATE]
+        start2 = start_pd[start_pd >= br_holidays.TRANSITION_DATE]
+        start3 = start_pd[start_pd.isna()]
+
+        # If end is a Series, it must be divided as well
+        if isinstance(end_pd, pd.Series):
+            end1 = end_pd[start1.index]
+            end2 = end_pd[start2.index]
+        else:
+            end1 = end_pd
+            end2 = end_pd
+
+        result1 = np.busday_count(
+            begindates=dc.to_numpy_date_type(start1),
+            enddates=dc.to_numpy_date_type(end1),
+            holidays=OLD_HOLIDAYS_ARRAY,
+        )
+        result2 = np.busday_count(
+            begindates=dc.to_numpy_date_type(start2),
+            enddates=dc.to_numpy_date_type(end2),
+            holidays=NEW_HOLIDAYS_ARRAY,
+        )
+
+        # Prepare results to be rejoined
+        result1 = pd.Series(result1, dtype="Int64")
+        result2 = pd.Series(result2, dtype="Int64")
+        # Convert the third result from NaT to NA
+        result3 = pd.Series(pd.NA, index=start3.index, dtype="Int64")
+
+        # Old index is used to rejoin the results
+        result1.index = start1.index
+        result2.index = start2.index
+
+        # Reorder the result to match the original input order
+        result = pd.concat([result1, result2, result3]).sort_index()
+
+    else:  # Start is a single date
+        result = np.busday_count(
+            begindates=dc.to_numpy_date_type(start_pd),
+            enddates=dc.to_numpy_date_type(end_pd),
+            holidays=br_holidays.get_holiday_array(start_pd),
+        )
+        result = pd.Series(result, dtype="Int64")
+
+    if result.size == 1:
+        return int(result[0])
+    return result
 
 
 def generate(
     start: ScalarDateTypes | None = None,
     end: ScalarDateTypes | None = None,
     inclusive: Literal["both", "neither", "left", "right"] = "both",
-    holiday_list: Literal["old", "new", "infer"] = "infer",
+    holiday_option: Literal["old", "new", "infer"] = "infer",
 ) -> pd.Series:
     """
     Generates a Series of business days between a `start` and `end` date, considering
@@ -304,7 +364,7 @@ def generate(
         inclusive (Literal["both", "neither", "left", "right"], optional):
             Determines which of the start and end dates are included in the result.
             Valid options are 'both', 'neither', 'left', 'right'. Defaults to 'both'.
-        holiday_list (Literal["old", "new", "infer"], optional):
+        holiday_option (Literal["old", "new", "infer"], optional):
             Specifies the list of holidays to consider. 'old' or 'new' refer to
             predefined lists, 'infer' selects the list based on the most recent date in
             the range. Defaults to "infer".
@@ -330,27 +390,24 @@ def generate(
         https://pandas.pydata.org/docs/reference/api/pandas.bdate_range.html.
     """
     if start:
-        converted_start = dc.convert_input_dates(start)
+        start_pd = dc.convert_input_dates(start)
     else:
-        converted_start = pd.Timestamp.today()
+        start_pd = pd.Timestamp.today()
 
     if end:
-        converted_end = dc.convert_input_dates(end)
+        end_pd = dc.convert_input_dates(end)
     else:
-        converted_end = pd.Timestamp.today()
+        end_pd = pd.Timestamp.today()
 
-    selected_holidays = br_holidays.get_applicable_holidays(
-        converted_start, holiday_list
-    )
-    selected_holidays_list = selected_holidays.to_list()
+    holidays_list = br_holidays.get_holiday_series(start_pd).to_list()
 
     # Get the result as a DatetimeIndex (dti)
     result_dti = pd.bdate_range(
-        start=converted_start,
-        end=converted_end,
+        start=start_pd,
+        end=end_pd,
         freq="C",
         inclusive=inclusive,
-        holidays=selected_holidays_list,
+        holidays=holidays_list,
     )
     return pd.Series(result_dti.values)
 
@@ -370,6 +427,6 @@ def is_business_day(date: ScalarDateTypes) -> bool:
         >>> bday.is_business_day("25-12-2023")  # Christmas
         False
     """
-    converted_date = dc.convert_input_dates(date)
-    shifted_date = offset(converted_date, 0)  # Shift the date if it is not a bus. day
-    return converted_date == shifted_date
+    date_pd = dc.convert_input_dates(date)
+    shifted_date = offset(date_pd, 0)  # Shift the date if it is not a bus. day
+    return date_pd == shifted_date

{pyield-0.20.2 → pyield-0.22.0}/pyield/data_cache.py

@@ -1,11 +1,12 @@
 from datetime import datetime as dt
+from zoneinfo import ZoneInfo
 
 import pandas as pd
-from pytz import timezone
 
 from pyield import bday
 
-TIMEZONE_BZ = timezone("America/Sao_Paulo")
+TIMEZONE_BZ = ZoneInfo("America/Sao_Paulo")
+
 UPDATE_HOUR = 21
 GIT_URL = "https://raw.githubusercontent.com/crdcj/pyield-data/main"
 
@@ -64,9 +65,9 @@ _data_cache = DataCache()
 
 
 # Funções de acesso para os módulos
-def get_di_dataframe():
+def get_di_dataset():
     return _data_cache.get_dataframe("di")
 
 
-def get_anbima_dataframe():
+def get_anbima_dataset():
     return _data_cache.get_dataframe("anbima")

{pyield-0.20.2 → pyield-0.22.0}/pyield/date_converter.py

@@ -60,7 +60,7 @@ def convert_input_dates(
             raise ValueError("Invalid input type for 'dates'.")
 
 
-def convert_to_numpy_date(
+def to_numpy_date_type(
     dates: pd.Timestamp | pd.Series,
 ) -> np.datetime64 | np.ndarray:
     """
@@ -74,5 +74,7 @@ def convert_to_numpy_date(
     """
     if isinstance(dates, pd.Timestamp):
         return np.datetime64(dates, "D")
-    else:
+    elif isinstance(dates, pd.Series):
         return dates.to_numpy().astype("datetime64[D]")
+    else:
+        raise ValueError("Invalid input type for 'dates'.")

pyield-0.22.0/pyield/di.py

@@ -0,0 +1,198 @@
+import pandas as pd
+
+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:
+    trade_dates = (
+        get_di_dataset()
+        .drop_duplicates(subset=["TradeDate"])["TradeDate"]
+        .sort_values(ascending=True)
+        .reset_index(drop=True)
+    )
+    """
+    pd.Series: Sorted series of unique trade dates available in the DI dataset.
+    It does not include the current date. It is updated when `reload_data`
+    is called and can be used to check for available historical data.
+    """
+
+    def __init__(
+        self,
+        trade_date: str | pd.Timestamp,
+        adj_expirations: bool = False,
+        prefixed_filter: bool = False,
+    ):
+        """
+        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.
+        """
+        self._trade_date = dc.convert_input_dates(trade_date)
+        self.adj_expirations = adj_expirations
+        self.prefixed_filter = prefixed_filter
+
+    def data(self) -> pd.DataFrame:
+        """Retrieve DI contract data for the initialized trade date."""
+        df = (
+            get_di_dataset()
+            .query("TradeDate == @self.trade_date")
+            .reset_index(drop=True)
+        )
+
+        if df.empty:
+            df = futures(contract_code="DI1", trade_date=self._trade_date)
+        if df.empty:
+            return pd.DataFrame()
+
+        df.drop(columns=["TradeDate"], inplace=True)
+        if "DaysToExpiration" in df.columns:
+            df.drop(columns=["DaysToExpiration"], inplace=True)
+
+        if self.prefixed_filter:
+            df_pre = (
+                get_anbima_dataset()
+                .query("ReferenceDate == @self.trade_date")
+                .query("BondType in ['LTN', 'NTN-F']")
+                .drop_duplicates(ignore_index=True)
+            )
+            pre_maturities = df_pre["MaturityDate"]
+            adj_pre_maturities = bday.offset(pre_maturities, 0)  # noqa
+            df.query("ExpirationDate in @adj_pre_maturities", inplace=True)
+
+        if self.adj_expirations:
+            df["ExpirationDate"] = (
+                df["ExpirationDate"].dt.to_period("M").dt.to_timestamp()
+            )
+
+        return df.sort_values(["ExpirationDate"], ignore_index=True)
+
+    @property
+    def expirations(self) -> pd.Series:
+        """
+        Get the unique expiration dates for DI contracts on the initialized trade date.
+
+        This property returns the unique expiration dates for DI contracts
+        based on the instance's trade date and applied filters.
+
+        Returns:
+            pd.Series: A Series of unique expiration dates for DI contracts.
+        """
+        df = self.data().drop_duplicates(subset=["ExpirationDate"])
+        return df["ExpirationDate"].sort_values(ignore_index=True)
+
+    @property
+    def forwards(self) -> pd.DataFrame:
+        """
+        Calculate the DI forward rates for the initialized trade date.
+
+        This property returns a DataFrame with both the SettlementRate and the
+        calculated ForwardRate for DI contracts, based on the instance's trade date and
+        applied filters.
+
+        Returns:
+            pd.DataFrame: A DataFrame containing the following columns:
+                - ExpirationDate: The expiration dates of the DI contracts.
+                - SettlementRate: The zero rate (interest rate) for each expiration
+                  date.
+                - ForwardRate: The forward rate calculated between successive expiration
+                  dates.
+        """
+        df = self.data()
+        if df.empty:
+            return pd.DataFrame()
+
+        df["ForwardRate"] = forward_rates(
+            business_days=bday.count(self._trade_date, df["ExpirationDate"]),
+            zero_rates=df["SettlementRate"],
+        )
+
+        return df[["ExpirationDate", "SettlementRate", "ForwardRate"]]
+
+    def rate(
+        self,
+        expiration: str | pd.Timestamp,
+        interpolate: bool = True,
+        extrapolate: bool = False,
+    ) -> float:
+        """Retrieve the DI rate for a specified expiration date."""
+        expiration = bday.offset(expiration, 0)
+
+        if not interpolate and extrapolate:
+            raise ValueError("Extrapolation is not allowed without interpolation.")
+
+        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])
+
+        if not interpolate:
+            return float("NaN")
+
+        ff_interpolator = interpolator.Interpolator(
+            method="flat_forward",
+            known_bdays=bday.count(self._trade_date, df["ExpirationDate"]),
+            known_rates=df["SettlementRate"],
+            extrapolate=extrapolate,
+        )
+
+        return ff_interpolator(bday.count(self._trade_date, expiration))
+
+    @property
+    def trade_date(self) -> pd.Timestamp:
+        """
+        Get or set the trade date for this DIFutures instance.
+
+        Returns:
+            pd.Timestamp: The trade date set for this instance.
+        """
+        return self._trade_date
+
+    @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:
+        """
+        Get or set the adj_expirations flag for this DIFutures instance.
+
+        Returns:
+            bool: Whether expiration dates are adjusted to the start of the month.
+        """
+        return self._adj_expirations
+
+    @adj_expirations.setter
+    def adj_expirations(self, value: bool):
+        self._adj_expirations = value
+
+    @property
+    def prefixed_filter(self) -> bool:
+        """
+        Get or set the prefixed_filter flag for this DIFutures instance.
+
+        Returns:
+            bool: Whether DI Futures are filtered to match prefixed Anbima bond
+                maturities.
+        """
+        return self._prefixed_filter
+
+    @prefixed_filter.setter
+    def prefixed_filter(self, value: bool):
+        self._prefixed_filter = value

pyield-0.22.0/pyield/holidays/brholidays.py

@@ -0,0 +1,94 @@
+from pathlib import Path
+from typing import Literal
+
+import numpy as np
+import pandas as pd
+
+
+class BrHolidays:
+    # The date (inclusive) when the new holidays list starts to be valid
+    TRANSITION_DATE = pd.to_datetime("2023-12-26")
+
+    def __init__(self):
+        current_dir = Path(__file__).parent
+        new_holidays_path = current_dir / "br_holidays_new.txt"
+        old_holidays_path = current_dir / "br_holidays_old.txt"
+        self.new_holidays = self._load_holidays(new_holidays_path)
+        self.old_holidays = self._load_holidays(old_holidays_path)
+
+    @staticmethod
+    def _load_holidays(file_path: Path) -> pd.Series:
+        """Loads the holidays from a file and returns it as a Series of Timestamps."""
+        df = pd.read_csv(file_path, header=None, names=["date"], comment="#")
+        holidays = pd.to_datetime(df["date"], format="%d/%m/%Y")
+        return holidays.astype("datetime64[ns]")
+
+    def get_holiday_series(
+        self,
+        dates: pd.Timestamp | pd.Series | None = None,
+        holiday_option: Literal["old", "new", "infer"] = "infer",
+    ) -> pd.Series:
+        """
+        Returns the correct list of holidays to use based on the most recent date in
+        the input.
+
+        Args:
+            dates (pd.Timestamp | pd.Series | None): The dates to use for inferring
+                the holiday list. If a single date is provided, it is used directly.
+                If a Series of dates is provided, the earliest date is used.
+
+            holiday_option (Literal): The holidays list to use. Valid options are
+                'old', 'new' or 'infer'. If 'infer' is used, the list of holidays is
+                selected based on the earliest (minimum) date in the input.
+
+        Returns:
+            pd.Series: The list of holidays as a Series of Timestamps.
+        """
+        match holiday_option:
+            case "old":
+                holidays = self.old_holidays
+
+            case "new":
+                return self.new_holidays
+
+            case "infer":
+                if dates is None:
+                    msg = "Dates must be provided when using 'infer' option."
+                    raise ValueError(msg)
+                if isinstance(dates, pd.Timestamp):
+                    earliest_date = dates
+                else:
+                    earliest_date = dates.min()
+
+                if earliest_date < BrHolidays.TRANSITION_DATE:
+                    holidays = self.old_holidays
+                else:
+                    holidays = self.new_holidays
+            case _:
+                raise ValueError("Invalid holiday list option.")
+
+        return holidays
+
+    def get_holiday_array(
+        self,
+        dates: pd.Timestamp | pd.Series | None = None,
+        holiday_option: Literal["old", "new", "infer"] = "infer",
+    ) -> np.ndarray:
+        """
+        Returns the correct list of holidays to use based on the most recent date in
+        the input.
+
+        Args:
+            dates (pd.Timestamp | pd.Series | None): The dates to use for inferring
+                the holiday list. If a single date is provided, it is used directly.
+                If a Series of dates is provided, the earliest date is used.
+
+            holiday_option (Literal): The holidays list to use. Valid options are
+                'old', 'new' or 'infer'. If 'infer' is used, the list of holidays is
+                selected based on the earliest (minimum) date in the input.
+
+        Returns:
+            np.ndarray: The list of holidays as a NumPy array of datetime64[D].
+        """
+        holidays = self.get_holiday_series(dates, holiday_option)
+        return holidays.to_numpy().astype("datetime64[D]")

{pyield-0.20.2 → pyield-0.22.0}/pyproject.toml

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

pyield-0.20.2/pyield/__about__.py

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

pyield-0.20.2/pyield/di.py

@@ -1,190 +0,0 @@
-import pandas as pd
-
-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_dataframe, get_di_dataframe
-
-
-def data(
-    trade_date: str | pd.Timestamp,
-    adj_expirations: bool = False,
-    prefixed_filter: bool = False,
-) -> pd.DataFrame:
-    """Retrieve DI contract data for a specified trade date.
-
-    This function retrieves DI contract data for the given trade date. If the historical
-    data is not available, it attempts to fetch the data from the B3 website. The
-    function can also filter and adjust expiration dates based on the provided options.
-
-    Args:
-        trade_date (str | pd.Timestamp): The trade date for which the 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 prefixed
-            Anbima bond maturities.
-
-    Returns:
-        pd.DataFrame: DataFrame containing DI contract data, with columns for
-            expiration dates and selected rates. The DataFrame is sorted by the
-            expiration date.
-    """
-    trade_date = dc.convert_input_dates(trade_date)
-    df = get_di_dataframe()
-    df.query("TradeDate == @trade_date", inplace=True)
-
-    if df.empty:
-        # There is no historical data for date provided.
-        # Let's try to fetch the data from the B3 website.
-        df = futures(contract_code="DI1", trade_date=trade_date)
-    if df.empty:
-        # If it is still empty, return an empty DataFrame.
-        return pd.DataFrame()
-
-    df.drop(columns=["TradeDate"], inplace=True)
-    if "DaysToExpiration" in df.columns:
-        df.drop(columns=["DaysToExpiration"], inplace=True)
-
-    if prefixed_filter:
-        df_pre = (
-            get_anbima_dataframe()
-            .query("ReferenceDate == @trade_date")
-            .query("BondType in ['LTN', 'NTN-F']")
-            .drop_duplicates(ignore_index=True)
-        )
-        pre_maturities = df_pre["MaturityDate"]
-        adj_pre_maturities = bday.offset(pre_maturities, 0)  # noqa
-        df.query("ExpirationDate in @adj_pre_maturities", inplace=True)
-
-    if adj_expirations:
-        df["ExpirationDate"] = df["ExpirationDate"].dt.to_period("M")
-        df["ExpirationDate"] = df["ExpirationDate"].dt.to_timestamp()
-
-    return df.sort_values(["ExpirationDate"], ignore_index=True)
-
-
-def expirations(
-    trade_date: str | pd.Timestamp,
-    adj_expirations: bool = False,
-    prefixed_filter: bool = False,
-) -> pd.Series:
-    """Retrieve unique expiration dates for DI contracts on a specified trade date.
-
-    This function returns a Series of unique expiration dates for DI contracts
-    for the given trade date. The expiration dates can be adjusted or filtered
-    based on the provided options.
-
-    Args:
-        trade_date (str | pd.Timestamp): The trade date for which expiration dates are
-            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 prefixed
-            Anbima bond maturities.
-
-    Returns:
-        pd.Series: A Series of unique expiration dates for DI contracts.
-    """
-    trade_date = dc.convert_input_dates(trade_date)
-    df = data(trade_date, adj_expirations, prefixed_filter)
-    df = df.drop_duplicates(subset=["ExpirationDate"], ignore_index=True)
-    return df["ExpirationDate"]
-
-
-def rate(
-    trade_date: str | pd.Timestamp,
-    expiration: str | pd.Timestamp,
-    interpolate: bool = True,
-    extrapolate: bool = False,
-) -> float:
-    """Retrieve the DI rate for a specified trade date and expiration date.
-
-    This function returns the DI rate for the given trade date and expiration date.
-    The function uses the SettlementRate column from the DI contract data and
-    interpolates the rate using the flat forward method if required.
-
-    Args:
-        trade_date (str | pd.Timestamp): The trade date for which the DI rate is
-            required.
-        expiration (str | pd.Timestamp): The expiration date for the DI contract.
-        interpolate (bool): If True, interpolates the rate for the provided expiration
-            date.
-        extrapolate (bool): If True, extrapolates the rate for expiration dates beyond
-            the available data.
-
-    Returns:
-        float: The DI rate for the specified trade date and expiration date, or NaN
-               if the rate cannot be determined.
-    """
-    # Convert input dates to consistent format
-    trade_date = dc.convert_input_dates(trade_date)
-    # Adjust expiration date to the nearest business day
-    expiration = bday.offset(expiration, 0)
-
-    # Return an error if interpolation is not allowed and extrapolation is required
-    if not interpolate and extrapolate:
-        raise ValueError("Extrapolation is not allowed without interpolation.")
-
-    # Retrieve the data for the given trade date
-    df = data(trade_date)
-
-    # Return NaN if no data is found for the trade date
-    if df.empty:
-        return float("NaN")
-
-    # Filter data for the specified expiration date
-    df_exp = df.query("ExpirationDate == @expiration")
-
-    # Return NaN if no exact match is found and interpolation is not allowed
-    if df_exp.empty and not interpolate:
-        return float("NaN")
-
-    if expiration in df_exp["ExpirationDate"]:
-        # Return the rate if an exact match is found
-        return float(df_exp["SettlementRate"].iloc[0])
-
-    if not interpolate:
-        # Return NaN if no exact match is found and interpolation is not allowed
-        return float("NaN")
-
-    # Perform flat forward interpolation if required
-    ff_interpolator = interpolator.Interpolator(
-        method="flat_forward",
-        known_bdays=bday.count(trade_date, df["ExpirationDate"]),
-        known_rates=df["SettlementRate"],
-        extrapolate=extrapolate,
-    )
-
-    # Return the interpolated rate for the calculated business days
-    return ff_interpolator(bday.count(trade_date, expiration))
-
-
-def trade_dates(
-    start_date: str | pd.Timestamp | None = None,
-    end_date: str | pd.Timestamp | None = None,
-) -> pd.Series:
-    """Retrieve unique trade dates for DI contracts within a specified date range.
-
-    This function returns a Series of unique trade dates for DI contracts within the
-    given date range.
-
-    Args:
-        start_date (str | pd.Timestamp): The start date of the date range. If None,
-            the earliest available date is used.
-        end_date (str | pd.Timestamp): The end date of the date range. If None, the
-            latest available date is used.
-
-    Returns:
-        pd.Series: A Series of unique trade dates for DI contracts.
-    """
-    df = get_di_dataframe()
-    if start_date:
-        start_date = dc.convert_input_dates(start_date)
-        df = df.query("TradeDate >= @start_date")
-    if end_date:
-        end_date = dc.convert_input_dates(end_date)
-        df = df.query("TradeDate <= @end_date")
-
-    df = df.drop_duplicates(subset=["TradeDate"], ignore_index=True)
-    return df["TradeDate"]

pyield-0.20.2/pyield/holidays/brholidays.py

@@ -1,62 +0,0 @@
-from pathlib import Path
-from typing import Literal
-
-import pandas as pd
-
-
-class BrHolidays:
-    # The date (inclusive) when the new holidays list starts to be valid
-    TRANSITION_DATE = pd.to_datetime("2023-12-26")
-
-    def __init__(self):
-        current_dir = Path(__file__).parent
-        new_holidays_path = current_dir / "br_holidays_new.txt"
-        old_holidays_path = current_dir / "br_holidays_old.txt"
-        self.new_holidays = self._load_holidays(new_holidays_path)
-        self.old_holidays = self._load_holidays(old_holidays_path)
-
-    @staticmethod
-    def _load_holidays(file_path: Path) -> pd.Series:
-        """
-        Loads the holidays from a text file and returns it as a Series of Timestamps.
-        """
-        df = pd.read_csv(file_path, header=None, names=["date"], comment="#")
-        # Convert the dates to a pd.Series of pd.Timestamp
-        holidays = pd.to_datetime(df["date"], format="%d/%m/%Y")
-        return holidays.astype("datetime64[ns]")
-
-    def get_applicable_holidays(
-        self,
-        dates: pd.Timestamp | pd.Series,
-        holiday_list: Literal["old", "new", "infer"] = "infer",
-    ) -> pd.Series:
-        """
-        Returns the correct list of holidays to use based on the most recent date in
-        the input.
-
-        Args:
-            dates (pd.Timestamp | pd.Series): The date(s) to use to infer the holidays.
-            holiday_list (str): The holidays list to use. Valid options are 'old', 'new'
-                or 'infer'. If 'infer' is used, the list of holidays is selected based
-                on the earliest (minimum) date in the input.
-
-        Returns:
-            pd.Series: The list of holidays to use.
-        """
-        if isinstance(dates, pd.Timestamp):
-            earliest_date = dates
-        else:
-            earliest_date = dates.min()
-
-        match holiday_list:
-            case "old":
-                return self.old_holidays
-            case "new":
-                return self.new_holidays
-            case "infer":
-                if earliest_date < BrHolidays.TRANSITION_DATE:
-                    return self.old_holidays
-                else:
-                    return self.new_holidays
-            case _:
-                raise ValueError("Invalid holiday list option.")