openseries 1.2.2__py3-none-any.whl → 1.2.4__py3-none-any.whl

openseries/datefixer.py

@@ -1,20 +1,22 @@
-"""
-Date related utilities
-"""
+"""Date related utilities."""
 from __future__ import annotations
+
 import datetime as dt
-from typing import Optional, Union
+from typing import Optional, Union, cast
+
 from dateutil.relativedelta import relativedelta
 from holidays import country_holidays, list_supported_countries
-from numpy import array, busdaycalendar, datetime64, is_busday, where, timedelta64
-from pandas import DataFrame, date_range, Timestamp, Series, DatetimeIndex, concat
+from numpy import array, busdaycalendar, datetime64, is_busday, where
+from pandas import DataFrame, DatetimeIndex, Series, Timestamp, concat, date_range
 from pandas.tseries.offsets import CustomBusinessDay
 
 from openseries.types import (
     CountriesType,
-    TradingDaysType,
+    DateType,
+    HolidayType,
     LiteralBizDayFreq,
     LiteralPandasResampleConvention,
+    TradingDaysType,
 )
 
 
@@ -22,15 +24,10 @@ def holiday_calendar(
     startyear: int,
     endyear: int,
     countries: CountriesType = "SE",
-    custom_holidays: Optional[
-        Union[
-            dict[Union[dt.date, dt.datetime, str, float, int], str],
-            list[Union[dt.date, dt.datetime, str, float, int]],
-            Union[dt.date, dt.datetime, str, float, int],
-        ]
-    ] = None,
+    custom_holidays: Optional[HolidayType] = None,
 ) -> busdaycalendar:
-    """Function to generate a business calendar
+    """
+    Generate a business calendar.
 
     Parameters
     ----------
@@ -38,19 +35,16 @@ def holiday_calendar(
         First year in date range generated
     endyear: int
         Last year in date range generated
-    countries: list[str] | str, default: "SE"
+    countries: CountriesType, default: "SE"
         (List of) country code(s) according to ISO 3166-1 alpha-2
-    custom_holidays: Union[
-        dict[Union[dt.date, dt.datetime, str, float, int], str],
-        list[Union[dt.date, dt.datetime, str, float, int]],
-        Union[dt.date, dt.datetime, str, float, int]], optional
+    custom_holidays: HolidayType, optional
         Argument where missing holidays can be added as
         {"2021-02-12": "Jack's birthday"} or ["2021-02-12"]
 
     Returns
     -------
     numpy.busdaycalendar
-        Numpy busdaycalendar object
+        Generate a business calendar
     """
     startyear -= 1
     endyear += 1
@@ -73,25 +67,25 @@ def holiday_calendar(
             if i == 0 and custom_holidays is not None:
                 staging.update(custom_holidays)
             countryholidays += list(staging)
-        hols = array(sorted(list(set(countryholidays))), dtype="datetime64[D]")
+        hols = array(sorted(set(countryholidays)), dtype="datetime64[D]")
     else:
         raise ValueError(
             "Argument countries must be a string country code or a list "
-            "of string country codes according to ISO 3166-1 alpha-2."
+            "of string country codes according to ISO 3166-1 alpha-2.",
         )
 
     return busdaycalendar(holidays=hols)
 
 
 def date_fix(
-    fixerdate: Union[str, dt.date, dt.datetime, datetime64, Timestamp],
+    fixerdate: DateType,
 ) -> dt.date:
-    """Function to parse from different date formats into datetime.date
+    """
+    Parse different date formats into datetime.date.
 
     Parameters
     ----------
-    fixerdate: str | datetime.date | datetime.datetime |
-    numpy.datetime64 | pandas.Timestamp
+    fixerdate: DateType
         The data item to parse
 
     Returns
@@ -99,44 +93,42 @@ def date_fix(
     datetime.date
         Parsed date
     """
-
     if isinstance(fixerdate, (Timestamp, dt.datetime)):
         return fixerdate.date()
     if isinstance(fixerdate, dt.date):
         return fixerdate
     if isinstance(fixerdate, datetime64):
-        unix_epoch = datetime64(0, "s")
-        one_second = timedelta64(1, "s")
-        seconds_since_epoch = (fixerdate - unix_epoch) / one_second
-        return dt.datetime.utcfromtimestamp(float(seconds_since_epoch)).date()
+        return (
+            dt.datetime.strptime(str(fixerdate)[:10], "%Y-%m-%d")
+            .replace(tzinfo=dt.timezone.utc)
+            .date()
+        )
     if isinstance(fixerdate, str):
-        return dt.datetime.strptime(fixerdate, "%Y-%m-%d").date()
+        return (
+            dt.datetime.strptime(fixerdate, "%Y-%m-%d")
+            .replace(tzinfo=dt.timezone.utc)
+            .date()
+        )
     raise TypeError(
-        f"Unknown date format {str(fixerdate)} of "
-        f"type {str(type(fixerdate))} encountered"
+        f"Unknown date format {fixerdate!s} of "
+        f"type {type(fixerdate)!s} encountered",
     )
 
 
 def date_offset_foll(
-    raw_date: Union[str, dt.date, dt.datetime, datetime64, Timestamp],
+    raw_date: DateType,
     months_offset: int = 12,
     adjust: bool = False,
     following: bool = True,
     countries: CountriesType = "SE",
-    custom_holidays: Optional[
-        Union[
-            dict[Union[dt.date, dt.datetime, str, float, int], str],
-            list[Union[dt.date, dt.datetime, str, float, int]],
-            Union[dt.date, dt.datetime, str, float, int],
-        ]
-    ] = None,
+    custom_holidays: Optional[HolidayType] = None,
 ) -> dt.date:
-    """Function to offset dates according to a given calendar
+    """
+    Offset dates according to a given calendar.
 
     Parameters
     ----------
-    raw_date: str | datetime.date | datetime.datetime | numpy.datetime64 |
-    pandas.Timestamp
+    raw_date: DateType
         The date to offset from
     months_offset: int, default: 12
         Number of months as integer
@@ -144,12 +136,9 @@ def date_offset_foll(
         Determines if offset should adjust for business days
     following: bool, default: True
         Determines if days should be offset forward (following) or backward
-    countries: list[str] | str, default: "SE"
+    countries: CountriesType, default: "SE"
         (List of) country code(s) according to ISO 3166-1 alpha-2
-    custom_holidays: Union[
-        dict[Union[dt.date, dt.datetime, str, float, int], str],
-        list[Union[dt.date, dt.datetime, str, float, int]],
-        Union[dt.date, dt.datetime, str, float, int]], optional
+    custom_holidays: HolidayType, optional
         Argument where missing holidays can be added as
         {"2021-02-12": "Jack's birthday"} or ["2021-02-12"]
 
@@ -158,7 +147,6 @@ def date_offset_foll(
     datetime.date
         Off-set date
     """
-
     raw_date = date_fix(raw_date)
     month_delta = relativedelta(months=months_offset)
 
@@ -187,26 +175,18 @@ def date_offset_foll(
 def get_previous_business_day_before_today(
     today: Optional[dt.date] = None,
     countries: CountriesType = "SE",
-    custom_holidays: Optional[
-        Union[
-            dict[Union[dt.date, dt.datetime, str, float, int], str],
-            list[Union[dt.date, dt.datetime, str, float, int]],
-            Union[dt.date, dt.datetime, str, float, int],
-        ]
-    ] = None,
+    custom_holidays: Optional[HolidayType] = None,
 ) -> dt.date:
-    """Function to bump backwards to find the previous business day before today
+    """
+    Bump date backwards to find the previous business day.
 
     Parameters
     ----------
     today: datetime.date, optional
         Manual input of the day from where the previous business day is found
-    countries: list[str] | str, default: "SE"
+    countries: CountriesType, default: "SE"
         (List of) country code(s) according to ISO 3166-1 alpha-2
-    custom_holidays: Union[
-        dict[Union[dt.date, dt.datetime, str, float, int], str],
-        list[Union[dt.date, dt.datetime, str, float, int]],
-        Union[dt.date, dt.datetime, str, float, int]], optional
+    custom_holidays: HolidayType, optional
         Argument where missing holidays can be added as
         {"2021-02-12": "Jack's birthday"} or ["2021-02-12"]
 
@@ -215,9 +195,8 @@ def get_previous_business_day_before_today(
     datetime.date
         The previous business day
     """
-
     if today is None:
-        today = dt.date.today()
+        today = dt.datetime.now(tz=dt.timezone.utc).date()
 
     return date_offset_foll(
         today - dt.timedelta(days=1),
@@ -233,17 +212,13 @@ def offset_business_days(
     ddate: dt.date,
     days: int,
     countries: CountriesType = "SE",
-    custom_holidays: Optional[
-        Union[
-            dict[Union[dt.date, dt.datetime, str, float, int], str],
-            list[Union[dt.date, dt.datetime, str, float, int]],
-            Union[dt.date, dt.datetime, str, float, int],
-        ]
-    ] = None,
+    custom_holidays: Optional[HolidayType] = None,
 ) -> dt.date:
-    """Function to bump a date by business days instead of calendar days.
+    """
+    Bump date by business days.
+
     It first adjusts to a valid business day and then bumps with given
-    number of business days from there
+    number of business days from there.
 
     Parameters
     ----------
@@ -252,12 +227,9 @@ def offset_business_days(
     days: int
         The number of business days to offset from the business day that is
         the closest preceding the day given
-    countries: list[str] | str, default: "SE"
+    countries: CountriesType, default: "SE"
         (List of) country code(s) according to ISO 3166-1 alpha-2
-    custom_holidays: Union[
-        dict[Union[dt.date, dt.datetime, str, float, int], str],
-        list[Union[dt.date, dt.datetime, str, float, int]],
-        Union[dt.date, dt.datetime, str, float, int]], optional
+    custom_holidays: HolidayType, optional
         Argument where missing holidays can be added as
         {"2021-02-12": "Jack's birthday"} or ["2021-02-12"]
 
@@ -309,7 +281,7 @@ def offset_business_days(
 
     idx = where(array(local_bdays) == ddate)[0]
 
-    return date_fix(local_bdays[idx[0] + days])
+    return cast(dt.date, local_bdays[idx[0] + days])
 
 
 def generate_calender_date_range(
@@ -318,18 +290,19 @@ def generate_calender_date_range(
     end: Optional[dt.date] = None,
     countries: CountriesType = "SE",
 ) -> list[dt.date]:
-    """Generates a list of business day calender dates
-
-        Parameters
-        ----------
-        trading_days: TradingDaysType
-            Number of days to generate
-        start: datetime.date, optional
-            Date when the range starts
-        end: datetime.date, optional
-            Date when the range ends
-        countries: CountriesType, default: "SE"
-            (List of) country code(s) according to ISO 3166-1 alpha-2
+    """
+    Generate a list of business day calender dates.
+
+    Parameters
+    ----------
+    trading_days: TradingDaysType
+        Number of days to generate
+    start: datetime.date, optional
+        Date when the range starts
+    end: datetime.date, optional
+        Date when the range ends
+    countries: CountriesType, default: "SE"
+        (List of) country code(s) according to ISO 3166-1 alpha-2
 
     Returns
     -------
@@ -338,10 +311,14 @@ def generate_calender_date_range(
     """
     if start and not end:
         tmp_range = date_range(
-            start=start, periods=trading_days * 365 // 252, freq="D"
+            start=start,
+            periods=trading_days * 365 // 252,
+            freq="D",
         )
         calendar = holiday_calendar(
-            startyear=start.year, endyear=tmp_range[-1].year, countries=countries
+            startyear=start.year,
+            endyear=tmp_range[-1].year,
+            countries=countries,
         )
         return [
             d.date()
@@ -355,7 +332,9 @@ def generate_calender_date_range(
     if end and not start:
         tmp_range = date_range(end=end, periods=trading_days * 365 // 252, freq="D")
         calendar = holiday_calendar(
-            startyear=tmp_range[0].year, endyear=end.year, countries=countries
+            startyear=tmp_range[0].year,
+            endyear=end.year,
+            countries=countries,
         )
         return [
             d.date()
@@ -368,21 +347,22 @@ def generate_calender_date_range(
 
     raise ValueError(
         "Provide one of start or end date, but not both. "
-        "Date range is inferred from number of trading days."
+        "Date range is inferred from number of trading days.",
     )
 
 
 def align_dataframe_to_local_cdays(
-    data: DataFrame, countries: CountriesType = "SE"
+    data: DataFrame,
+    countries: CountriesType = "SE",
 ) -> DataFrame:
-    """Changes the index of the associated Pandas DataFrame .tsdf to align with
-    local calendar business days
+    """
+    Align the index .tsdf with local calendar business days.
 
     Parameters
     ----------
     data: pandas.DataFrame
         The timeseries data
-    countries: list[str] | str, default: "SE"
+    countries: CountriesType, default: "SE"
         (List of) country code(s) according to ISO 3166-1 alpha-2
 
     Returns
@@ -393,7 +373,9 @@ def align_dataframe_to_local_cdays(
     startyear = data.index[0].year
     endyear = data.index[-1].year
     calendar = holiday_calendar(
-        startyear=startyear, endyear=endyear, countries=countries
+        startyear=startyear,
+        endyear=endyear,
+        countries=countries,
     )
 
     d_range = [
@@ -415,9 +397,10 @@ def do_resample_to_business_period_ends(
     countries: CountriesType,
     convention: LiteralPandasResampleConvention,
 ) -> DatetimeIndex:
-    """Resamples timeseries frequency to the business calendar
-    month end dates of each period while leaving any stubs
-    in place. Stubs will be aligned to the shortest stub
+    """
+    Resample timeseries frequency to business calendar month end dates.
+
+    Stubs left in place. Stubs will be aligned to the shortest stub.
 
     Parameters
     ----------
@@ -440,12 +423,11 @@ def do_resample_to_business_period_ends(
     Pandas.DatetimeIndex
         A date range aligned to business period ends
     """
-
     head = head.to_frame().T
     tail = tail.to_frame().T
     data.index = DatetimeIndex(data.index)
     data = data.resample(rule=freq, convention=convention).last()
-    data.drop(index=data.index[-1], inplace=True)
+    data = data.drop(index=data.index[-1])
     data.index = [d.date() for d in DatetimeIndex(data.index)]
 
     if head.index[0] not in data.index:
@@ -454,7 +436,7 @@ def do_resample_to_business_period_ends(
     if tail.index[0] not in data.index:
         data = concat([data, tail])
 
-    data.sort_index(inplace=True)
+    data = data.sort_index()
 
     dates = DatetimeIndex(
         [data.index[0]]
@@ -470,7 +452,7 @@ def do_resample_to_business_period_ends(
             )
             for d in data.index[1:-1]
         ]
-        + [data.index[-1]]
+        + [data.index[-1]],
     )
     dates = dates.drop_duplicates()
     return dates
@@ -482,7 +464,8 @@ def get_calc_range(
     from_dt: Optional[dt.date] = None,
     to_dt: Optional[dt.date] = None,
 ) -> tuple[dt.date, dt.date]:
-    """Creates user defined date range
+    """
+    Create user defined date range.
 
     Parameters
     ----------