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

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

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

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

none_shall_parse-0.4.2/src/none_shall_parse/__init__.py

@@ -0,0 +1,133 @@
+"""Trinity Shared Python utilities.
+
+A collection of shared utilities for Trinity projects.
+
+Originally intended to be parsing utilities, this grew to include
+other useful functions.
+
+Named for its author Andries Niemandt - whose surname loosely
+translates to "none". Combined this with our parsing intentions
+to create a name which nods to the Black Knight in Monty Python's Holy Grail.
+https://www.youtube.com/watch?v=zKhEw7nD9C4
+"""
+from __future__ import annotations
+from .dates import (
+    DateUtilsError, assert_week_start_date_is_valid,
+    assert_month_start_date_is_valid,
+    get_datetime_now, za_now,
+    za_ordinal_year_day_now,
+    za_ordinal_year_day_tomorrow, utc_epoch_start,
+    now_offset_n_minutes, now_offset_n_hours,
+    now_offset_n_days, get_datetime_tomorrow,
+    get_datetime_yesterday,
+    get_utc_datetime_offset_n_days,
+    epoch_to_datetime, epoch_to_utc_datetime,
+    is_office_hours_in_timezone,
+    get_datetime_from_ordinal_and_sentinel,
+    day_span, week_span, month_span, arb_span,
+    calendar_month_start_end, unix_timestamp,
+    sentinel_date_and_ordinal_to_date,
+    seconds_to_end_of_month, standard_tz_timestring,
+    get_notice_end_date, dt_to_za_time_string,
+    months_ago_selection, is_aware, make_aware,
+    unaware_to_utc_aware, timer_decorator, ZA_TZ,
+    UTC_TZ, keys_for_span_func,
+)
+from .imeis import (
+    get_luhn_digit,
+    is_valid_luhn,
+    is_valid_imei,
+    normalize_imei,
+    get_tac_from_imei,
+    decrement_imei,
+    increment_imei,
+)
+
+from .lists import (
+    flatten,
+    safe_list_get,
+)
+from .parse import (
+    str_to_bool,
+    is_true,
+    is_false,
+    str_to_strs_list,
+    int_to_bool,
+    int_or_none,
+    choices_code_to_string,
+    choices_string_to_code,
+    none_or_empty,
+)
+from .strings import (
+    slugify,
+    random_16,
+    to_human_string,
+    is_quoted_string,
+    is_numeric_string,
+    custom_slug,
+    b64_encode,
+    b64_decode,
+    calc_hash,
+    generate_random_password,
+)
+from .types import (
+    StringLike,
+    ChoicesType
+)
+
+__author__ = "Andries Niemandt, Jan Badenhorst"
+__email__ = "andries.niemandt@trintel.co.za, jan@trintel.co.za"
+__license__ = "MIT"
+
+__all__ = (
+    "DateUtilsError", "assert_week_start_date_is_valid",
+    "assert_month_start_date_is_valid",
+    "get_datetime_now", "za_now",
+    "za_ordinal_year_day_now",
+    "za_ordinal_year_day_tomorrow", "utc_epoch_start",
+    "now_offset_n_minutes", "now_offset_n_hours",
+    "now_offset_n_days", "get_datetime_tomorrow",
+    "get_datetime_yesterday",
+    "get_utc_datetime_offset_n_days",
+    "epoch_to_datetime", "epoch_to_utc_datetime",
+    "is_office_hours_in_timezone",
+    "get_datetime_from_ordinal_and_sentinel",
+    "day_span", "week_span", "month_span", "arb_span",
+    "calendar_month_start_end", "unix_timestamp",
+    "sentinel_date_and_ordinal_to_date",
+    "seconds_to_end_of_month", "standard_tz_timestring",
+    "get_notice_end_date", "dt_to_za_time_string",
+    "months_ago_selection", "is_aware", "make_aware",
+    "unaware_to_utc_aware", "timer_decorator", "ZA_TZ",
+    "UTC_TZ", "keys_for_span_func",
+    "get_luhn_digit",
+    "is_valid_luhn",
+    "is_valid_imei",
+    "normalize_imei",
+    "get_tac_from_imei",
+    "decrement_imei",
+    "increment_imei",
+    "flatten",
+    "safe_list_get",
+    "str_to_bool",
+    "is_true",
+    "is_false",
+    "str_to_strs_list",
+    "int_to_bool",
+    "int_or_none",
+    "choices_code_to_string",
+    "choices_string_to_code",
+    "none_or_empty",
+    "slugify",
+    "random_16",
+    "to_human_string",
+    "is_quoted_string",
+    "is_numeric_string",
+    "custom_slug",
+    "b64_encode",
+    "b64_decode",
+    "calc_hash",
+    "generate_random_password",
+    "StringLike",
+    "ChoicesType"
+)

{none_shall_parse-0.4.0 → none_shall_parse-0.4.2}/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)

{none_shall_parse-0.4.0 → none_shall_parse-0.4.2}/src/none_shall_parse/imeis.py

@@ -1,9 +1,8 @@
-from typing import Union
 
 LUHN_DOUBLES = [0, 2, 4, 6, 8, 1, 3, 5, 7, 9]
 
 
-def get_luhn_digit(n: Union[str, int]) -> int:
+def get_luhn_digit(n: str | int) -> int:
     """
     Calculates the Luhn checksum digit for a given number.
 
@@ -26,7 +25,7 @@ def get_luhn_digit(n: Union[str, int]) -> int:
     return divmod(check, 10)[1]
 
 
-def is_valid_luhn(n: Union[str, int]) -> bool:
+def is_valid_luhn(n: str | int) -> bool:
     """
     Determines if a given number, represented as a string or integer, adheres
     to the Luhn algorithm.
@@ -78,7 +77,7 @@ def is_valid_luhn(n: Union[str, int]) -> bool:
     return divmod(final, 10)[1] == 0
 
 
-def is_valid_imei(n: Union[str, int]) -> bool:
+def is_valid_imei(n: str | int) -> bool:
     """
     Determines whether the given number is a valid IMEI (International Mobile
     Equipment Identity) number.
@@ -98,7 +97,7 @@ def is_valid_imei(n: Union[str, int]) -> bool:
     return len(str(n)) == 15 and is_valid_luhn(n)
 
 
-def normalize_imei(c: Union[str, int]) -> str:
+def normalize_imei(c: str | int) -> str:
     """
     Normalizes the given IMEI number by extracting the first 14 digits and appending
     the calculated Luhn check digit to make it a valid IMEI.
@@ -131,7 +130,7 @@ def normalize_imei(c: Union[str, int]) -> str:
     return "%s%s" % (t, check_digit)
 
 
-def get_tac_from_imei(n: Union[str, int]) -> tuple[bool, str]:
+def get_tac_from_imei(n: str | int) -> tuple[bool, str]:
     """
     Determines the validity of an IMEI number and extracts its TAC if valid.
 
@@ -156,7 +155,7 @@ def get_tac_from_imei(n: Union[str, int]) -> tuple[bool, str]:
         return True, tac
 
 
-def decrement_imei(n: Union[str, int]) -> tuple[bool, str]:
+def decrement_imei(n: str | int) -> tuple[bool, str]:
     """
     Decrements the given IMEI number by one and normalizes it.
 
@@ -184,7 +183,7 @@ def decrement_imei(n: Union[str, int]) -> tuple[bool, str]:
         return True, result
 
 
-def increment_imei(n: Union[str, int]) -> tuple[bool, str]:
+def increment_imei(n: str | int) -> tuple[bool, str]:
     """
     Determines if a given IMEI number is valid and increments it by 1 if valid.
 

none_shall_parse-0.4.0/src/none_shall_parse/__init__.py

@@ -1,15 +0,0 @@
-"""Trinity Shared Python utilities.
-
-A collection of shared utilities for Trinity projects.
-
-Originally intended to be parsing utilities, this grew to include
-other useful functions.
-
-Named for its author Andries Niemandt - whose surname loosely
-translates to "none". Combined this with our parsing intentions
-to create a name which nods to the Black Knight in Monty Python's Holy Grail.
-https://www.youtube.com/watch?v=zKhEw7nD9C4
-"""
-
-__author__ = "Andries Niemandt, Jan Badenhorst"
-__email__ = "andries.niemandt@trintel.co.za, jan@trintel.co.za"