PYield 0.19.2__tar.gz → 0.19.3__tar.gz

{pyield-0.19.2 → pyield-0.19.3}/PKG-INFO

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

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

{pyield-0.19.2 → pyield-0.19.3}/pyield/bday.py

@@ -1,14 +1,11 @@
-import datetime as dt
 from typing import Literal, overload
 
 import numpy as np
 import pandas as pd
 
+from . import date_converter as dc
 from . import holidays
-
-type ScalarDateTypes = str | np.datetime64 | pd.Timestamp | dt.datetime | dt.date
-type PandasArrayDateTypes = pd.Series | pd.DatetimeIndex | pd.Index
-type ArrayDateTypes = PandasArrayDateTypes | np.ndarray | list | tuple
+from .date_converter import ArrayDateTypes, ScalarDateTypes
 
 type ArrayIntTypes = np.ndarray | pd.Series | list | tuple
 type ScalarIntTypes = int | np.integer
@@ -17,44 +14,6 @@ type ScalarIntTypes = int | np.integer
 br_holidays = holidays.BrHolidays()
 
 
-@overload
-def _convert_input_dates(dates: ScalarDateTypes) -> pd.Timestamp: ...
-@overload
-def _convert_input_dates(dates: ArrayDateTypes) -> pd.Series: ...
-
-
-def _convert_input_dates(
-    dates: ScalarDateTypes | ArrayDateTypes,
-) -> pd.Timestamp | pd.Series:
-    result = pd.to_datetime(dates, dayfirst=True)
-    if isinstance(result, (pd.Timestamp, dt.date, dt.datetime, np.datetime64)):
-        result = pd.Timestamp(result).normalize()
-    elif isinstance(result, (pd.Series, pd.DatetimeIndex)):
-        result = pd.Series(result).astype("datetime64[ns]")
-    else:
-        raise ValueError("Invalid date input type.")
-
-    return result
-
-
-def _convert_to_numpy_date(
-    dates: pd.Timestamp | pd.Series,
-) -> np.datetime64 | np.ndarray:
-    """
-    Converts the input dates to a numpy datetime64[D] format.
-
-    Args:
-        dates (Timestamp | Series): A single date or a Series of dates.
-
-    Returns:
-        np.datetime64 | np.ndarray: The input dates in a numpy datetime64[D] format.
-    """
-    if isinstance(dates, pd.Timestamp):
-        return np.datetime64(dates, "D")
-    else:
-        return dates.to_numpy().astype("datetime64[D]")
-
-
 @overload
 def offset(
     dates: ScalarDateTypes,
@@ -188,14 +147,14 @@ def offset(
         information on error handling and behavior, refer to the `numpy.busday_offset`
         documentation: https://numpy.org/doc/stable/reference/generated/numpy.busday_offset.html
     """
-    normalized_dates = _convert_input_dates(dates)
+    converted_dates = dc.convert_input_dates(dates)
 
     selected_holidays = br_holidays.get_applicable_holidays(
-        normalized_dates, holiday_list
+        converted_dates, holiday_list
     )
-    selected_holidays_np = _convert_to_numpy_date(selected_holidays)
+    selected_holidays_np = dc.convert_to_numpy_date(selected_holidays)
 
-    dates_np = _convert_to_numpy_date(normalized_dates)
+    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
     )
@@ -304,18 +263,18 @@ def count(
         1    19
         dtype: Int64
     """
-    normalized_start = _convert_input_dates(start)
-    normalized_end = _convert_input_dates(end)
+    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(
-        normalized_start, holiday_list
+        converted_start, holiday_list
     )
-    selected_holidays_np = _convert_to_numpy_date(selected_holidays)
+    selected_holidays_np = dc.convert_to_numpy_date(selected_holidays)
 
     # Convert inputs to numpy datetime64[D] before calling numpy.busday_count
-    start_np = _convert_to_numpy_date(normalized_start)
-    end_np = _convert_to_numpy_date(normalized_end)
+    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):
@@ -371,11 +330,12 @@ def generate(
         https://pandas.pydata.org/docs/reference/api/pandas.bdate_range.html.
     """
     if start:
-        converted_start = _convert_input_dates(start)
+        converted_start = dc.convert_input_dates(start)
     else:
         converted_start = pd.Timestamp.today()
+
     if end:
-        converted_end = _convert_input_dates(end)
+        converted_end = dc.convert_input_dates(end)
     else:
         converted_end = pd.Timestamp.today()
 
@@ -410,6 +370,6 @@ def is_business_day(date: ScalarDateTypes) -> bool:
         >>> bday.is_business_day("25-12-2023")  # Christmas
         False
     """
-    converted_date = _convert_input_dates(date)
+    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

{pyield-0.19.2 → pyield-0.19.3}/pyield/bonds/bond_tools.py

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

{pyield-0.19.2 → pyield-0.19.3}/pyield/bonds/lft.py

@@ -62,8 +62,8 @@ def quotation(
         98.9645
     """
     # Validate and normalize dates
-    settlement = dc.convert_date(settlement)
-    maturity = dc.convert_date(maturity)
+    settlement = dc.convert_input_dates(settlement)
+    maturity = dc.convert_input_dates(maturity)
 
     # The number of bdays between settlement (inclusive) and the maturity (exclusive)
     bdays = bday.count(settlement, maturity)

{pyield-0.19.2 → pyield-0.19.3}/pyield/bonds/ltn.py

@@ -66,8 +66,8 @@ def price(
     """
 
     # Validate and normalize dates
-    settlement = dc.convert_date(settlement)
-    maturity = dc.convert_date(maturity)
+    settlement = dc.convert_input_dates(settlement)
+    maturity = dc.convert_input_dates(maturity)
 
     # Calculate the number of business days between settlement and cash flow dates
     bdays = bday.count(settlement, maturity)
@@ -138,8 +138,8 @@ def historical_premium(
                If the data is not available, returns NaN.
     """
     # Convert input dates to a consistent format
-    reference_date = dc.convert_date(reference_date)
-    maturity = dc.convert_date(maturity)
+    reference_date = dc.convert_input_dates(reference_date)
+    maturity = dc.convert_input_dates(maturity)
 
     # Retrieve LTN rates for the reference date
     df_anbima = rates(reference_date)

{pyield-0.19.2 → pyield-0.19.3}/pyield/bonds/ntnb.py

@@ -99,8 +99,8 @@ def _generate_coupon_dates_map(
         pd.Series: Series of coupon dates within the specified range.
     """
     # Validate and normalize dates
-    start = dc.convert_date(start)
-    end = dc.convert_date(end)
+    start = dc.convert_input_dates(start)
+    end = dc.convert_input_dates(end)
 
     # Initialize the first coupon date based on the reference date
     reference_year = start.year
@@ -138,8 +138,8 @@ def payment_dates(
         pd.Series: Series of coupon dates within the specified range.
     """
     # Validate and normalize dates
-    settlement = dc.convert_date(settlement)
-    maturity = dc.convert_date(maturity)
+    settlement = dc.convert_input_dates(settlement)
+    maturity = dc.convert_input_dates(maturity)
     _check_maturities(maturity)
 
     # Check if maturity date is after the start date
@@ -180,8 +180,8 @@ def cash_flows(
         - CashFlow: Cash flow value for the bond
     """
     # Validate and normalize dates
-    settlement = dc.convert_date(settlement)
-    maturity = dc.convert_date(maturity)
+    settlement = dc.convert_input_dates(settlement)
+    maturity = dc.convert_input_dates(maturity)
 
     # Get the coupon dates between the settlement and maturity dates
     p_dates = payment_dates(settlement, maturity)
@@ -225,8 +225,8 @@ def quotation(
         99.5341
     """
     # Validate and normalize dates
-    settlement = dc.convert_date(settlement)
-    maturity = dc.convert_date(maturity)
+    settlement = dc.convert_input_dates(settlement)
+    maturity = dc.convert_input_dates(maturity)
     _check_maturities(maturity)
 
     cf_df = cash_flows(settlement, maturity)
@@ -306,7 +306,7 @@ def spot_rates(
                 - SpotRate: The real spot rate for the bond.
     """
     # Process and validate the input data
-    settlement = dc.convert_date(settlement)
+    settlement = dc.convert_input_dates(settlement)
     maturities = pd.to_datetime(maturities, errors="raise", dayfirst=True)
     _check_maturities(maturities)
 
@@ -401,7 +401,7 @@ def bei_rates(
         settlement date to the bond's maturity.
     """
     # Normalize input dates
-    settlement = dc.convert_date(settlement)
+    settlement = dc.convert_input_dates(settlement)
     ntnb_maturities = pd.to_datetime(ntnb_maturities, errors="coerce", dayfirst=True)
 
     # Calculate Real Interest Rate (RIR)
@@ -434,8 +434,8 @@ def duration(
     maturity: str | pd.Timestamp,
     rate: float,
 ) -> float:
-    settlement = dc.convert_date(settlement)
-    maturity = dc.convert_date(maturity)
+    settlement = dc.convert_input_dates(settlement)
+    maturity = dc.convert_input_dates(maturity)
 
     df = cash_flows(settlement, maturity)
     df["BY"] = bday.count(settlement, df["PaymentDate"]) / 252

{pyield-0.19.2 → pyield-0.19.3}/pyield/bonds/ntnf.py

@@ -85,8 +85,8 @@ def coupon_dates(
             (exclusive) and maturity (inclusive) dates.
     """
     # Validate and normalize dates
-    settlement = dc.convert_date(settlement)
-    maturity = dc.convert_date(maturity)
+    settlement = dc.convert_input_dates(settlement)
+    maturity = dc.convert_input_dates(maturity)
 
     # Check if the maturity date is valid
     _check_maturity_date(maturity)
@@ -131,8 +131,8 @@ def cash_flows(
         pd.DataFrame: DataFrame with columns "PaymentDate" and "CashFlow".
     """
     # Validate input dates
-    settlement = dc.convert_date(settlement)
-    maturity = dc.convert_date(maturity)
+    settlement = dc.convert_input_dates(settlement)
+    maturity = dc.convert_input_dates(maturity)
     _check_maturity_date(maturity)
 
     # Get the coupon payment dates between the settlement and maturity dates
@@ -221,7 +221,7 @@ def spot_rates(  # noqa
         pd.DataFrame: DataFrame with columns "MaturityDate" and "SpotRate"
     """
     # Process and validate the input data
-    settlement = dc.convert_date(settlement)
+    settlement = dc.convert_input_dates(settlement)
 
     # Create flat forward interpolators for LTN and NTN-F rates
     ltn_rate_interpolator = it.Interpolator(
@@ -379,8 +379,8 @@ def di_net_spread(  # noqa
         float: The net DI spread in basis points.
     """
     # Create an interpolator for the DI rates using the flat-forward method
-    settlement = dc.convert_date(settlement)
-    ntnf_maturity = dc.convert_date(ntnf_maturity)
+    settlement = dc.convert_input_dates(settlement)
+    ntnf_maturity = dc.convert_input_dates(ntnf_maturity)
 
     ff_interpolator = it.Interpolator(
         "flat_forward",
@@ -420,8 +420,8 @@ def premium(
     di_expirations: pd.Series,
     di_rates: pd.Series,
 ) -> float:
-    ntnf_maturity = dc.convert_date(ntnf_maturity)
-    settlement = dc.convert_date(settlement)
+    ntnf_maturity = dc.convert_input_dates(ntnf_maturity)
+    settlement = dc.convert_input_dates(settlement)
 
     df = cash_flows(settlement, ntnf_maturity, adj_payment_dates=True)
     df["BDays"] = bday.count(settlement, df["PaymentDate"])
@@ -460,8 +460,8 @@ def historical_premium(
     reference_date: str | pd.Timestamp,
     maturity: str | pd.Timestamp,  # noqa
 ) -> float:
-    reference_date = dc.convert_date(reference_date)
-    maturity = dc.convert_date(maturity)
+    reference_date = dc.convert_input_dates(reference_date)
+    maturity = dc.convert_input_dates(maturity)
 
     df_ntnf = rates(reference_date)
     if df_ntnf.empty:
@@ -503,8 +503,8 @@ def duration(
     maturity: str | pd.Timestamp,
     rate: float,
 ) -> float:
-    settlement = dc.convert_date(settlement)
-    maturity = dc.convert_date(maturity)
+    settlement = dc.convert_input_dates(settlement)
+    maturity = dc.convert_input_dates(maturity)
 
     df = cash_flows(settlement, maturity)
     df["BY"] = bday.count(settlement, df["PaymentDate"]) / 252

{pyield-0.19.2 → pyield-0.19.3}/pyield/data_sources/anbima.py

@@ -110,7 +110,7 @@ def data(
     bond_type: str | None = None,
 ) -> pd.DataFrame:
     # Normalize the reference date
-    reference_date = dc.convert_date(reference_date)
+    reference_date = dc.convert_input_dates(reference_date)
     file_content = _get_file_content(reference_date)
 
     if not file_content:
@@ -134,7 +134,7 @@ def rates(
 ) -> pd.DataFrame:
     df = get_anbima_dataframe()
 
-    reference_date = dc.convert_date(reference_date)
+    reference_date = dc.convert_input_dates(reference_date)
     df.query("ReferenceDate == @reference_date", inplace=True)
 
     if df.empty:
@@ -159,7 +159,7 @@ def pre_maturities(
     reference_date: str | pd.Timestamp,
 ) -> pd.Series:
     df = get_anbima_dataframe()
-    reference_date = dc.convert_date(reference_date)
+    reference_date = dc.convert_input_dates(reference_date)
     df.query("ReferenceDate == @reference_date", inplace=True)
     df.query("BondType in ['LTN', 'NTN-F']", inplace=True)
     maturity_dates = df["MaturityDate"].drop_duplicates()

{pyield-0.19.2 → pyield-0.19.3}/pyield/data_sources/di.py

@@ -30,7 +30,7 @@ def data(
             expiration dates and selected rates. The DataFrame is sorted by the
             expiration date.
     """
-    trade_date = dc.convert_date(trade_date)
+    trade_date = dc.convert_input_dates(trade_date)
     df = get_di_dataframe()
     df.query("TradeDate == @trade_date", inplace=True)
 
@@ -86,7 +86,7 @@ def expirations(
     Returns:
         pd.Series: A Series of unique expiration dates for DI contracts.
     """
-    trade_date = dc.convert_date(trade_date)
+    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"]
@@ -118,7 +118,7 @@ def rate(
                if the rate cannot be determined.
     """
     # Convert input dates to consistent format
-    trade_date = dc.convert_date(trade_date)
+    trade_date = dc.convert_input_dates(trade_date)
     # Adjust expiration date to the nearest business day
     expiration = bday.offset(expiration, 0)
 
@@ -180,10 +180,10 @@ def trade_dates(
     """
     df = get_di_dataframe()
     if start_date:
-        start_date = dc.convert_date(start_date)
+        start_date = dc.convert_input_dates(start_date)
         df = df.query("TradeDate >= @start_date")
     if end_date:
-        end_date = dc.convert_date(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)

{pyield-0.19.2 → pyield-0.19.3}/pyield/data_sources/futures_data/__init__.py

@@ -47,7 +47,7 @@ def futures(
     if contract_code not in SUPPORTED_FUTURES:
         raise ValueError("Futures contract not supported.")
 
-    trade_date = dc.convert_date(trade_date)
+    trade_date = dc.convert_input_dates(trade_date)
 
     # First, try to fetch historical data for the specified date
     df = fetch_historical_df(contract_code, trade_date)

{pyield-0.19.2 → pyield-0.19.3}/pyield/data_sources/indicators.py

@@ -13,7 +13,7 @@ def indicator(
     indicator_type: Literal["IPCA_MR", "SELIC_TARGET", "SELIC_OVER", "DI", "VNA_LFT"],
     reference_date: str | pd.Timestamp,
 ) -> float:
-    reference_date = dc.convert_date(reference_date)
+    reference_date = dc.convert_input_dates(reference_date)
     ind_type = str(indicator_type).upper()
     if ind_type == "IPCA_MR":
         return ipca_monthly_rate(reference_date)

pyield-0.19.3/pyield/date_converter.py

@@ -0,0 +1,82 @@
+import datetime as dt
+import re
+from typing import overload
+
+import numpy as np
+import pandas as pd
+
+type ScalarDateTypes = str | np.datetime64 | pd.Timestamp | dt.datetime | dt.date
+type PandasArrayDateTypes = pd.Series | pd.DatetimeIndex | pd.Index
+type ArrayDateTypes = PandasArrayDateTypes | np.ndarray | list | tuple
+
+
+def validate_year_format(value):
+    """If the input date is a string, it validates the year format."""
+    if not isinstance(value, str):
+        return
+
+    value = value.strip().lower()
+    if value in {"today", "now"}:
+        return
+
+    if re.match(r"^\d{4}-", value):
+        error_msg = f"Invalid format: {value}. Day first format is required. Example: '31-05-2024'."  # noqa
+        raise ValueError(error_msg)
+
+
+def check_first_value(dates):
+    match dates:
+        case None:
+            raise ValueError("Date cannot be None.")
+        case str():
+            validate_year_format(dates)
+        case list() | tuple() | np.ndarray() | pd.Series():
+            validate_year_format(dates[0])
+
+
+@overload
+def convert_input_dates(dates: ScalarDateTypes) -> pd.Timestamp: ...
+@overload
+def convert_input_dates(dates: ArrayDateTypes) -> pd.Series: ...
+
+
+def convert_input_dates(
+    dates: ScalarDateTypes | ArrayDateTypes,
+) -> pd.Timestamp | pd.Series:
+    check_first_value(dates)
+
+    result = pd.to_datetime(dates, dayfirst=True)
+
+    match result:
+        case pd.Timestamp():
+            result = result.normalize()
+        case dt.datetime() | dt.date() | np.datetime64():
+            result = pd.Timestamp(result).normalize()
+        case pd.Series():
+            result = result.astype("datetime64[ns]")
+        case pd.DatetimeIndex():
+            result = pd.Series(result).astype("datetime64[ns]")
+        case None:
+            raise ValueError("Date cannot be None.")
+        case _:
+            raise ValueError("Invalid date input type.")
+
+    return result
+
+
+def convert_to_numpy_date(
+    dates: pd.Timestamp | pd.Series,
+) -> np.datetime64 | np.ndarray:
+    """
+    Converts the input dates to a numpy datetime64[D] format.
+
+    Args:
+        dates (Timestamp | Series): A single date or a Series of dates.
+
+    Returns:
+        np.datetime64 | np.ndarray: The input dates in a numpy datetime64[D] format.
+    """
+    if isinstance(dates, pd.Timestamp):
+        return np.datetime64(dates, "D")
+    else:
+        return dates.to_numpy().astype("datetime64[D]")

{pyield-0.19.2 → pyield-0.19.3}/pyproject.toml

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

pyield-0.19.2/pyield/__about__.py

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

pyield-0.19.2/pyield/date_converter.py

@@ -1,65 +0,0 @@
-import datetime as dt
-import re
-
-import numpy as np
-import pandas as pd
-
-
-def _starts_with_year(date_str: str) -> bool:
-    """Check if the date string starts with a four-digit year."""
-    if date_str in {"today", "now"}:
-        return False
-    else:
-        return bool(re.match(r"^\d{4}-", date_str))
-
-
-def convert_date(
-    input_date: str | pd.Timestamp | np.datetime64 | dt.date | dt.datetime,
-) -> pd.Timestamp:
-    """
-    Convert a date to pandas Timestamp adjusted to midnight.
-
-    Args:
-        reference_date (str | pd.Timestamp | np.datetime64): The date to convert.
-            If str, it should be with day first format (e.g. "31-05-2024").
-
-    Returns:
-        pd.Timestamp: A normalized pandas Timestamp.
-
-    Raises:
-        ValueError: If the input date format is invalid.
-
-    Notes:
-        - Normalization means setting the time component of the timestamp to midnight.
-        - Business day calculations consider Brazilian holidays.
-
-    Examples:
-        >>> convert_date("31-05-2024")
-        Timestamp('2024-05-31 00:00:00')
-    """
-    match input_date:
-        case None:
-            raise ValueError("Date cannot be None.")
-        case str():
-            if _starts_with_year(input_date):
-                raise ValueError(
-                    f"Invalid date format: {input_date}. Day first format is required (e.g. '31-05-2024')."  # noqa
-                )
-            # Parse the date string with day first format
-            output_date = pd.to_datetime(input_date, dayfirst=True)
-        case pd.Timestamp():
-            # Use Timestamp as is
-            output_date = input_date
-        case np.datetime64():
-            # Convert numpy datetime to pandas Timestamp
-            output_date = pd.Timestamp(input_date)
-        case dt.date():
-            # Convert datetime.date to pandas Timestamp
-            output_date = pd.Timestamp(input_date)
-        case dt.datetime():
-            # Convert datetime.datetime to pandas Timestamp
-            output_date = pd.Timestamp(input_date)
-        case _:
-            raise ValueError(f"Date format not recognized: {input_date}")
-    # Normalize the final date to midnight
-    return output_date.normalize()