PYield 0.3.7__tar.gz → 0.4.0__tar.gz

{pyield-0.3.7 → pyield-0.4.0}/PKG-INFO

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

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

{pyield-0.3.7 → pyield-0.4.0}/pyield/__init__.py

@@ -1,6 +1,6 @@
 from .__about__ import __version__
 from .di_futures import get_di, read_di
-from .br_calendar import count_bdays, generate_bdays, offset_bdays
+from .br_calendar import count_bdays, generate_bdays, offset_bdays, is_business_day
 from .anbima import get_treasury_rates, calculate_treasury_di_spreads
 
 __all__ = [
@@ -10,6 +10,7 @@ __all__ = [
     "count_bdays",
     "generate_bdays",
     "offset_bdays",
+    "is_business_day",
     "get_treasury_rates",
     "calculate_treasury_di_spreads",
 ]

{pyield-0.3.7 → pyield-0.4.0}/pyield/anbima.py

@@ -13,32 +13,26 @@ ANBIMA_MEMBER_URL = "http://www.anbima.associados.rtm/merc_sec/arqs/"
 BP_CONVERSION_FACTOR = 10_000
 
 
-def process_reference_date(reference_date: str | Timestamp | None = None) -> Timestamp:
-    """
-    Process the given reference date, converting it to a pandas Timestamp. If no date is provided,
-    use the previous business day based on the Brazilian calendar.
-
-    Parameters:
-    - reference_date (str | pd.Timestamp | None): The reference date to process.
-
-    Returns:
-    - pd.Timestamp: The processed reference date.
-    """
-    if reference_date:  # Force reference_date to be a pd.Timestamp
-        processed_date = pd.to_datetime(reference_date)
-    else:  # If no reference_date is given, use the previous business day
+def normalize_date(reference_date: str | Timestamp | None = None) -> Timestamp:
+    if isinstance(reference_date, str):
+        normalized_date = pd.Timestamp(reference_date).normalize()
+    elif isinstance(reference_date, Timestamp):
+        normalized_date = reference_date.normalize()
+    elif reference_date is None:
         today = pd.Timestamp.today().normalize()
-        processed_date = cl.offset_bdays(today, -1)  # type: ignore
-
-    # Check if the reference date is Timestamp
-    if not isinstance(processed_date, Timestamp):
-        raise ValueError("Reference date must be a pandas Timestamp.")
+        normalized_date = cl.offset_bdays(today, -1)
+    else:
+        raise ValueError("Invalid date format.")
 
     # Raise an error if the reference date is in the future
-    if processed_date > pd.Timestamp.today().normalize():
+    if normalized_date > pd.Timestamp.today().normalize():
         raise ValueError("Reference date cannot be in the future.")
 
-    return processed_date
+    # Raise error if the reference date is not a business day
+    if not cl.is_business_day(normalized_date):
+        raise ValueError("Reference date must be a business day.")
+
+    return normalized_date
 
 
 def get_raw_data(
@@ -55,10 +49,10 @@ def get_raw_data(
     - pd.DataFrame: DataFrame with the indicative rates for the given date.
     """
     # Process the reference date, defaulting to the previous business day if not provided
-    validated_date = process_reference_date(reference_date)
+    normalized_date = normalize_date(reference_date)
 
     # Format the date to match the URL format
-    url_date = validated_date.strftime("%y%m%d")
+    url_date = normalized_date.strftime("%y%m%d")
 
     # Set the base URL according to the member status
     base_url = ANBIMA_MEMBER_URL if is_anbima_member else ANBIMA_NON_MEMBER_URL
@@ -76,7 +70,7 @@ def get_raw_data(
             dtype_backend="numpy_nullable",
         )
     except HTTPError:
-        error_date = validated_date.strftime("%d-%m-%Y")
+        error_date = normalized_date.strftime("%d-%m-%Y")
         raise ValueError(f"Failed to get ANBIMA rates for {error_date}")
 
     return df
@@ -144,7 +138,8 @@ def get_treasury_rates(
      - pd.DataFrame: DataFrame with the indicative rates for the given date.
     """
 
-    df = get_raw_data(reference_date, is_anbima_member)
+    normalized_date = normalize_date(reference_date)
+    df = get_raw_data(normalized_date, is_anbima_member)
 
     if not return_raw:
         df = process_raw_data(df)
@@ -169,11 +164,11 @@ def calculate_treasury_di_spreads(
     Returns:
     - pd.DataFrame: A DataFrame containing the bond type, reference date, maturity date, and DI spread in basis points.
     """
-    # Process the reference date, defaulting to the previous business day if not provided
-    validated_date = process_reference_date(reference_date)
+    # Validate the reference date, defaulting to the previous business day if not provided
+    normalized_date = normalize_date(reference_date)
 
     # Fetch DI rates and adjust the maturity date format for compatibility
-    df_di = di.get_di(validated_date)[["ExpirationDate", "SettlementRate"]]
+    df_di = di.get_di(normalized_date)[["ExpirationDate", "SettlementRate"]]
 
     # Renaming the columns to match the ANBIMA structure
     df_di.rename(columns={"ExpirationDate": "MaturityDate"}, inplace=True)
@@ -182,9 +177,7 @@ def calculate_treasury_di_spreads(
     df_di["MaturityDate"] = df_di["MaturityDate"].dt.to_period("M").dt.to_timestamp()
 
     # Fetch bond rates, filtering for LTN and NTN-F types
-    df_anbima = get_treasury_rates(
-        reference_date=validated_date, is_anbima_member=is_anbima_member
-    )
+    df_anbima = get_treasury_rates(normalized_date, False, is_anbima_member)
     df_anbima.query("BondType in ['LTN', 'NTN-F']", inplace=True)
 
     # Merge bond and DI rates by maturity date to calculate spreads

{pyield-0.3.7 → pyield-0.4.0}/pyield/br_calendar.py

@@ -11,24 +11,46 @@ br_holidays = BrHolidays()
 
 
 @overload
-def format_input_dates(dates: str | Timestamp | None) -> Timestamp: ...
+def normalize_input_dates(dates: str | Timestamp | None) -> Timestamp: ...
 
 
 @overload
-def format_input_dates(dates: Series) -> Series: ...
+def normalize_input_dates(dates: Series) -> Series: ...
 
 
-# Implementação da função que atende às sobrecargas acima
-def format_input_dates(dates: str | Timestamp | Series | None) -> Timestamp | Series:
-    if dates is None:
+def normalize_input_dates(dates: str | Timestamp | Series | None) -> Timestamp | Series:
+    if isinstance(dates, str):
+        return pd.Timestamp(dates).normalize()
+    elif isinstance(dates, Timestamp):
+        return dates.normalize()
+    elif isinstance(dates, Series):
+        return pd.to_datetime(dates)
+    elif dates is None:
         return pd.Timestamp.today().normalize()
-    result = pd.to_datetime(dates)
-    if isinstance(result, pd.Series):
-        return result
-    elif result is pd.NaT:
-        raise ValueError("Invalid date format.")
     else:
-        return pd.Timestamp(result).normalize()
+        raise ValueError("Invalid date format.")
+
+
+def is_business_day(date: str | Timestamp | None = None) -> bool:
+    """
+    Checks if the input date is a business day.
+
+    Args:
+        date (str | Timestamp): The date to check.
+
+    Returns:
+        bool: True if the input date is a business day, False otherwise.
+
+    Examples:
+        >>> yd.is_business_day('2023-12-25') # Christmas
+        False
+        >>> yd.is_business_day() # Check if today is a business day
+        True
+    """
+    normalized_date = normalize_input_dates(date)
+    # Shift the date if it is not a business day
+    adjusted_date = offset_bdays(normalized_date, 0)
+    return normalized_date == adjusted_date
 
 
 def convert_to_numpy_date(dates: Timestamp | Series) -> np.datetime64 | np.ndarray:
@@ -51,6 +73,7 @@ def convert_to_numpy_date(dates: Timestamp | Series) -> np.datetime64 | np.ndarr
 def offset_bdays(
     dates: str | Timestamp | None = None,
     offset: int = 0,
+    roll: Literal["forward", "backward"] = "forward",
     holiday_list: Literal["old", "new", "infer"] = "infer",
 ) -> Timestamp: ...
 
@@ -59,6 +82,7 @@ def offset_bdays(
 def offset_bdays(
     dates: Series,
     offset: int = 0,
+    roll: Literal["forward", "backward"] = "forward",
     holiday_list: Literal["old", "new", "infer"] = "infer",
 ) -> Series: ...
 
@@ -66,6 +90,7 @@ def offset_bdays(
 def offset_bdays(
     dates: str | Timestamp | Series | None = None,
     offset: int = 0,
+    roll: Literal["forward", "backward"] = "forward",
     holiday_list: Literal["old", "new", "infer"] = "infer",
 ) -> Timestamp | Series:
     """
@@ -74,16 +99,19 @@ def offset_bdays(
     right list of holidays based on the most recent date in the input.
 
     Args:
-        dates (str | pd.Timestamp | pd.Series): A single date or a Series of dates to be offset.
+        dates (str | Timestamp | Series): A single date or a Series of dates to be offset. If
+            None, the current date is used.
         offset (int): The number of business days to offset the dates. Positive numbers
             offset to the next business day, negative numbers offset to the previous
             business day. Zero offsets to the same date if it's a business day, otherwise
             offsets to the next business day.
+        roll (str, optional): The direction to roll the date if it falls on a holiday.
+            Valid options are 'forward' and 'backward'. Defaults to 'forward'.
         holiday_list (str, optional): The list of holidays to use. Defaults to "infer", which
             infers the right list of holidays based on the most recent date in the input.
 
     Returns:
-        pd.Timestamp | pd.Series: The offset dates. Returns a single date if
+        Timestamp | Series: The offset dates. Returns a single date if
         `dates` is a single date, otherwise returns a Series of dates.
 
     Note: For more information on error handling, see numpy.busday_offset documentation at
@@ -101,16 +129,16 @@ def offset_bdays(
         >>> yd.offset_bdays(date, -1)
         Timestamp('2023-12-21') # Offset to the previous business day
     """
-    formatted_dates = format_input_dates(dates)
+    normalized_dates = normalize_input_dates(dates)
 
     selected_holidays = br_holidays.get_applicable_holidays(
-        formatted_dates, holiday_list
+        normalized_dates, holiday_list
     )
     selected_holidays_np = convert_to_numpy_date(selected_holidays)
 
-    dates_np = convert_to_numpy_date(formatted_dates)
+    dates_np = convert_to_numpy_date(normalized_dates)
     offsetted_dates_np = np.busday_offset(
-        dates_np, offsets=offset, roll="forward", holidays=selected_holidays_np
+        dates_np, offsets=offset, roll=roll, holidays=selected_holidays_np
     )
     if isinstance(offsetted_dates_np, np.datetime64):
         return pd.Timestamp(offsetted_dates_np, unit="ns")
@@ -155,14 +183,16 @@ def count_bdays(
     with Pandas data types.
 
     Args:
-        start (str | Timestamp, optional): The start date. Defaults to None.
-        end (str | Timestamp optional): The end date. Defaults to None.
+        start (str | Timestamp | Series, optional): The start date. If None, the current
+            date is used. Defaults to None.
+        end (str | Timestamp | Series, optional): The end date. If None, the current date
+            is used. Defaults to None.
         holiday_list (str, optional): The list of holidays to use. Defaults to "infer",
             which infers the right list of holidays based on the most recent date in
             the input.
 
     Returns:
-        int | pd.Series: The number of business days between the start date and end date.
+        int | Series: The number of business days between the start date and end date.
         Returns an integer if the result is a single value, otherwise returns a Series.
 
     Notes:
@@ -183,18 +213,18 @@ def count_bdays(
         >>> yd.count_bdays(start, end)
         pd.Series([22, 40], dtype='int64')
     """
-    formatted_start = format_input_dates(start)
-    formatted_end = format_input_dates(end)
+    normalized_start = normalize_input_dates(start)
+    normalized_end = normalize_input_dates(end)
 
     # Determine which list of holidays to use
     selected_holidays = br_holidays.get_applicable_holidays(
-        formatted_start, holiday_list
+        normalized_start, holiday_list
     )
     selected_holidays_np = convert_to_numpy_date(selected_holidays)
 
     # Convert inputs to numpy datetime64[D] before calling numpy.busday_count
-    start_np = convert_to_numpy_date(formatted_start)
-    end_np = convert_to_numpy_date(formatted_end)
+    start_np = convert_to_numpy_date(normalized_start)
+    end_np = convert_to_numpy_date(normalized_end)
 
     result_np = np.busday_count(start_np, end_np, holidays=selected_holidays_np)
     if isinstance(result_np, np.ndarray):
@@ -219,8 +249,10 @@ def generate_bdays(
 
 
     Args:
-        start (str | pd.Timestamp, optional): The start date. Defaults to None.
-        end (str | pd.Timestamp | pd.Series, optional): The end date. Defaults to None.
+        start (str | Timestamp, optional): The start date. Defaults to None. If None,
+            the current date is used.
+        end (str | Timestamp | Series, optional): The end date. Defaults to None. If None,
+            the current date is used.
         inclusive (str, optional): Whether to include the start and end dates.
             Valid options are 'both', 'neither', 'left', 'right'. Defaults to 'both'.
         holiday_list (str, optional): The list of holidays to use. Defaults to "infer",
@@ -251,20 +283,20 @@ def generate_bdays(
         2023-12-29    2023-12-29
         dtype: object
     """
-    formatted_start = format_input_dates(start)
-    formatted_end = format_input_dates(end)
+    normalized_start = normalize_input_dates(start)
+    normalized_end = normalize_input_dates(end)
 
-    if isinstance(formatted_start, Series) or isinstance(formatted_end, Series):
+    if isinstance(normalized_start, Series) or isinstance(normalized_end, Series):
         raise ValueError("The start and end dates must be single dates.")
 
     selected_holidays = br_holidays.get_applicable_holidays(
-        formatted_start, holiday_list
+        normalized_start, holiday_list
     )
     selected_holidays_list = selected_holidays.to_list()
 
     result = pd.bdate_range(
-        formatted_start,
-        formatted_end,
+        normalized_start,
+        normalized_end,
         freq="C",
         inclusive=inclusive,
         holidays=selected_holidays_list,

{pyield-0.3.7 → pyield-0.4.0}/pyield/di_futures.py

@@ -9,6 +9,28 @@ from . import di_xml as dix
 from . import br_calendar as brc
 
 
+def normalize_date(trade_date: str | Timestamp | None = None) -> Timestamp:
+    if isinstance(trade_date, str):
+        normalized_date = pd.Timestamp(trade_date).normalize()
+    elif isinstance(trade_date, Timestamp):
+        normalized_date = trade_date.normalize()
+    elif trade_date is None:
+        today = pd.Timestamp.today().normalize()
+        normalized_date = brc.offset_bdays(today, -1)
+    else:
+        raise ValueError("Invalid date format.")
+
+    # Raise an error if the trade date is in the future
+    if normalized_date > pd.Timestamp.today().normalize():
+        raise ValueError("Trade date cannot be in the future.")
+
+    # Raise error if the reference date is not a business day
+    if not brc.is_business_day(normalized_date):
+        raise ValueError("Trade date must be a business day.")
+
+    return normalized_date
+
+
 def get_expiration_date(expiration_code: str) -> Timestamp:
     """
     Internal function to convert the expiration code into its expiration date.
@@ -75,10 +97,10 @@ def get_expiration_date(expiration_code: str) -> Timestamp:
 
 
 def get_di(
-    trade_date: str | Timestamp,
+    trade_date: str | Timestamp | None = None,
     source_type: Literal["bmf", "b3", "b3s"] = "bmf",
     return_raw: bool = False,
-) -> pd.DataFrame:
+) -> DataFrame:
     """
     Gets the DI futures data for a given date from B3.
 
@@ -86,7 +108,8 @@ def get_di(
     trade date. It's the primary external interface for accessing DI data.
 
     Args:
-        trade_date: a datetime-like object representing the trade date.
+        trade_date: a datetime-like object representing the trade date. if not provided,
+            the function will use the previous business day.
         source_type: a string indicating the source of the data. Options are "bmf",
             "b3" and "b3s" (default is "bmf").
             - "bmf" (fast) fetches DI data from old BM&FBOVESPA website. This is the default
@@ -95,15 +118,15 @@ def get_di(
             - "b3s" (fast) fetches DI data from the simplified Price Report (XML file) provided by B3.
               This option is faster than "b3" but it has less information.
         return_raw: a boolean indicating whether to return the raw DI data.
-        data_path: a Path object indicating the path to the directory where the XML
-            files are stored. This argument is only used when source_type is "b3" or
-            "b3s". If not provided, data will be downloaded from B3's website.
 
     Returns:
         pd.DataFrame: A Pandas DataFrame containing the DI Futures data for
         the given trade date.
 
     Examples:
+        # Get the DI data for the previous business day
+        >>> get_di()
+        # Get the DI data for a specific date in ISO format (YYYY-MM-DD)
         >>> get_di("2023-12-28")
 
     Notes:
@@ -113,14 +136,12 @@ def get_di(
 
     """
     # Force trade_date to be a pandas Timestamp
-    trade_date = pd.Timestamp(trade_date)
-    if not trade_date:
-        raise ValueError("Uma data de referência válida deve ser fornecida.")
+    normalized_trade_date = normalize_date(trade_date)
 
     if source_type == "bmf":
-        return diw.get_di(trade_date, return_raw)
+        return diw.get_di(normalized_trade_date, return_raw)
     elif source_type in ["b3", "b3s"]:
-        return dix.get_di(trade_date, source_type, return_raw)
+        return dix.get_di(normalized_trade_date, source_type, return_raw)
     else:
         raise ValueError("source_type must be either 'bmf', 'b3' or 'b3s'.")
 

{pyield-0.3.7 → pyield-0.4.0}/pyproject.toml

@@ -31,7 +31,7 @@ dependencies = [
     "lxml",
 ]
 dynamic = []
-version = "0.3.7"
+version = "0.4.0"
 
 [project.license]
 file = "LICENSE"

{pyield-0.3.7 → pyield-0.4.0}/tests/test_di.py

@@ -1,4 +1,5 @@
 import pandas as pd
+import pytest
 
 from pyield import di_futures as dif
 from pyield import di_web as diw
@@ -75,6 +76,7 @@ def test_settlement_rates_with_current_holiday_list():
     assert results == list(settlement_rates.values())
 
 
-def test_invalid_date():
-    result = dif.get_di(trade_date="2023-12-24")
-    assert result.empty
+def test_non_business_day():
+    non_business_day = "2023-12-24"
+    with pytest.raises(ValueError):
+        dif.get_di(trade_date=non_business_day)

pyield-0.3.7/pyield/__about__.py

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