none-shall-parse 0.6.1__tar.gz → 0.6.3__tar.gz

{none_shall_parse-0.6.1 → none_shall_parse-0.6.3}/PKG-INFO

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

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

{none_shall_parse-0.6.1 → none_shall_parse-0.6.3}/src/none_shall_parse/__init__.py

@@ -10,28 +10,48 @@ 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,
+    DateUtilsError,
+    assert_week_start_date_is_valid,
     assert_month_start_date_is_valid,
-    get_datetime_now, za_now, utc_now,
+    get_datetime_now,
+    za_now,
+    utc_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, now_offset_n_months, get_datetime_tomorrow,
+    za_ordinal_year_day_tomorrow,
+    utc_epoch_start,
+    now_offset_n_minutes,
+    now_offset_n_hours,
+    now_offset_n_days,
+    now_offset_n_months,
+    get_datetime_tomorrow,
     get_datetime_yesterday,
     get_utc_datetime_offset_n_days,
-    epoch_to_datetime, epoch_to_utc_datetime,
+    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,
+    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,
+    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,
@@ -83,26 +103,45 @@ __email__ = "andries.niemandt@trintel.co.za, jan@trintel.co.za"
 __license__ = "MIT"
 
 __all__ = (
-    "DateUtilsError", "assert_week_start_date_is_valid",
+    "DateUtilsError",
+    "assert_week_start_date_is_valid",
     "assert_month_start_date_is_valid",
-    "get_datetime_now", "za_now", "utc_now",
+    "get_datetime_now",
+    "za_now",
+    "utc_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", "now_offset_n_months", "get_datetime_tomorrow",
+    "za_ordinal_year_day_tomorrow",
+    "utc_epoch_start",
+    "now_offset_n_minutes",
+    "now_offset_n_hours",
+    "now_offset_n_days",
+    "now_offset_n_months",
+    "get_datetime_tomorrow",
     "get_datetime_yesterday",
     "get_utc_datetime_offset_n_days",
-    "epoch_to_datetime", "epoch_to_utc_datetime",
+    "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",
+    "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",
+    "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",
@@ -136,4 +175,4 @@ __all__ = (
     "DateTimeLike",
     "DateLike",
     "DateTimeOrDateLike",
-)
+)

{none_shall_parse-0.6.1 → none_shall_parse-0.6.3}/src/none_shall_parse/dates.py

@@ -10,8 +10,8 @@ from pendulum import DateTime, Date
 from pendulum import local_timezone
 from pendulum.tz.exceptions import InvalidTimezone
 
-ZA_TZ = 'Africa/Johannesburg'
-UTC_TZ = 'UTC'
+ZA_TZ = "Africa/Johannesburg"
+UTC_TZ = "UTC"
 
 
 class DateUtilsError(Exception):
@@ -48,13 +48,17 @@ def get_datetime_now(naive: bool = False, tz: str | None = None) -> DateTime:
         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.
-                            If not provided and naive is False, the default system timezone
-                            is used.
+                            If not provided and naive is False, defaults to ZA_TZ.
 
     Returns:
         pendulum.DateTime: The current date and time based on the specified parameters.
     """
-    return pendulum.now().naive() if naive else pendulum.now(tz=tz)
+    if naive:
+        return pendulum.now().naive()
+    else:
+        # Default to ZA_TZ if no timezone is specified for aware datetime
+        timezone = tz if tz is not None else ZA_TZ
+        return pendulum.now(tz=timezone)
 
 
 def za_now() -> DateTime:
@@ -120,8 +124,9 @@ def utc_epoch_start() -> DateTime:
     return pendulum.from_timestamp(0)
 
 
-def _now_offset_n_units(n: int, units: str, naive: bool = False,
-                        tz: str | None = None) -> DateTime:
+def _now_offset_n_units(
+    n: int, units: str, naive: bool = False, tz: str | None = None
+) -> DateTime:
     """
     Calculate a DateTime object offset by a specified number of time units.
 
@@ -141,22 +146,24 @@ def _now_offset_n_units(n: int, units: str, naive: bool = False,
         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(
-        **kwargs)
+    return (
+        pendulum.now().add(**kwargs).naive()
+        if naive
+        else pendulum.now(tz).add(**kwargs)
+    )
 
 
-def now_offset_n_minutes(n: int, naive: bool = False,
-                         tz: str | None = None) -> DateTime:
+def now_offset_n_minutes(
+    n: int, naive: bool = False, 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:
+def now_offset_n_hours(n: int, naive: bool = False, 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:
+def now_offset_n_days(n: int, naive: bool = False, tz: str | None = None) -> DateTime:
     return _now_offset_n_units(n, units="days", naive=naive, tz=tz)
 
 
@@ -164,14 +171,12 @@ def now_offset_n_months(n: int, naive: bool = False, tz: str | None = None) -> D
     return _now_offset_n_units(n, units="months", naive=naive, tz=tz)
 
 
-def get_datetime_tomorrow(naive: bool = False,
-                          tz: str | None = None) -> DateTime:
+def get_datetime_tomorrow(naive: bool = False, 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:
+def get_datetime_yesterday(naive: bool = False, tz: str | None = None) -> DateTime:
     """Get yesterday's DateTime"""
     return now_offset_n_days(-1, naive=naive, tz=tz)
 
@@ -181,8 +186,9 @@ def get_utc_datetime_offset_n_days(n: int = 0) -> DateTime:
     return pendulum.now(UTC_TZ).add(days=n)
 
 
-def epoch_to_datetime(epoch_int: int | float, naive: bool = False,
-                      tz: str | None = None) -> DateTime:
+def epoch_to_datetime(
+    epoch_int: int | float, naive: bool = False, tz: str | None = None
+) -> DateTime:
     """
     Converts an epoch timestamp to a DateTime object.
 
@@ -231,7 +237,9 @@ def epoch_to_utc_datetime(epoch_int: int | float | str) -> DateTime:
     return pendulum.from_timestamp(int(epoch_int), tz=UTC_TZ)
 
 
-def is_office_hours_in_timezone(epoch_int: int | float | str, 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.
@@ -263,7 +271,8 @@ def is_office_hours_in_timezone(epoch_int: int | float | str, tz: str | None = N
 
 
 def get_datetime_from_ordinal_and_sentinel(
-        sentinel: DateTimeLike | 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.
@@ -324,8 +333,8 @@ def day_span(pts: DateTimeLike) -> Tuple[DateTime, DateTime]:
     pdt = pendulum.instance(pts)
 
     # Use Pendulum's clean API
-    begin = pdt.start_of('day')
-    end = pdt.add(days=1).start_of('day')
+    begin = pdt.start_of("day")
+    end = pdt.add(days=1).start_of("day")
 
     if naive:
         return begin.naive(), end.naive()
@@ -362,7 +371,7 @@ def week_span(wso: int) -> Callable[[DateTimeLike], Tuple[DateTime, DateTime]]:
         current_weekday = pdt.weekday() + 1  # Pendulum uses 0-6, we want 1-7
         days_back = (current_weekday - wso) % 7
 
-        begin = pdt.start_of('day').subtract(days=days_back)
+        begin = pdt.start_of("day").subtract(days=days_back)
         end = begin.add(days=7)
 
         if naive:
@@ -401,10 +410,10 @@ def month_span(mso: int) -> Callable[[DateTimeLike], Tuple[DateTime, DateTime]]:
 
         if current_day >= mso:
             # We're in the current month period
-            begin = pdt.start_of('day').replace(day=mso)
+            begin = pdt.start_of("day").replace(day=mso)
         else:
             # We're in the previous month period
-            begin = pdt.start_of('day').subtract(months=1).replace(day=mso)
+            begin = pdt.start_of("day").subtract(months=1).replace(day=mso)
 
         # End is mso of next month from `begin`
         end = begin.add(months=1)
@@ -417,8 +426,9 @@ def month_span(mso: int) -> Callable[[DateTimeLike], Tuple[DateTime, DateTime]]:
     return find_dates
 
 
-def arb_span(dates: Sequence[str | DateTimeOrDateLike], naive: bool = False) -> Callable[
-    [Any], Tuple[DateTime, DateTime]]:
+def arb_span(
+    dates: Sequence[str | DateTimeOrDateLike], 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
@@ -447,19 +457,25 @@ def arb_span(dates: Sequence[str | DateTimeOrDateLike], naive: bool = False) ->
                 parsed = pendulum.parse(date)
 
                 # If it's a date-only string (no time/timezone info), treat as naive
-                if 'T' not in date and ' ' not in date:
+                if "T" not in date and " " not in date:
                     parsed = parsed.naive()
 
-                parsed_dates.append(parsed.start_of('day'))
+                parsed_dates.append(parsed.start_of("day"))
             else:
                 # It's already a datetime-like object
                 if isinstance(date, datetime):
                     # datetime objects have tzinfo, hour, minute, etc.
                     if date.tzinfo is None:
                         # Input is naive, keep it naive using pendulum.naive()
-                        parsed = pendulum.naive(date.year, date.month, date.day,
-                                                date.hour, date.minute, date.second,
-                                                date.microsecond)
+                        parsed = pendulum.naive(
+                            date.year,
+                            date.month,
+                            date.day,
+                            date.hour,
+                            date.minute,
+                            date.second,
+                            date.microsecond,
+                        )
                     else:
                         # Input is timezone-aware, preserve it
                         parsed = pendulum.instance(date)
@@ -467,7 +483,7 @@ def arb_span(dates: Sequence[str | DateTimeOrDateLike], naive: bool = False) ->
                     # date objects (no time component, no tzinfo) - treat as naive
                     parsed = pendulum.naive(date.year, date.month, date.day)
 
-                parsed_dates.append(parsed.start_of('day'))
+                parsed_dates.append(parsed.start_of("day"))
 
         a, b = parsed_dates
 
@@ -497,8 +513,8 @@ def arb_span(dates: Sequence[str | DateTimeOrDateLike], naive: bool = False) ->
 
 
 def unroll_span_func(
-        f: Callable[[DateTimeLike], Tuple[DateTime, DateTime]],
-        cover: DateTimeLike | None = None,
+    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.
@@ -554,7 +570,7 @@ def unroll_span_func(
             if dt <= current_date_sentinel and dt < end:
                 date_range.append(dt)
                 ord_days.append(dt.day_of_year)
-                iso_date_strings.append(dt.format('YYYY-MM-DD'))
+                iso_date_strings.append(dt.format("YYYY-MM-DD"))
 
         return date_range, ord_days, iso_date_strings, start, end
 
@@ -563,10 +579,10 @@ def unroll_span_func(
 
 
 def keys_for_span_func(
-        f: Callable[[DateTimeLike], Tuple[DateTime, DateTime]],
-        cover: DateTimeLike | None = None,
-        key_in_format: str = "ODIN_{}",
-        key_out_format: str = "ODOUT_{}",
+    f: Callable[[DateTimeLike], Tuple[DateTime, DateTime]],
+    cover: DateTimeLike | None = None,
+    key_in_format: str = "ODIN_{}",
+    key_out_format: str = "ODOUT_{}",
 ):
     """
     Generate keys for a date range based on a provided function.
@@ -586,14 +602,17 @@ def keys_for_span_func(
     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)
+    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: DateTimeLike | 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:
@@ -601,7 +620,7 @@ def calendar_month_start_end(date_in_month: DateTimeLike | None = None) -> Tuple
 
     pdt = pendulum.instance(date_in_month)
 
-    start = pdt.start_of('month')
+    start = pdt.start_of("month")
     end = start.add(months=1)
 
     if naive:
@@ -620,8 +639,9 @@ def unix_timestamp() -> int:
     return round(time.time())
 
 
-def sentinel_date_and_ordinal_to_date(sentinel_date: DateTimeLike | date,
-                                      ordinal: int | float | str) -> 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
     int_ordinal = int(ordinal)
@@ -638,7 +658,7 @@ def sentinel_date_and_ordinal_to_date(sentinel_date: DateTimeLike | date,
 def seconds_to_end_of_month() -> int:
     """Calculate seconds remaining until the end of the current month"""
     now = pendulum.now(UTC_TZ)
-    end_of_month = now.end_of('month')
+    end_of_month = now.end_of("month")
     return int((end_of_month - now).total_seconds())
 
 
@@ -667,24 +687,42 @@ def get_notice_end_date(given_date: DateTimeLike | date | Date | None = None) ->
         given_date = given_date.date()
     elif not isinstance(given_date, date):
         raise ValueError(
-            "Given date must be a datetime.date or datetime.datetime object")
+            "Given date must be a datetime.date or datetime.datetime object"
+        )
 
     pdt = pendulum.instance(given_date)
     if given_date.day <= 15:
         # End of current month
-        end_date = pdt.add(months=1).start_of('month')
+        end_date = pdt.add(months=1).start_of("month")
     else:
         # End of next month
-        end_date = pdt.add(months=2).start_of('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: DateTimeLike) -> str:
-    """Convert DateTime to South Africa time string"""
-    # Convert to Pendulum
+def dt_to_za_time_string(v: DateTimeOrDateLike | float | None) -> str | None:
+    """Convert DateTime or Date to South Africa time string.
+
+    For datetime objects: returns "YYYY-MM-DD HH:MM:SS" in ZA timezone.
+    For date objects: returns "YYYY-MM-DD" (no time component).
+    For None: returns None.
+    For float values (NaN): returns None.
+    """
+    if v is None:
+        return None
+
+    # Handle float values (NaN from pandas NULL database values)
+    if isinstance(v, float):
+        return None
+
+    # Handle date objects (no time component)
+    if isinstance(v, date) and not isinstance(v, datetime):
+        return v.strftime("%Y-%m-%d")
+
+    # Convert datetime to Pendulum
     naive = v.tzinfo is None
     if naive:
         pdt = pendulum.instance(v, tz=ZA_TZ)
@@ -697,10 +735,7 @@ def months_ago_selection() -> List[Tuple[int, str]]:
     """Generate list of (index, "Month-Year") tuples for last 12 months"""
     today = pendulum.today()
 
-    return [
-        (i, today.subtract(months=i).strftime("%B-%Y"))
-        for i in range(12)
-    ]
+    return [(i, today.subtract(months=i).strftime("%B-%Y")) for i in range(12)]
 
 
 def is_aware(dt: DateTimeLike | Date | date) -> bool:
@@ -708,7 +743,9 @@ def is_aware(dt: DateTimeLike | Date | date) -> bool:
     return dt.tzinfo is not None and dt.tzinfo.utcoffset(dt) is not None
 
 
-def make_aware(dt: DateTimeLike | date | Date | None, tz: str = None) -> DateTime | Date | 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.
 
@@ -743,7 +780,9 @@ def make_aware(dt: DateTimeLike | date | Date | None, tz: str = None) -> DateTim
         raise DateUtilsError(f"Invalid timezone: {tz}") from e
 
 
-def unaware_to_utc_aware(dt: DateTimeLike | date | Date | None) -> DateTime | Date | None:
+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.6.1 → none_shall_parse-0.6.3}/src/none_shall_parse/imeis.py

@@ -1,4 +1,3 @@
-
 LUHN_DOUBLES = [0, 2, 4, 6, 8, 1, 3, 5, 7, 9]
 
 

{none_shall_parse-0.6.1 → none_shall_parse-0.6.3}/src/none_shall_parse/lists.py

@@ -1,4 +1,3 @@
-import collections
 from typing import Iterable, Generator, Any, List
 
 from .types import T