none-shall-parse 0.4.2__tar.gz → 0.4.3__tar.gz

{none_shall_parse-0.4.2 → none_shall_parse-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: none-shall-parse
-Version: 0.4.2
+Version: 0.4.3
 Summary: Trinity Shared Python utilities.
 Author: Andries Niemandt, Jan Badenhorst
 Author-email: Andries Niemandt <andries.niemandt@trintel.co.za>, Jan Badenhorst <jan@trintel.co.za>

{none_shall_parse-0.4.2 → none_shall_parse-0.4.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "none-shall-parse"
-version = "0.4.2"
+version = "0.4.3"
 description = "Trinity Shared Python utilities."
 readme = "README.md"
 authors = [

{none_shall_parse-0.4.2 → none_shall_parse-0.4.3}/src/none_shall_parse/dates.py

@@ -3,8 +3,10 @@ import logging
 import time
 from datetime import date, datetime
 from typing import Callable, Any, Tuple, Sequence, List
+from .types import DateTimeLike
 
 import pendulum
+from pendulum import DateTime, Date
 from pendulum import local_timezone
 from pendulum.tz.exceptions import InvalidTimezone
 
@@ -24,38 +26,38 @@ class DateUtilsError(Exception):
         self.message = message
 
 
-def assert_week_start_date_is_valid(wso):
+def assert_week_start_date_is_valid(wso: int) -> None:
     if wso < 1 or wso > 7:
         raise DateUtilsError("Weeks can only start on days between 1 and 7")
 
 
-def assert_month_start_date_is_valid(mso):
+def assert_month_start_date_is_valid(mso: int) -> None:
     if mso > 28 or mso < 1:
         raise DateUtilsError("Months can only start on days between 1 and 28")
 
 
-def get_datetime_now(naive: bool = False, tz: str | None = None) -> datetime:
+def get_datetime_now(naive: bool = False, tz: str | None = None) -> DateTime:
     """
     Get the current date and time.
 
     This function retrieves the current date and time using the pendulum library. It can
-    return the datetime in either a naive or timezone-aware format, depending on the
+    return the DateTime in either a naive or timezone-aware format, depending on the
     parameters provided.
 
     Args:
-        naive (bool): If True, returns a naive datetime object without timezone information.
+        naive (bool): If True, returns a naive DateTime object without timezone information.
                       Defaults to True.
-        tz (Optional[str]): The timezone to use if a timezone-aware datetime is requested.
+        tz (Optional[str]): The timezone to use if a timezone-aware DateTime is requested.
                             If not provided and naive is False, the default system timezone
                             is used.
 
     Returns:
-        datetime: The current date and time based on the specified parameters.
+        pendulum.DateTime: The current date and time based on the specified parameters.
     """
     return pendulum.now().naive() if naive else pendulum.now(tz=tz)
 
 
-def za_now() -> datetime:
+def za_now() -> DateTime:
     """
     Returns the current date and time in the South African timezone.
 
@@ -64,7 +66,7 @@ def za_now() -> datetime:
     time localization.
 
     Returns:
-        datetime: The current date and time in the South African timezone.
+        pendulum.DateTime: The current date and time in the South African timezone.
     """
     return get_datetime_now(naive=False, tz=ZA_TZ)
 
@@ -95,39 +97,39 @@ def za_ordinal_year_day_tomorrow() -> int:
     return pendulum.now(ZA_TZ).add(days=1).day_of_year
 
 
-def utc_epoch_start() -> datetime:
+def utc_epoch_start() -> DateTime:
     """
-    Gets the UTC epoch start time as a datetime object.
+    Gets the UTC epoch start time as a DateTime object.
 
     This function calculates the start of the UNIX epoch (January 1, 1970)
-    in UTC as a datetime object. It leverages the `pendulum` library for
+    in UTC as a DateTime object. It leverages the `pendulum` library for
     handling the time calculation with the specified UTC timezone.
 
     Returns:
-        datetime: A datetime object representing the start of the UTC epoch.
+        pendulum.DateTime: A pendulum DateTime object representing the start of the UTC epoch.
     """
     return pendulum.from_timestamp(0)
 
 
 def _now_offset_n_units(n: int, units: str, naive: bool = False,
-                        tz: str | None = None) -> datetime:
+                        tz: str | None = None) -> DateTime:
     """
-    Calculate a datetime object offset by a specified number of time units.
+    Calculate a DateTime object offset by a specified number of time units.
 
-    This function allows you to calculate a datetime offset by a given number of units
+    This function allows you to calculate a DateTime offset by a given number of units
     (minutes, hours, days, etc.) from the current time. You can also specify the timezone
-    and whether the returned datetime should be naive or timezone-aware.
+    and whether the returned DateTime should be naive or timezone-aware.
 
     Parameters:
         n (int): The number of units to offset the current time by.
         units (str): The type of time unit to offset by.
-        naive (bool): Whether to return a naive datetime (without timezone information).
+        naive (bool): Whether to return a naive DateTime (without timezone information).
             Defaults to False.
-        tz (Optional[str]): The timezone of the resulting datetime. If not provided,
+        tz (Optional[str]): The timezone of the resulting DateTime. If not provided,
             the system's local timezone is used.
 
     Returns:
-        datetime: The calculated datetime object, optionally timezone-aware or naive.
+        DateTime: The calculated DateTime object, optionally timezone-aware or naive.
     """
     kwargs = {units: n}
     return pendulum.now().add(**kwargs).naive() if naive else pendulum.now(tz).add(
@@ -135,58 +137,58 @@ def _now_offset_n_units(n: int, units: str, naive: bool = False,
 
 
 def now_offset_n_minutes(n: int, naive: bool = False,
-                         tz: str | None = None) -> datetime:
+                         tz: str | None = None) -> DateTime:
     return _now_offset_n_units(n, units="minutes", naive=naive, tz=tz)
 
 
 def now_offset_n_hours(n: int, naive: bool = False,
-                       tz: str | None = None) -> datetime:
+                       tz: str | None = None) -> DateTime:
     return _now_offset_n_units(n, units="hours", naive=naive, tz=tz)
 
 
 def now_offset_n_days(n: int, naive: bool = False,
-                      tz: str | None = None) -> datetime:
+                      tz: str | None = None) -> DateTime:
     return _now_offset_n_units(n, units="days", naive=naive, tz=tz)
 
 
 def get_datetime_tomorrow(naive: bool = False,
-                          tz: str | None = None) -> datetime:
-    """Get tomorrow's datetime"""
+                          tz: str | None = None) -> DateTime:
+    """Get tomorrow's DateTime"""
     return now_offset_n_days(1, naive=naive, tz=tz)
 
 
 def get_datetime_yesterday(naive: bool = False,
-                           tz: str | None = None) -> datetime:
-    """Get yesterday's datetime"""
+                           tz: str | None = None) -> DateTime:
+    """Get yesterday's DateTime"""
     return now_offset_n_days(-1, naive=naive, tz=tz)
 
 
-def get_utc_datetime_offset_n_days(n: int = 0) -> datetime:
-    """Get UTC datetime n with an offset of n days"""
+def get_utc_datetime_offset_n_days(n: int = 0) -> DateTime:
+    """Get UTC DateTime n with an offset of n days"""
     return pendulum.now(UTC_TZ).add(days=n)
 
 
 def epoch_to_datetime(epoch_int: int | float, naive: bool = False,
-                      tz: str | None = None) -> datetime:
+                      tz: str | None = None) -> DateTime:
     """
-    Converts an epoch timestamp to a datetime object.
+    Converts an epoch timestamp to a DateTime object.
 
     This function takes an input epoch timestamp and converts it into a
-    datetime object using the Pendulum library. It supports conversion
-    to either naive or timezone-aware datetime objects based on the
+    DateTime object using the Pendulum library. It supports conversion
+    to either naive or timezone-aware DateTime objects based on the
     parameters provided.
 
     Parameters:
-        epoch_int (int | float): The epoch timestamp to convert to a datetime
+        epoch_int (int | float): The epoch timestamp to convert to a DateTime
             object. It can be provided as an integer or float value.
-        naive (bool): If True, the resulting datetime object will be naive
+        naive (bool): If True, the resulting DateTime object will be naive
             (without timezone information). Defaults to False.
-        tz (Optional[str]): The timezone in which the resulting datetime object
+        tz (Optional[str]): The timezone in which the resulting DateTime object
             should be created. If not provided, the system's default timezone
             will be used.
 
     Returns:
-        datetime: A datetime object representing the converted epoch timestamp.
+        DateTime: A DateTime object representing the converted epoch timestamp.
     """
 
     # We force the timezone to the user's local timezone if none was supplied
@@ -200,18 +202,18 @@ def epoch_to_datetime(epoch_int: int | float, naive: bool = False,
     return pendulum.from_timestamp(int(epoch_int), tz=tz)
 
 
-def epoch_to_utc_datetime(epoch_int: int | float | str) -> datetime:
+def epoch_to_utc_datetime(epoch_int: int | float | str) -> DateTime:
     """
-    Converts an epoch timestamp to a UTC datetime object.
+    Converts an epoch timestamp to a UTC DateTime object.
 
     This function takes an integer or float representing an epoch timestamp,
-    and converts it to a datetime object in UTC timezone using Pendulum.
+    and converts it to a DateTime object in UTC timezone using Pendulum.
 
     Parameters:
         epoch_int: An epoch timestamp represented as an integer or float.
 
     Returns:
-        A datetime object in UTC corresponding to the provided epoch timestamp.
+        A DateTime object in UTC corresponding to the provided epoch timestamp.
     """
     return pendulum.from_timestamp(int(epoch_int), tz=UTC_TZ)
 
@@ -223,7 +225,7 @@ def is_office_hours_in_timezone(epoch_int: int | float | str, tz: str | None = N
 
     Office hours are considered to be between 08:00 and 17:00 (8 AM to 5 PM) in
     the specified timezone. The function converts the provided epoch timestamp into
-    a datetime object according to the given timezone and checks whether the time falls
+    a DateTime object according to the given timezone and checks whether the time falls
     within the defined office hours.
 
     Parameters:
@@ -248,7 +250,7 @@ def is_office_hours_in_timezone(epoch_int: int | float | str, tz: str | None = N
 
 
 def get_datetime_from_ordinal_and_sentinel(
-        sentinel: datetime | None = None) -> Callable[[int], datetime]:
+        sentinel: DateTimeLike | None = None) -> Callable[[int], DateTime]:
     """
     Given an ordinal year day, and a sentinel datetime, get the closest past
     datetime to the sentinel that had the given ordinal year day.
@@ -258,19 +260,20 @@ def get_datetime_from_ordinal_and_sentinel(
     """
     # Check timezone awareness
     naive = sentinel.tzinfo is None
-
-    sentinel_pdt = pendulum.instance(sentinel)
-    sentinel_doy = sentinel_pdt.day_of_year
-    sentinel_year = sentinel_pdt.year
+    sentinel = pendulum.instance(sentinel)
+    if naive:
+        sentinel = sentinel.naive()
+    sentinel_doy = sentinel.day_of_year
+    sentinel_year = sentinel.year
 
     if naive:
         this_year = pendulum.naive(sentinel_year, 1, 1)
         last_year = pendulum.naive(sentinel_year - 1, 1, 1)
     else:
-        this_year = pendulum.datetime(sentinel_year, 1, 1, tz=sentinel_pdt.timezone)
-        last_year = pendulum.datetime(sentinel_year - 1, 1, 1, tz=sentinel_pdt.timezone)
+        this_year = pendulum.datetime(sentinel_year, 1, 1, tz=sentinel.timezone)
+        last_year = pendulum.datetime(sentinel_year - 1, 1, 1, tz=sentinel.timezone)
 
-    def f(ordinal: int) -> datetime:
+    def f(ordinal: int) -> DateTime:
         dt = this_year if ordinal <= sentinel_doy else last_year
 
         # Handle leap year edge case
@@ -278,7 +281,7 @@ def get_datetime_from_ordinal_and_sentinel(
             if naive:
                 return pendulum.naive(1970, 1, 1)
             else:
-                return pendulum.datetime(1970, 1, 1, tz=sentinel_pdt.timezone)
+                return pendulum.datetime(1970, 1, 1, tz=sentinel.timezone)
 
         result = dt.add(days=ordinal - 1)
         return result
@@ -287,7 +290,7 @@ def get_datetime_from_ordinal_and_sentinel(
 
 
 # ------------------------------------------------------------------[ Span Functions ]--
-def day_span(pts: datetime) -> Tuple[datetime, datetime]:
+def day_span(pts: DateTimeLike) -> Tuple[DateTime, DateTime]:
     """
     Returns the beginning and end of the day passed in.
     begin is inclusive and end is exclusive.
@@ -300,13 +303,11 @@ def day_span(pts: datetime) -> Tuple[datetime, datetime]:
         dt = datetime(2023, 12, 25, 14, 30, 45)
 
         start, end = day_span(dt)
-        print(type(start)) # <class 'datetime.datetime'>
+        print(type(start)) # <class 'DateTime.DateTime'>
 
     """
     # Check if input is naive or aware
     naive = pts.tzinfo is None
-
-    # Convert to Pendulum for easier manipulation
     pdt = pendulum.instance(pts)
 
     # Use Pendulum's clean API
@@ -319,7 +320,7 @@ def day_span(pts: datetime) -> Tuple[datetime, datetime]:
         return begin, end
 
 
-def week_span(wso: int) -> Callable[[datetime], Tuple[datetime, datetime]]:
+def week_span(wso: int) -> Callable[[DateTimeLike], Tuple[DateTime, DateTime]]:
     """
     Given an integer between 1 and 7, return a function that will give the
     start and end dates of the week.
@@ -339,7 +340,7 @@ def week_span(wso: int) -> Callable[[datetime], Tuple[datetime, datetime]]:
     """
     assert_week_start_date_is_valid(wso)
 
-    def find_dates(pts: datetime) -> Tuple[datetime, datetime]:
+    def find_dates(pts: DateTimeLike) -> Tuple[DateTime, DateTime]:
         # Check if input is naive or aware
         naive = pts.tzinfo is None
         pdt = pendulum.instance(pts)
@@ -359,7 +360,7 @@ def week_span(wso: int) -> Callable[[datetime], Tuple[datetime, datetime]]:
     return find_dates
 
 
-def month_span(mso: int) -> Callable[[datetime], Tuple[datetime, datetime]]:
+def month_span(mso: int) -> Callable[[DateTimeLike], Tuple[DateTime, DateTime]]:
     """
     Given an integer between 1 and 28, return a function that will give the
     start and end dates of the custom month period.
@@ -379,7 +380,7 @@ def month_span(mso: int) -> Callable[[datetime], Tuple[datetime, datetime]]:
     """
     assert_month_start_date_is_valid(mso)
 
-    def find_dates(pts: datetime) -> Tuple[datetime, datetime]:
+    def find_dates(pts: DateTimeLike) -> Tuple[DateTime, DateTime]:
         # Convert to Pendulum
         naive = pts.tzinfo is None
         pdt = pendulum.instance(pts)
@@ -403,22 +404,22 @@ def month_span(mso: int) -> Callable[[datetime], Tuple[datetime, datetime]]:
     return find_dates
 
 
-def arb_span(dates: Sequence[str | datetime], naive: bool = False) -> Callable[
-    [Any], Tuple[datetime, datetime]]:
+def arb_span(dates: Sequence[str | DateTimeLike], naive: bool = False) -> Callable[
+    [Any], Tuple[DateTime, DateTime]]:
     """
     Parses two given dates and returns a callable function that provides the date range
     as a tuple of datetime objects. The function ensures the date range is valid and
     always returns the earlier date as the start and the later date as the end.
 
     Parameters:
-        dates (Sequence[str | datetime]): A sequence containing exactly two dates where
+        dates (Sequence[str | DateTimeLike]): A sequence containing exactly two dates where
             each date is either a string or a datetime object.
         naive (bool): Optional flag. If True, the returned datetime objects will not
             have timezone information (naive datetime). Defaults to False.
 
     Returns:
-        Callable[[Any], Tuple[datetime, datetime]]: A function that, when invoked,
-        returns a tuple of datetime objects (start, end) representing the date range.
+        Callable[[Any], Tuple[DateTime, DateTime]]: A function that, when invoked,
+        returns a tuple of DateTime objects (start, end) representing the date range.
 
     Raises:
         DateUtilsError: If the provided dates are invalid, identical, or there's an error
@@ -466,9 +467,9 @@ def arb_span(dates: Sequence[str | datetime], naive: bool = False) -> Callable[
     except Exception as ex:
         raise DateUtilsError(f"Error parsing dates: {ex}")
 
-    def find_dates(*args) -> Tuple[datetime, datetime]:
+    def find_dates(*args) -> Tuple[DateTime, DateTime]:
         """
-        :return: tuple of datetime objects (start, end)
+        :return: tuple of DateTime objects (start, end)
         """
         if naive:
             return begin.naive(), end.naive()
@@ -478,9 +479,9 @@ def arb_span(dates: Sequence[str | datetime], naive: bool = False) -> Callable[
 
 
 def unroll_span_func(
-        f: Callable[[datetime], Tuple[datetime, datetime]],
-        cover: datetime | None = None,
-) -> Tuple[List[datetime], List[int], List[str], datetime, datetime]:
+        f: Callable[[DateTimeLike], Tuple[DateTime, DateTime]],
+        cover: DateTimeLike | None = None,
+) -> Tuple[List[DateTime], List[int], List[str], DateTime, DateTime]:
     """
     Generate keys for a date range based on a provided function.
 
@@ -490,14 +491,14 @@ def unroll_span_func(
 
     Args:
         f: Function that takes a base date and returns a tuple of start and end dates.
-        cover: Base date for computing the range. Defaults to the current date if None.
+        cover: Base datetime for computing the range. Defaults to the current date if None.
 
     Returns:
         A tuple containing:
-        - List of datetime objects.
+        - List of DateTime objects.
         - List of ordinal day integers.
-        - Start date of the range (as datetime).
-        - End date of the range (as datetime).
+        - Start date of the range (as DateTime).
+        - End date of the range (as DateTime).
         If ord_ints_only is True, returns (ordinal_days, start, end, iso_dates).
 
     Raises:
@@ -507,15 +508,13 @@ def unroll_span_func(
     naive = cover.tzinfo is None
     try:
         start, end = f(cover)
+        start = pendulum.instance(start)
+        start = start.naive() if naive else start
+        end = pendulum.instance(end)
+        end = end.naive() if naive else end
     except Exception as e:
         raise DateUtilsError(f"Function f failed to compute date range: {str(e)}")
 
-    # Make sure we can use pendulum with these dates
-    start = pendulum.instance(start) if isinstance(start, datetime) else start
-    start = start.naive() if naive else start
-    end = pendulum.instance(end) if isinstance(end, datetime) else end
-    end = end.naive() if naive else end
-
     try:
         # Generate date range using pendulum.interval
         # The absolute kwarg ensures that we do not have to care about dates passed
@@ -536,8 +535,8 @@ def unroll_span_func(
 
 
 def keys_for_span_func(
-        f: Callable[[datetime], Tuple[datetime, datetime]],
-        cover: datetime | None = None,
+        f: Callable[[DateTimeLike], Tuple[DateTime, DateTime]],
+        cover: DateTimeLike | None = None,
         key_in_format: str = "ODIN_{}",
         key_out_format: str = "ODOUT_{}",
 ):
@@ -553,8 +552,8 @@ def keys_for_span_func(
     Returns:
         - List of input keys (empty if key_in_format is None).
         - List of output keys (empty if key_out_format is None).
-        - Start date of the range (as datetime).
-        - End date of the range (as datetime).
+        - Start date of the range (as DateTime).
+        - End date of the range (as DateTime).
 
     Raises:
         DateUtilsError: If the date range cannot be processed.
@@ -565,8 +564,8 @@ def keys_for_span_func(
     return keys_in, keys_out, start, end
 
 
-def calendar_month_start_end(date_in_month: datetime | None = None) -> Tuple[
-    datetime, datetime]:
+def calendar_month_start_end(date_in_month: DateTimeLike | None = None) -> Tuple[
+    DateTime, DateTime]:
     naive = date_in_month.tzinfo is None
 
     if date_in_month is None:
@@ -593,7 +592,7 @@ def unix_timestamp() -> int:
     return round(time.time())
 
 
-def sentinel_date_and_ordinal_to_date(sentinel_date: datetime | date,
+def sentinel_date_and_ordinal_to_date(sentinel_date: DateTimeLike | date,
                                       ordinal: int | float | str) -> date:
     """Convert sentinel date and ordinal day to actual date"""
     year = sentinel_date.year
@@ -620,13 +619,13 @@ def standard_tz_timestring(ts: int | float, tz: str = ZA_TZ) -> str:
     Format timestamp as: 2022-02-22 15:28:10 (SAST)
     :param ts: Seconds since epoch
     :param tz: Timezone string
-    :return: Formatted datetime string
+    :return: Formatted date time string
     """
     dt = pendulum.from_timestamp(int(ts), tz=tz)
     return dt.strftime("%Y-%m-%d %H:%M:%S (%Z)")
 
 
-def get_notice_end_date(given_date: datetime | date | None = None) -> date:
+def get_notice_end_date(given_date: DateTimeLike | date | Date | None = None) -> Date:
     """
     A notice end date is the end of the month of the given date if the given date
     is before or on the 15th. If the given date is after the 15th, the notice period
@@ -650,11 +649,13 @@ def get_notice_end_date(given_date: datetime | date | None = None) -> date:
         # End of next month
         end_date = pdt.add(months=2).start_of('month')
 
+    if isinstance(end_date, DateTime):
+        return end_date.date()
     return end_date
 
 
-def dt_to_za_time_string(v: datetime) -> str:
-    """Convert datetime to South Africa time string"""
+def dt_to_za_time_string(v: DateTimeLike) -> str:
+    """Convert DateTime to South Africa time string"""
     # Convert to Pendulum
     naive = v.tzinfo is None
     if naive:
@@ -674,24 +675,24 @@ def months_ago_selection() -> List[Tuple[int, str]]:
     ]
 
 
-def is_aware(dt: datetime) -> bool:
-    """Check if a datetime object is timezone-aware."""
+def is_aware(dt: DateTimeLike | Date | date) -> bool:
+    """Check if a DateTime object is timezone-aware."""
     return dt.tzinfo is not None and dt.tzinfo.utcoffset(dt) is not None
 
 
-def make_aware(dt: datetime | None, tz: str = None) -> datetime | None:
+def make_aware(dt: DateTimeLike | date | Date | None, tz: str = None) -> DateTime | Date | None:
     """
-    Convert a naive datetime to a timezone-aware datetime using Pendulum.
+    Convert a naive DateTime to a timezone-aware DateTime using Pendulum.
 
     Args:
-        dt: The datetime object to convert. If None, returns None.
+        dt: The DateTime object to convert. If None, returns None.
         tz: The timezone to apply (default: The user's default timezone).).
 
     Returns:
-        A timezone-aware datetime object.
+        A timezone-aware DateTime object.
 
     Raises:
-        TypeError: If dt is not a datetime object or None.
+        TypeError: If dt is not a DateTime object or None.
         ValueError: If dt is already timezone-aware.
         DateUtilsError: If the timezone string is invalid.
     """
@@ -714,8 +715,8 @@ def make_aware(dt: datetime | None, tz: str = None) -> datetime | None:
         raise DateUtilsError(f"Invalid timezone: {tz}") from e
 
 
-def unaware_to_utc_aware(dt: datetime | None) -> datetime | None:
-    """Convert naive datetime to UTC-aware datetime using Pendulum."""
+def unaware_to_utc_aware(dt: DateTimeLike | date | Date | None) -> DateTime | Date | None:
+    """Convert naive DateTime to UTC-aware DateTime using Pendulum."""
     if not isinstance(dt, (datetime, type(None))):
         raise TypeError(f"Expected datetime or None, got {type(dt)}")
 

{none_shall_parse-0.4.2 → none_shall_parse-0.4.3}/src/none_shall_parse/types.py

@@ -1,5 +1,8 @@
+from datetime import datetime, date
 from typing import Protocol, Sequence, Tuple, Union, TypeVar
 
+from pendulum import DateTime, Date
+
 
 class StringLike(Protocol):
     """
@@ -29,4 +32,10 @@ class StringLike(Protocol):
 
 ChoicesType = Sequence[Tuple[Union[int, str], StringLike]]
 
+DateLike = Union[Date, date]
+
+DateTimeLike = Union[DateTime, datetime]
+
+DateTimeOrDateLike = Union[DateTimeLike, DateLike]
+
 T = TypeVar("T")