PYield 0.3.6__tar.gz → 0.4.0__tar.gz

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

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

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

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

@@ -1,4 +1,5 @@
 import pandas as pd
+from pandas import Timestamp, DataFrame
 from urllib.error import HTTPError
 
 from . import di_futures as di
@@ -12,31 +13,31 @@ ANBIMA_MEMBER_URL = "http://www.anbima.associados.rtm/merc_sec/arqs/"
 BP_CONVERSION_FACTOR = 10_000
 
 
-def process_reference_date(
-    reference_date: str | pd.Timestamp | None = None,
-) -> pd.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.
+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()
+        normalized_date = cl.offset_bdays(today, -1)
+    else:
+        raise ValueError("Invalid date format.")
 
-    Parameters:
-    - reference_date (str | pd.Timestamp | None): The reference date to process.
+    # Raise an error if the reference date is in the future
+    if normalized_date > pd.Timestamp.today().normalize():
+        raise ValueError("Reference date cannot be in the future.")
 
-    Returns:
-    - pd.Timestamp: The processed reference date.
-    """
-    if reference_date:  # Force reference_date to be a pd.Timestamp
-        processed_date = pd.Timestamp(reference_date)
-    else:  # If no reference_date is given, use the previous business day
-        today = pd.Timestamp.today().normalize()
-        processed_date = cl.offset_bdays(today, -1)
+    # 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 processed_date
+    return normalized_date
 
 
 def get_raw_data(
-    reference_date: str | pd.Timestamp | None = None, is_anbima_member: bool = False
-) -> pd.DataFrame:
+    reference_date: str | Timestamp | None = None, is_anbima_member: bool = False
+) -> DataFrame:
     """
     Fetch indicative rates from ANBIMA for a specific date.
 
@@ -48,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
@@ -69,13 +70,13 @@ 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
 
 
-def process_raw_data(df: pd.DataFrame) -> pd.DataFrame:
+def process_raw_data(df_raw: DataFrame) -> DataFrame:
     """
     Process raw data from ANBIMA by filtering selected columns, renaming them, and adjusting data formats.
 
@@ -104,8 +105,8 @@ def process_raw_data(df: pd.DataFrame) -> pd.DataFrame:
         # "Criterio": "Criteria",
     }
     select_columns = list(selected_columns_dict.keys())
-    df = df[select_columns].copy()
-    df.rename(columns=selected_columns_dict, inplace=True)
+    df = df_raw[select_columns].copy()
+    df = df.rename(columns=selected_columns_dict)
 
     # Remove percentage from rates
     rate_cols = ["BidRate", "AskRate", "IndicativeRate"]
@@ -118,10 +119,10 @@ def process_raw_data(df: pd.DataFrame) -> pd.DataFrame:
 
 
 def get_treasury_rates(
-    reference_date: str | pd.Timestamp | None = None,
+    reference_date: str | Timestamp | None = None,
     return_raw=False,
     is_anbima_member=False,
-) -> pd.DataFrame:
+) -> DataFrame:
     """
     Fetch and process indicative rates from ANBIMA for a specific date.
     If no date is provided, the previous business day based on the Brazilian calendar
@@ -137,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)
@@ -146,9 +148,9 @@ def get_treasury_rates(
 
 
 def calculate_treasury_di_spreads(
-    reference_date: str | pd.Timestamp | None = None,
+    reference_date: str | Timestamp | None = None,
     is_anbima_member=False,
-) -> pd.DataFrame:
+) -> DataFrame:
     """
     Calculate the DI spread for LTN and NTN-F bonds based on ANBIMA's indicative rates.
     If no date is provided, the previous business day based on the Brazilian calendar
@@ -162,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)
@@ -175,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.6 → pyield-0.4.0}/pyield/br_calendar.py

@@ -1,7 +1,8 @@
-from typing import Literal
+from typing import Literal, overload
 
-import pandas as pd
 import numpy as np
+import pandas as pd
+from pandas import Series, Timestamp
 
 from .br_holidays import BrHolidays
 
@@ -9,9 +10,50 @@ from .br_holidays import BrHolidays
 br_holidays = BrHolidays()
 
 
-def convert_to_numpy_date(
-    dates: pd.Timestamp | pd.Series,
-) -> np.datetime64 | np.ndarray:
+@overload
+def normalize_input_dates(dates: str | Timestamp | None) -> Timestamp: ...
+
+
+@overload
+def normalize_input_dates(dates: Series) -> Series: ...
+
+
+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()
+    else:
+        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:
     """
     Converts the input dates to a numpy datetime64[D] format.
 
@@ -27,27 +69,49 @@ def convert_to_numpy_date(
         return dates.to_numpy().astype("datetime64[D]")
 
 
+@overload
 def offset_bdays(
-    dates: str | pd.Timestamp | pd.Series,
-    offset: int,
+    dates: str | Timestamp | None = None,
+    offset: int = 0,
+    roll: Literal["forward", "backward"] = "forward",
     holiday_list: Literal["old", "new", "infer"] = "infer",
-):
+) -> Timestamp: ...
+
+
+@overload
+def offset_bdays(
+    dates: Series,
+    offset: int = 0,
+    roll: Literal["forward", "backward"] = "forward",
+    holiday_list: Literal["old", "new", "infer"] = "infer",
+) -> Series: ...
+
+
+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:
     """
     Offsets the dates to the next or previous business day. This function is a wrapper
     for `numpy.busday_offset` to be used directly with Pandas data types that infers the
     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
@@ -65,22 +129,53 @@ def offset_bdays(
         >>> yd.offset_bdays(date, -1)
         Timestamp('2023-12-21') # Offset to the previous business day
     """
-    # Assure that the input is in pandas datetime64[ns] format
-    dates_pd = pd.to_datetime(dates)
+    normalized_dates = normalize_input_dates(dates)
 
-    selected_holidays = br_holidays.get_applicable_holidays(dates_pd, holiday_list)
+    selected_holidays = br_holidays.get_applicable_holidays(
+        normalized_dates, holiday_list
+    )
     selected_holidays_np = convert_to_numpy_date(selected_holidays)
 
-    dates_np = convert_to_numpy_date(dates_pd)
+    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")
+    else:
+        result = pd.to_datetime(offsetted_dates_np, unit="ns")
+        return pd.Series(result)
+
 
-    # Convert the dates back to a pandas datetime64[ns] format
-    return pd.to_datetime(offsetted_dates_np, unit="ns")
+@overload
+def count_bdays(
+    start: str | Timestamp | None = None,
+    end: str | Timestamp | None = None,
+    holiday_list: Literal["old", "new", "infer"] = "infer",
+) -> int: ...
 
 
-def count_bdays(start, end, holiday_list: Literal["old", "new", "infer"] = "infer"):
+@overload
+def count_bdays(
+    start: Series,
+    end: str | Timestamp | Series | None,
+    holiday_list: Literal["old", "new", "infer"] = "infer",
+) -> Series: ...
+
+
+@overload
+def count_bdays(
+    start: str | Timestamp | Series | None,
+    end: Series,
+    holiday_list: Literal["old", "new", "infer"] = "infer",
+) -> Series: ...
+
+
+def count_bdays(
+    start: str | Timestamp | Series | None = None,
+    end: str | Timestamp | Series | None = None,
+    holiday_list: Literal["old", "new", "infer"] = "infer",
+) -> int | Series:
     """
     Counts the number of business days between a `start` (inclusive) and `end`
     (exclusive). If an end date is earlier than the start date, the count will be
@@ -88,16 +183,17 @@ def count_bdays(start, end, holiday_list: Literal["old", "new", "infer"] = "infe
     with Pandas data types.
 
     Args:
-        start (str | pd.Timestamp, optional): The start date. Defaults to None.
-        end (str | pd.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:
-        np.int64 | np.ndarray: The number of business days between the start date and
-        end dates. Returns a single integer if `end` is a single Timestamp, otherwise
-        returns an ndarray of integers.
+        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:
         - For more information on error handling, see numpy.busday_count documentation at
@@ -115,30 +211,36 @@ def count_bdays(start, end, holiday_list: Literal["old", "new", "infer"] = "infe
         >>> start = '2023-01-01'
         >>> end = pd.to_datetime(['2023-01-31', '2023-03-01'])
         >>> yd.count_bdays(start, end)
-        array([22, 40])
+        pd.Series([22, 40], dtype='int64')
     """
-    # Assure that the inputs are in pandas datetime64[ns] format
-    start_pd = pd.to_datetime(start)
-    end_pd = pd.to_datetime(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(start_pd, holiday_list)
+    selected_holidays = br_holidays.get_applicable_holidays(
+        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(start_pd)
-    end_np = convert_to_numpy_date(end_pd)
+    start_np = convert_to_numpy_date(normalized_start)
+    end_np = convert_to_numpy_date(normalized_end)
 
-    return np.busday_count(start_np, end_np, holidays=selected_holidays_np)
+    result_np = np.busday_count(start_np, end_np, holidays=selected_holidays_np)
+    if isinstance(result_np, np.ndarray):
+        # Return pandas Int64 type for type consistency
+        return pd.Series(result_np, dtype="Int64")
+    else:
+        return int(result_np)
 
 
 def generate_bdays(
-    start: str | pd.Timestamp | None = None,
-    end: str | pd.Timestamp | None = None,
-    inclusive="both",
+    start: str | Timestamp | None = None,
+    end: str | Timestamp | None = None,
+    inclusive: Literal["both", "neither", "left", "right"] = "both",
     holiday_list: Literal["old", "new", "infer"] = "infer",
     **kwargs,
-) -> pd.DatetimeIndex:
+) -> Series:
     """
     Generates a Series of business days between a `start` (inclusive) and `end`
     (inclusive) that takes into account the list of brazilian holidays as the default.
@@ -147,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",
@@ -179,24 +283,23 @@ def generate_bdays(
         2023-12-29    2023-12-29
         dtype: object
     """
-    if start:
-        start_pd = pd.to_datetime(start)
-    else:
-        start_pd = pd.Timestamp.today().normalize()
+    normalized_start = normalize_input_dates(start)
+    normalized_end = normalize_input_dates(end)
 
-    if end:
-        end_pd = pd.to_datetime(end)
-    else:
-        end_pd = pd.Timestamp.today().normalize()
+    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(start_pd, holiday_list)
+    selected_holidays = br_holidays.get_applicable_holidays(
+        normalized_start, holiday_list
+    )
     selected_holidays_list = selected_holidays.to_list()
 
-    return pd.bdate_range(
-        start_pd,
-        end_pd,
+    result = pd.bdate_range(
+        normalized_start,
+        normalized_end,
         freq="C",
         inclusive=inclusive,
         holidays=selected_holidays_list,
         **kwargs,
     )
+    return pd.Series(result)

{pyield-0.3.6 → pyield-0.4.0}/pyield/br_holidays.py

@@ -2,6 +2,7 @@ from pathlib import Path
 from typing import Literal
 
 import pandas as pd
+from pandas import Series, Timestamp
 
 
 class BrHolidays:
@@ -15,7 +16,7 @@ class BrHolidays:
         self.new_holidays = self._load_holidays(new_holidays_path)
         self.old_holidays = self._load_holidays(old_holidays_path)
 
-    def _load_holidays(self, file_path: Path) -> pd.Series:
+    def _load_holidays(self, file_path: Path) -> Series:
         """Loads the list of holidays from a text file and returns it as a pd.Series of pd.Timestamp."""
         df = pd.read_csv(file_path, header=None, names=["date"], comment="#")
         # Convert the dates to a pd.Series of pd.Timestamp
@@ -23,9 +24,9 @@ class BrHolidays:
 
     def get_applicable_holidays(
         self,
-        dates: pd.Timestamp | pd.Series,
+        dates: Timestamp | Series,
         holiday_list: Literal["old", "new", "infer"] = "infer",
-    ) -> pd.Series:
+    ) -> Series:
         """
         Returns the correct list of holidays to use based on the most recent date in the input.
 
@@ -38,7 +39,7 @@ class BrHolidays:
         Returns:
             pd.Series: The list of holidays to use.
         """
-        if isinstance(dates, pd.Timestamp):
+        if isinstance(dates, Timestamp):
             earliest_date = dates
         else:
             earliest_date = dates.min()

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

@@ -1,14 +1,37 @@
-from typing import Literal, Optional
+from typing import Literal
 from pathlib import Path
+
 import pandas as pd
-import pandas.api.types
+from pandas import DataFrame, Timestamp
 
 from . import di_web as diw
 from . import di_xml as dix
 from . import br_calendar as brc
 
 
-def get_expiration_date(expiration_code: str) -> Optional[pd.Timestamp]:
+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.
 
@@ -63,18 +86,21 @@ def get_expiration_date(expiration_code: str) -> Optional[pd.Timestamp]:
         year = int("20" + expiration_code[-2:])
         # The expiration date is always the first business day of the month
         expiration = pd.Timestamp(year, month, 1)
+
         # Adjust to the next business day when expiration date is a weekend or a holiday
-        return brc.offset_bdays(expiration, offset=0)
+        adj_expiration = brc.offset_bdays(expiration, offset=0)
+
+        return adj_expiration
 
     except (KeyError, ValueError):
-        return pd.NaT  # type: ignore
+        raise ValueError("Invalid expiration code.")
 
 
 def get_di(
-    trade_date: str | pd.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.
 
@@ -82,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
@@ -91,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:
@@ -109,19 +136,17 @@ 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'.")
 
 
-def read_di(file_path: Path, return_raw: bool = False) -> pd.DataFrame:
+def read_di(file_path: Path, return_raw: bool = False) -> DataFrame:
     """
     Reads a DI futures data file and returns a DataFrame.
 

{pyield-0.3.6 → pyield-0.4.0}/pyield/di_web.py

@@ -3,6 +3,7 @@ import warnings
 from typing import Optional
 
 import pandas as pd
+from pandas import Timestamp, Series, DataFrame
 import requests
 
 from . import br_calendar as brc
@@ -10,8 +11,8 @@ from . import di_futures as dif
 
 
 def get_old_expiration_date(
-    ExpirationCode: str, trade_date: pd.Timestamp
-) -> Optional[pd.Timestamp]:
+    ExpirationCode: str, trade_date: Timestamp
+) -> Optional[Timestamp]:
     """
     Internal function to convert an old DI contract code into its ExpirationDate date. Valid for
     contract codes up to 21-05-2006.
@@ -71,7 +72,7 @@ def get_old_expiration_date(
         return pd.NaT  # type: ignore
 
 
-def get_raw_di(trade_date: pd.Timestamp) -> pd.DataFrame:
+def get_raw_di(trade_date: Timestamp) -> DataFrame:
     """
     Internal function to fetch raw DI futures data from B3 for a specific trade date.
 
@@ -119,7 +120,7 @@ def get_raw_di(trade_date: pd.Timestamp) -> pd.DataFrame:
         return pd.DataFrame()
 
 
-def convert_prices_to_rates(prices: pd.Series, bd: pd.Series) -> pd.Series:
+def convert_prices_to_rates(prices: Series, bd: Series) -> Series:
     """
     Internal function to convert DI futures prices to rates.
 
@@ -136,7 +137,7 @@ def convert_prices_to_rates(prices: pd.Series, bd: pd.Series) -> pd.Series:
     return 100 * rates
 
 
-def convert_prices_in_older_contracts(df: pd.DataFrame) -> pd.DataFrame:
+def convert_prices_in_older_contracts(df: DataFrame) -> DataFrame:
     # Prior to 01/01/2002, prices were not converted to rates
     convert_cols = [
         "FirstRate",
@@ -156,7 +157,7 @@ def convert_prices_in_older_contracts(df: pd.DataFrame) -> pd.DataFrame:
     return df
 
 
-def process_di(df: pd.DataFrame, trade_date: pd.Timestamp) -> pd.DataFrame:
+def process_di(df: DataFrame, trade_date: Timestamp) -> DataFrame:
     """
     Internal function to process and transform raw DI futures data.
 
@@ -265,7 +266,7 @@ def process_di(df: pd.DataFrame, trade_date: pd.Timestamp) -> pd.DataFrame:
     return df[ordered_cols]
 
 
-def get_di(trade_date: pd.Timestamp, return_raw: bool = False) -> pd.DataFrame:
+def get_di(trade_date: Timestamp, return_raw: bool = False) -> DataFrame:
     """
     Gets the DI futures data for a given date from B3.
 

{pyield-0.3.6 → pyield-0.4.0}/pyield/di_xml.py

@@ -4,13 +4,14 @@ from pathlib import Path
 
 import requests
 import pandas as pd
+from pandas import Timestamp, DataFrame
 from lxml import etree
 
 from . import di_futures as dif
 from . import br_calendar as brc
 
 
-def get_file_from_url(trade_date: pd.Timestamp, source_type: str) -> io.BytesIO:
+def get_file_from_url(trade_date: Timestamp, source_type: str) -> io.BytesIO:
     """
     Types of XML files available:
     Full Price Report (all assets)
@@ -119,7 +120,7 @@ def extract_di_data_from_xml(xml_file: io.BytesIO) -> list[dict]:
     return di_data
 
 
-def create_df_from_di_data(di1_data: list) -> pd.DataFrame:
+def create_df_from_di_data(di1_data: list) -> DataFrame:
     # Criar um DataFrame com os dados coletados
     df = pd.DataFrame(di1_data)
 
@@ -128,7 +129,7 @@ def create_df_from_di_data(di1_data: list) -> pd.DataFrame:
     return pd.read_csv(file, dtype_backend="numpy_nullable")
 
 
-def filter_and_order_pr_df(df: pd.DataFrame) -> pd.DataFrame:
+def filter_and_order_pr_df(df: DataFrame) -> DataFrame:
     selected_columns = [
         "TradDt",
         "TckrSymb",
@@ -164,7 +165,7 @@ def filter_and_order_pr_df(df: pd.DataFrame) -> pd.DataFrame:
     return df[selected_columns]
 
 
-def filter_and_order_sprd_df(df: pd.DataFrame) -> pd.DataFrame:
+def filter_and_order_sprd_df(df: DataFrame) -> DataFrame:
     cols = [
         "TradDt",
         "TckrSymb",
@@ -186,7 +187,7 @@ def filter_and_order_sprd_df(df: pd.DataFrame) -> pd.DataFrame:
     return df[cols]
 
 
-def standardize_column_names(df: pd.DataFrame) -> pd.DataFrame:
+def standardize_column_names(df: DataFrame) -> DataFrame:
     rename_dict = {
         "TradDt": "TradeDate",
         "TckrSymb": "Ticker",
@@ -223,7 +224,7 @@ def standardize_column_names(df: pd.DataFrame) -> pd.DataFrame:
     return df.rename(columns=rename_dict)
 
 
-def process_di_df(df_raw: pd.DataFrame) -> pd.DataFrame:
+def process_di_df(df_raw: DataFrame) -> DataFrame:
     df = df_raw.copy()
     # Convert to datetime64[ns] since it is pandas default type for timestamps
     df["TradDt"] = df["TradDt"].astype("datetime64[ns]")
@@ -243,11 +244,7 @@ def process_di_df(df_raw: pd.DataFrame) -> pd.DataFrame:
     return df.sort_values(by=["ExpirationDate"], ignore_index=True)
 
 
-def get_di(
-    trade_date: pd.Timestamp,
-    source_type: str,
-    return_raw: bool,
-) -> pd.DataFrame:
+def get_di(trade_date: Timestamp, source_type: str, return_raw: bool) -> DataFrame:
     zip_file = get_file_from_url(trade_date, source_type)
 
     xml_file = extract_xml_from_zip(zip_file)
@@ -263,6 +260,8 @@ def get_di(
         df_di = filter_and_order_pr_df(df_raw)
     elif source_type == "b3s":
         df_di = filter_and_order_sprd_df(df_raw)
+    else:
+        raise ValueError("Invalid source type. Must be 'b3' or 'b3s'.")
 
     # Process and transform data
     df_di = process_di_df(df_di)
@@ -273,7 +272,7 @@ def get_di(
     return df_di
 
 
-def read_di(file_path: Path, return_raw: bool = False) -> pd.DataFrame:
+def read_di(file_path: Path, return_raw: bool = False) -> DataFrame:
     if file_path:
         if file_path.exists():
             content = file_path.read_bytes()

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

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

{pyield-0.3.6 → 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.6/pyield/__about__.py

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

pyield-0.3.6/pyield/__init__.py

@@ -1,4 +0,0 @@
-from .__about__ import __version__  # noqa: F401
-from .di_futures import get_di, read_di  # noqa: F401
-from .br_calendar import count_bdays, generate_bdays, offset_bdays  # noqa: F401
-from .anbima import get_treasury_rates, calculate_treasury_di_spreads  # noqa: F401