none-shall-parse 0.4.0__tar.gz → 0.4.1__tar.gz

{none_shall_parse-0.4.0 → none_shall_parse-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: none-shall-parse
-Version: 0.4.0
+Version: 0.4.1
 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.0 → none_shall_parse-0.4.1}/pyproject.toml

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

{none_shall_parse-0.4.0 → none_shall_parse-0.4.1}/src/none_shall_parse/dates.py

@@ -200,7 +200,7 @@ 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) -> datetime:
+def epoch_to_utc_datetime(epoch_int: int | float | str) -> datetime:
     """
     Converts an epoch timestamp to a UTC datetime object.
 
@@ -216,7 +216,7 @@ def epoch_to_utc_datetime(epoch_int: int | float) -> datetime:
     return pendulum.from_timestamp(int(epoch_int), tz=UTC_TZ)
 
 
-def is_office_hours_in_timezone(epoch_int: int | float, tz: str | None = None) -> bool:
+def is_office_hours_in_timezone(epoch_int: int | float | str, tz: str | None = None) -> bool:
     """
     Determines if a given epoch timestamp falls within office hours for a
     specific timezone.
@@ -259,23 +259,18 @@ def get_datetime_from_ordinal_and_sentinel(
     # Check timezone awareness
     naive = sentinel.tzinfo is None
 
-    # Convert to Pendulum for easier manipulation
     sentinel_pdt = pendulum.instance(sentinel)
     sentinel_doy = sentinel_pdt.day_of_year
     sentinel_year = sentinel_pdt.year
 
-    # Create start of years with CORRECT timezone handling
     if naive:
-        # Use pendulum.naive() to create naive datetimes
         this_year = pendulum.naive(sentinel_year, 1, 1)
         last_year = pendulum.naive(sentinel_year - 1, 1, 1)
     else:
-        # Create in the same timezone as sentinel (not UTC!)
         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)
 
     def f(ordinal: int) -> datetime:
-        # Choose year based on whether ordinal is before or after sentinel's day of year
         dt = this_year if ordinal <= sentinel_doy else last_year
 
         # Handle leap year edge case
@@ -285,10 +280,7 @@ def get_datetime_from_ordinal_and_sentinel(
             else:
                 return pendulum.datetime(1970, 1, 1, tz=sentinel_pdt.timezone)
 
-        # Add (ordinal - 1) days to start of year
         result = dt.add(days=ordinal - 1)
-
-        # Return as-is (Pendulum datetime preserves timezone awareness)
         return result
 
     return f
@@ -412,26 +404,25 @@ def month_span(mso: int) -> Callable[[datetime], Tuple[datetime, datetime]]:
 
 
 def arb_span(dates: Sequence[str | datetime], naive: bool = False) -> Callable[
-    [], Tuple[datetime, datetime]]:
+    [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 each
-                                          date is either a string or a datetime object.
+        dates (Sequence[str | datetime]): 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.
+            have timezone information (naive datetime). Defaults to False.
 
     Returns:
-        Callable[[], 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
-                        during parsing.
+       during parsing.
     """
     try:
         parsed_dates = []
@@ -475,7 +466,7 @@ 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() -> Tuple[datetime, datetime]:
+    def find_dates(*args) -> Tuple[datetime, datetime]:
         """
         :return: tuple of datetime objects (start, end)
         """
@@ -486,6 +477,94 @@ def arb_span(dates: Sequence[str | datetime], naive: bool = False) -> Callable[
     return find_dates
 
 
+def unroll_span_func(
+        f: Callable[[datetime], Tuple[datetime, datetime]],
+        cover: datetime | None = None,
+) -> Tuple[List[datetime], List[int], List[str], datetime, datetime]:
+    """
+    Generate keys for a date range based on a provided function.
+
+    This function computes a date range using the provided function `f`, which takes a base date and returns
+    start and end dates. It generates input and output keys for each day in the range based on ordinal days
+    and optionally returns only ordinal day integers.
+
+    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.
+
+    Returns:
+        A tuple containing:
+        - List of datetime objects.
+        - List of ordinal day integers.
+        - 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:
+        DateUtilsError: If the date range cannot be processed due to invalid dates or formatting.
+    """
+    cover = pendulum.now() if cover is None else cover
+    naive = cover.tzinfo is None
+    try:
+        start, end = f(cover)
+    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
+        # in the wrong order. We will always range from start to end, inclusive.
+        interval = pendulum.interval(start, end.subtract(days=1), absolute=True)
+        date_range = []
+        ord_days = []
+        iso_date_strings = []
+        for dt in interval.range(unit="days"):
+            date_range.append(dt)
+            ord_days.append(dt.day_of_year)
+            iso_date_strings.append(dt.format('YYYY-MM-DD'))
+
+        return date_range, ord_days, iso_date_strings, start, end
+
+    except (TypeError, ValueError) as e:
+        raise DateUtilsError(f"Error processing date range: {str(e)}")
+
+
+def keys_for_span_func(
+        f: Callable[[datetime], Tuple[datetime, datetime]],
+        cover: datetime | None = None,
+        key_in_format: str = "ODIN_{}",
+        key_out_format: str = "ODOUT_{}",
+):
+    """
+    Generate keys for a date range based on a provided function.
+
+    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.
+        key_in_format: Format string for input keys. Defaults to "ODIN_{}".
+        key_out_format: Format string for output keys, Defaults to "ODOUT_{}"
+
+    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).
+
+    Raises:
+        DateUtilsError: If the date range cannot be processed.
+    """
+    date_range, ord_days, iso_date_strings, start, end = unroll_span_func(f=f, cover=cover)
+    keys_in = [key_in_format.format(d) for d in ord_days]
+    keys_out = [key_out_format.format(d) for d in ord_days]
+    return keys_in, keys_out, start, end
+
+
 def calendar_month_start_end(date_in_month: datetime | None = None) -> Tuple[
     datetime, datetime]:
     naive = date_in_month.tzinfo is None
@@ -495,7 +574,6 @@ def calendar_month_start_end(date_in_month: datetime | None = None) -> Tuple[
 
     pdt = pendulum.instance(date_in_month)
 
-    # One-liner for both values
     start = pdt.start_of('month')
     end = start.add(months=1)
 
@@ -515,8 +593,8 @@ def unix_timestamp() -> int:
     return round(time.time())
 
 
-def sentinel_date_and_ordinal_to_date(sentinel_date: datetime,
-                                      ordinal: int | float) -> date:
+def sentinel_date_and_ordinal_to_date(sentinel_date: datetime | date,
+                                      ordinal: int | float | str) -> date:
     """Convert sentinel date and ordinal day to actual date"""
     year = sentinel_date.year
     int_ordinal = int(ordinal)