none-shall-parse 0.3.0__py3-none-any.whl → 0.4.1__py3-none-any.whl

none_shall_parse/__init__.py

@@ -12,4 +12,4 @@ https://www.youtube.com/watch?v=zKhEw7nD9C4
 """
 
 __author__ = "Andries Niemandt, Jan Badenhorst"
-__email__ = "andries.niemandt@trintel.co.za, jan@trintel.co.za"
+__email__ = "andries.niemandt@trintel.co.za, jan@trintel.co.za"

none_shall_parse/dates.py

@@ -0,0 +1,760 @@
+import functools
+import logging
+import time
+from datetime import date, datetime
+from typing import Callable, Any, Tuple, Sequence, List
+
+import pendulum
+from pendulum import local_timezone
+from pendulum.tz.exceptions import InvalidTimezone
+
+ZA_TZ = 'Africa/Johannesburg'
+UTC_TZ = 'UTC'
+
+
+class DateUtilsError(Exception):
+    """
+    Raised when some date calc gets crap input.
+    """
+
+    message = None
+
+    def __init__(self, message):
+        super().__init__(message)
+        self.message = message
+
+
+def assert_week_start_date_is_valid(wso):
+    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):
+    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:
+    """
+    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
+    parameters provided.
+
+    Args:
+        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.
+
+    Returns:
+        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:
+    """
+    Returns the current date and time in the South African timezone.
+
+    This function retrieves the current date and time, ensuring it is aware of
+    time zone settings. It uses the South African timezone (ZA_TZ) for proper
+    time localization.
+
+    Returns:
+        datetime: The current date and time in the South African timezone.
+    """
+    return get_datetime_now(naive=False, tz=ZA_TZ)
+
+
+def za_ordinal_year_day_now() -> int:
+    """
+    Returns the current ordinal day of the year for the ZA_TZ timezone.
+
+    This function calculates and returns the day of the year based on the current
+    date and time in the ZA (South Africa) timezone.
+
+    Returns:
+        int: The current ordinal day of the year in ZA_TZ timezone.
+    """
+    return pendulum.now(ZA_TZ).day_of_year
+
+
+def za_ordinal_year_day_tomorrow() -> int:
+    """
+    Returns the ordinal day of the year for tomorrow in the ZA_TZ timezone.
+
+    This function calculates the ordinal day of the year (1 to 366) for the date
+    that is one day ahead of today, as per the ZA_TZ timezone.
+
+    Returns:
+        int: The ordinal day of the year for tomorrow in the ZA_TZ timezone.
+    """
+    return pendulum.now(ZA_TZ).add(days=1).day_of_year
+
+
+def utc_epoch_start() -> datetime:
+    """
+    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
+    handling the time calculation with the specified UTC timezone.
+
+    Returns:
+        datetime: A 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:
+    """
+    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
+    (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.
+
+    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).
+            Defaults to False.
+        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.
+    """
+    kwargs = {units: n}
+    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:
+    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:
+    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:
+    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"""
+    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"""
+    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"""
+    return pendulum.now(UTC_TZ).add(days=n)
+
+
+def epoch_to_datetime(epoch_int: int | float, naive: bool = False,
+                      tz: str | None = None) -> datetime:
+    """
+    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
+    parameters provided.
+
+    Parameters:
+        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
+            (without timezone information). Defaults to False.
+        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.
+    """
+
+    # We force the timezone to the user's local timezone if none was supplied
+    # to make this function behave the same as the other functions, where the absense
+    # of a timezone is interpreted as the user's local timezone.'
+    if tz is None:
+        tz = local_timezone()
+
+    if naive:
+        return pendulum.from_timestamp(int(epoch_int), tz=tz).naive()
+    return pendulum.from_timestamp(int(epoch_int), tz=tz)
+
+
+def epoch_to_utc_datetime(epoch_int: int | float | str) -> datetime:
+    """
+    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.
+
+    Parameters:
+        epoch_int: An epoch timestamp represented as an integer or float.
+
+    Returns:
+        A datetime object in UTC corresponding to the provided epoch timestamp.
+    """
+    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:
+    """
+    Determines if a given epoch timestamp falls within office hours for a
+    specific timezone.
+
+    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
+    within the defined office hours.
+
+    Parameters:
+        epoch_int: int | float
+            Epoch timestamp to be checked. It must represent the number of seconds
+            (or fraction of seconds, if float) since the UNIX epoch.
+        tz: str, optional
+            Timezone expressed as a string. Defaults to local system timezone.
+
+    Returns:
+        bool
+            True if the epoch timestamp occurs within office hours for the specified
+            timezone otherwise, False.
+    """
+    dt = pendulum.from_timestamp(int(epoch_int), tz=tz)
+
+    # Create office hours boundaries for the same date
+    oh_begin = dt.replace(hour=8, minute=0, second=0, microsecond=0)
+    oh_end = dt.replace(hour=17, minute=0, second=0, microsecond=0)
+
+    return oh_begin < dt < oh_end
+
+
+def get_datetime_from_ordinal_and_sentinel(
+        sentinel: datetime | 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.
+
+    If the given sentinel is timezone-aware, the results will be as well, and in the
+    same timezone. If the given sentinel is naive, the results will be naive.
+    """
+    # 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
+
+    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)
+
+    def f(ordinal: int) -> datetime:
+        dt = this_year if ordinal <= sentinel_doy else last_year
+
+        # Handle leap year edge case
+        if ordinal == 366 and not dt.is_leap_year():
+            if naive:
+                return pendulum.naive(1970, 1, 1)
+            else:
+                return pendulum.datetime(1970, 1, 1, tz=sentinel_pdt.timezone)
+
+        result = dt.add(days=ordinal - 1)
+        return result
+
+    return f
+
+
+# ------------------------------------------------------------------[ Span Functions ]--
+def day_span(pts: datetime) -> Tuple[datetime, datetime]:
+    """
+    Returns the beginning and end of the day passed in.
+    begin is inclusive and end is exclusive.
+
+    If the given datetime is timezone aware, the results will be as well, and in the
+    same timezone. If the given sentinel is naive, the results will be naive.
+
+    Examples:
+        from datetime import datetime
+        dt = datetime(2023, 12, 25, 14, 30, 45)
+
+        start, end = day_span(dt)
+        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
+    begin = pdt.start_of('day')
+    end = pdt.add(days=1).start_of('day')
+
+    if naive:
+        return begin.naive(), end.naive()
+    else:
+        return begin, end
+
+
+def week_span(wso: int) -> Callable[[datetime], Tuple[datetime, datetime]]:
+    """
+    Given an integer between 1 and 7, return a function that will give the
+    start and end dates of the week.
+
+    If the given datetime is timezone aware, the results will be as well, and in the
+    same timezone. If the given sentinel is naive, the results will be naive.
+
+    Examples:
+        from datetime import datetime
+        dt = datetime(2023, 12, 25, 14, 30, 45)
+
+        # Week starting on Wednesday (ISO day 3)
+        week_func = week_span(3)
+        week_start, week_end = week_func(dt)
+
+    :param wso: ISO weekday integer (1=Monday, 7=Sunday)
+    """
+    assert_week_start_date_is_valid(wso)
+
+    def find_dates(pts: datetime) -> Tuple[datetime, datetime]:
+        # Check if input is naive or aware
+        naive = pts.tzinfo is None
+        pdt = pendulum.instance(pts)
+
+        # Get to the desired week start day
+        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)
+        end = begin.add(days=7)
+
+        if naive:
+            return begin.naive(), end.naive()
+        else:
+            return begin, end
+
+    return find_dates
+
+
+def month_span(mso: int) -> Callable[[datetime], 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.
+
+    If the given datetime is timezone aware, the results will be as well, and in the
+    same timezone. If the given sentinel is naive, the results will be naive.
+
+    Examples:
+        from datetime import datetime
+        dt = datetime(2023, 12, 25, 14, 30, 45)
+
+        # Month starting on 15th
+        month_func = month_span(15)
+        month_start, month_end = month_func(dt)
+
+    :param mso: Integer (1-28, the day of month to start periods on)
+    """
+    assert_month_start_date_is_valid(mso)
+
+    def find_dates(pts: datetime) -> Tuple[datetime, datetime]:
+        # Convert to Pendulum
+        naive = pts.tzinfo is None
+        pdt = pendulum.instance(pts)
+        current_day = pdt.day
+
+        if current_day >= mso:
+            # We're in the current month period
+            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)
+
+        # End is mso of next month from `begin`
+        end = begin.add(months=1)
+
+        if naive:
+            return begin.naive(), end.naive()
+        else:
+            return begin, end
+
+    return find_dates
+
+
+def arb_span(dates: Sequence[str | datetime], 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
+            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.
+
+    Raises:
+        DateUtilsError: If the provided dates are invalid, identical, or there's an error
+       during parsing.
+    """
+    try:
+        parsed_dates = []
+
+        for date in dates[:2]:
+            if isinstance(date, str):
+                # Parse string - pendulum.parse returns UTC for date-only strings
+                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:
+                    parsed = parsed.naive()
+
+                parsed_dates.append(parsed.start_of('day'))
+            else:
+                # It's already a datetime
+                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)
+                else:
+                    # Input is timezone-aware, preserve it
+                    parsed = pendulum.instance(date)
+
+                parsed_dates.append(parsed.start_of('day'))
+
+        a, b = parsed_dates
+
+        # Check if they're comparable (both naive or both aware)
+        if (a.tzinfo is None) != (b.tzinfo is None):
+            raise DateUtilsError("Cannot compare naive and timezone-aware datetimes")
+
+        if a == b:
+            raise DateUtilsError("Dates may not be the same")
+
+        # Ensure `begin` is the earlier date and `end` is the later date
+        begin = a if a < b else b
+        end = b if a < b else a
+
+    except Exception as ex:
+        raise DateUtilsError(f"Error parsing dates: {ex}")
+
+    def find_dates(*args) -> Tuple[datetime, datetime]:
+        """
+        :return: tuple of datetime objects (start, end)
+        """
+        if naive:
+            return begin.naive(), end.naive()
+        return begin, end
+
+    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
+
+    if date_in_month is None:
+        date_in_month = za_now()
+
+    pdt = pendulum.instance(date_in_month)
+
+    start = pdt.start_of('month')
+    end = start.add(months=1)
+
+    if naive:
+        return start.naive(), end.naive()
+
+    return start, end
+
+
+# --------------------------------------------------------------------[ Unaware time ]--
+def unix_timestamp() -> int:
+    """
+    Unix timestamps are, by definition, the number of seconds since the epoch - a
+    fixed moment in time, defined as 01-01-1970 UTC.
+    :return: Current Unix timestamp
+    """
+    return round(time.time())
+
+
+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)
+
+    # If sentinel is Jan 1st and ordinal > 1, use previous year
+    if sentinel_date.month == 1 and sentinel_date.day == 1 and int_ordinal > 1:
+        year = year - 1
+
+    # Use Pendulum for date arithmetic
+    dt = pendulum.datetime(year, 1, 1).add(days=int_ordinal - 1)
+    return dt.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')
+    return int((end_of_month - now).total_seconds())
+
+
+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
+    """
+    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:
+    """
+    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
+    ends at the end of the next month.
+    :param given_date: Date to calculate the notice end from
+    :return: Notice end date
+    """
+    if given_date is None:
+        given_date = pendulum.now().today()
+    elif isinstance(given_date, datetime):
+        given_date = given_date.date()
+    elif not isinstance(given_date, date):
+        raise ValueError(
+            "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')
+    else:
+        # End of next month
+        end_date = pdt.add(months=2).start_of('month')
+
+    return end_date
+
+
+def dt_to_za_time_string(v: datetime) -> str:
+    """Convert datetime to South Africa time string"""
+    # Convert to Pendulum
+    naive = v.tzinfo is None
+    if naive:
+        pdt = pendulum.instance(v, tz=ZA_TZ)
+    else:
+        pdt = pendulum.instance(v).in_timezone(ZA_TZ)
+    return pdt.strftime("%Y-%m-%d %H:%M:%S")
+
+
+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)
+    ]
+
+
+def is_aware(dt: datetime) -> 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:
+    """
+    Convert a naive datetime to a timezone-aware datetime using Pendulum.
+
+    Args:
+        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.
+
+    Raises:
+        TypeError: If dt is not a datetime object or None.
+        ValueError: If dt is already timezone-aware.
+        DateUtilsError: If the timezone string is invalid.
+    """
+    # We force the timezone to the user's local timezone if none was supplied
+    # to make this function behave the same as the other functions, where the absense
+    # of a timezone is interpreted as the user's local timezone.
+    if tz is None:
+        tz = local_timezone()
+
+    if dt is None:
+        return None
+    if not isinstance(dt, datetime):
+        raise TypeError(f"Expected datetime or None, got {type(dt).__name__}")
+    if is_aware(dt):
+        raise ValueError(f"Datetime is already timezone-aware with {dt.tzinfo}")
+
+    try:
+        return pendulum.instance(dt, tz=tz)
+    except InvalidTimezone as e:
+        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."""
+    if not isinstance(dt, (datetime, type(None))):
+        raise TypeError(f"Expected datetime or None, got {type(dt)}")
+
+    if dt is None or is_aware(dt):
+        return dt
+
+    # Use Pendulum for clean UTC conversion
+    pdt = pendulum.instance(dt, tz=UTC_TZ)
+    return pdt
+
+
+def timer_decorator(logger: logging.Logger | None = None):
+    """
+    Timer decorator that optionally accepts a logger.
+
+    Args:
+        logger: Logger instance to use for timing output. If None, uses print().
+
+    Returns:
+        Decorator function
+    """
+
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs) -> Any:
+            start_time = time.perf_counter()
+            result = func(*args, **kwargs)
+            end_time = time.perf_counter()
+            execution_time = end_time - start_time
+
+            message = f"{func.__name__}:TIME:{execution_time:.6f}s"
+
+            if logger:
+                logger.info(message)
+            else:
+                print(message)  # Fallback to print if no logger provided
+
+            return result
+
+        return wrapper
+
+    return decorator

none_shall_parse/imeis.py

@@ -47,28 +47,28 @@ def is_valid_luhn(n: Union[str, int]) -> bool:
             e
             for e in n
             if e
-               in [
-                   0,
-                   1,
-                   2,
-                   3,
-                   4,
-                   5,
-                   6,
-                   7,
-                   8,
-                   9,
-                   "0",
-                   "1",
-                   "2",
-                   "3",
-                   "4",
-                   "5",
-                   "6",
-                   "7",
-                   "8",
-                   "9",
-               ]
+            in [
+                0,
+                1,
+                2,
+                3,
+                4,
+                5,
+                6,
+                7,
+                8,
+                9,
+                "0",
+                "1",
+                "2",
+                "3",
+                "4",
+                "5",
+                "6",
+                "7",
+                "8",
+                "9",
+            ]
         ]
     )
     chars = [int(ch) for ch in str(n)][::-1]  # Reversed Digits
@@ -135,16 +135,16 @@ def get_tac_from_imei(n: Union[str, int]) -> tuple[bool, str]:
     """
     Determines the validity of an IMEI number and extracts its TAC if valid.
 
-    This function checks whether a provided IMEI (International Mobile Equipment 
-    Identity) number is valid based on IMEI validation rules. If the given IMEI 
-    is valid, the function also extracts and returns the TAC (Type Allocation 
+    This function checks whether a provided IMEI (International Mobile Equipment
+    Identity) number is valid based on IMEI validation rules. If the given IMEI
+    is valid, the function also extracts and returns the TAC (Type Allocation
     Code), which corresponds to the first 8 digits of the IMEI.
 
     Parameters:
     n (str): The IMEI number to be validated and processed.
 
     Returns:
-    tuple: A tuple containing a boolean indicating whether the IMEI is valid 
+    tuple: A tuple containing a boolean indicating whether the IMEI is valid
     and a string representing the TAC if valid or a placeholder if invalid.
     """
     tac = "Not a Valid IMEI"
@@ -188,9 +188,9 @@ def increment_imei(n: Union[str, int]) -> tuple[bool, str]:
     """
     Determines if a given IMEI number is valid and increments it by 1 if valid.
 
-    This function first checks if the provided IMEI number is valid using the 
+    This function first checks if the provided IMEI number is valid using the
     is_valid_imei function. If the input is a valid IMEI, it increments the IMEI
-    value by 1 while retaining only the first 14 digits. If the input is not valid, 
+    value by 1 while retaining only the first 14 digits. If the input is not valid,
     it returns a predefined invalid result.
 
     Parameters:
@@ -199,8 +199,8 @@ def increment_imei(n: Union[str, int]) -> tuple[bool, str]:
 
     Returns:
     tuple[bool, str]
-        A tuple where the first element is a boolean indicating whether the operation 
-        was successful, and the second element is a string containing the incremented 
+        A tuple where the first element is a boolean indicating whether the operation
+        was successful, and the second element is a string containing the incremented
         IMEI number if valid or an error message if not valid.
     """
     result = "Not a Valid IMEI"

none_shall_parse/lists.py

@@ -1,7 +1,9 @@
 import collections
 from typing import Iterable, Generator, Any, List
+
 from .types import T
 
+
 def flatten(some_list: Iterable) -> Generator[Any, None, None]:
     """
     Flattens a nested iterable into a one-dimensional generator.
@@ -44,4 +46,3 @@ def safe_list_get(lst: List[T], idx: int, default: T) -> T:
         return lst[idx]
     except IndexError:
         return default
-

none_shall_parse/parse.py

@@ -1,11 +1,11 @@
 from typing import Callable, Any
 from typing import Union
 
-from src.none_shall_parse.strings import slugify
-from src.none_shall_parse.types import ChoicesType, StringLike
+from .strings import slugify
+from .types import ChoicesType, StringLike
 
-_true_set = {'yes', 'true', 't', 'y', '1'}
-_false_set = {'no', 'false', 'f', 'n', '0'}
+_true_set = {"yes", "true", "t", "y", "1"}
+_false_set = {"no", "false", "f", "n", "0"}
 
 
 def str_to_bool(v: Any, raise_exc: bool = False) -> bool | None:
@@ -123,8 +123,8 @@ def int_or_none(s: int | float | str | None) -> int | None:
 
 
 def choices_code_to_string(
-        choices: ChoicesType, default: str | None = None,
-        to_slug: bool = False) -> Callable[[Union[int, StringLike]], StringLike | None]:
+    choices: ChoicesType, default: str | None = None, to_slug: bool = False
+) -> Callable[[Union[int, StringLike]], StringLike | None]:
     """
     Converts a code to a corresponding string representation based on provided choices.
     The function allows optional fallback to a default value and can slugify the resulting string
@@ -157,8 +157,8 @@ def choices_code_to_string(
 
 
 def choices_string_to_code(
-        choices: ChoicesType, default: Any = None,
-        to_lower: bool = False) -> Callable[[str], Union[int, str, None]]:
+    choices: ChoicesType, default: Any = None, to_lower: bool = False
+) -> Callable[[str], Union[int, str, None]]:
     """
     Converts a dictionary of choices into a callable function that maps input strings
     to their corresponding codes. This helper function is particularly useful for handling

none_shall_parse/strings.py

@@ -9,7 +9,8 @@ import unicodedata
 from typing import Any
 
 _control_chars = "".join(
-    map(chr, itertools.chain(range(0x00, 0x20), range(0x7F, 0xA0))))
+    map(chr, itertools.chain(range(0x00, 0x20), range(0x7F, 0xA0)))
+)
 _re_control_char = re.compile("[%s]" % re.escape(_control_chars))
 _re_combine_whitespace = re.compile(r"\s+")
 
@@ -74,8 +75,8 @@ def is_quoted_string(s: str, strip: bool = False) -> tuple[bool, str]:
     """
     Checks if a given string is enclosed in quotes and optionally strips the quotes.
 
-    The function determines whether a given string starts and ends with matching quotes, 
-    either single quotes (') or double quotes ("). If the string is quoted and 
+    The function determines whether a given string starts and ends with matching quotes,
+    either single quotes (') or double quotes ("). If the string is quoted and
     the `strip` parameter is set to True, it removes the enclosing quotes and returns
     the unquoted string.
 
@@ -88,8 +89,8 @@ def is_quoted_string(s: str, strip: bool = False) -> tuple[bool, str]:
 
     Returns:
     tuple[bool, str]
-        A tuple where the first element is a boolean indicating whether the string 
-        is quoted, and the second element is the original string or the stripped 
+        A tuple where the first element is a boolean indicating whether the string
+        is quoted, and the second element is the original string or the stripped
         version if `strip` is True.
     """
     is_quoted = False
@@ -131,7 +132,7 @@ def is_numeric_string(s: str, convert: bool = False) -> tuple[bool, str | int |
     tuple
         A tuple containing a boolean and the result:
             - A boolean indicating whether the input string is numeric or not.
-            - The numeric value if `convert` is True and the string is numeric; 
+            - The numeric value if `convert` is True and the string is numeric;
               otherwise, the original string.
     """
     is_numeric = False
@@ -218,15 +219,15 @@ def calc_hash(*args: Any) -> str:
     Returns:
         str: The computed SHA-1 hash as a hexadecimal string.
     """
-    s = '_'.join(map(str, args))
+    s = "_".join(map(str, args))
     return hashlib.sha1(s.encode("utf-16")).hexdigest()
 
 
 def generate_random_password(n: int = 10) -> str:
     """
-    Generates a random password meeting specific criteria for complexity. The 
-    function ensures the password contains at least one lowercase letter, one 
-    uppercase letter, and at least three numeric digits. The length of the 
+    Generates a random password meeting specific criteria for complexity. The
+    function ensures the password contains at least one lowercase letter, one
+    uppercase letter, and at least three numeric digits. The length of the
     password can be customized using the 'n' parameter.
 
     Parameters:
@@ -239,9 +240,9 @@ def generate_random_password(n: int = 10) -> str:
     while True:
         password = "".join(secrets.choice(alphabet) for i in range(n))
         if (
-                any(c.islower() for c in password)
-                and any(c.isupper() for c in password)
-                and sum(c.isdigit() for c in password) >= 3
+            any(c.islower() for c in password)
+            and any(c.isupper() for c in password)
+            and sum(c.isdigit() for c in password) >= 3
         ):
             break
     return password

none_shall_parse/types.py

@@ -12,6 +12,7 @@ class StringLike(Protocol):
     commonly used string manipulation methods. Objects adhering to
     this protocol can mimic the behavior of standard Python strings.
     """
+
     def __str__(self) -> str: ...
     def __len__(self) -> int: ...
     def __add__(self, other: str) -> str: ...
@@ -28,4 +29,4 @@ class StringLike(Protocol):
 
 ChoicesType = Sequence[Tuple[Union[int, str], StringLike]]
 
-T = TypeVar('T')
+T = TypeVar("T")

{none_shall_parse-0.3.0.dist-info → none_shall_parse-0.4.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: none-shall-parse
-Version: 0.3.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>
@@ -8,6 +8,7 @@ License: MIT
 Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
+Requires-Dist: pendulum
 Requires-Dist: pytest>=8.0.0 ; extra == 'dev'
 Requires-Dist: ruff>=0.12.3 ; extra == 'dev'
 Requires-Dist: isort ; extra == 'dev'
@@ -53,7 +54,7 @@ pip install none-shall-parse
 
 ## Development Quick Start
 
-#### To build an publish to pypi:
+#### To build and publish to pypi:
 
 Update the version in the `pyproject.toml` file, then:
 ```bash

none_shall_parse-0.4.1.dist-info/RECORD

@@ -0,0 +1,10 @@
+none_shall_parse/__init__.py,sha256=3uhWV40LVbfVnCtRGCDLdTKyBBcoH56zgIApAQWWN0Q,549
+none_shall_parse/dates.py,sha256=aoOlpzHynnO8HpMQxQteY1XunHPR6KzbZQgq9121JDE,26461
+none_shall_parse/imeis.py,sha256=o-TgbWDU4tmv1MHnAxfLCeZUpCZ8lt7VKOHrIeBmUFE,6837
+none_shall_parse/lists.py,sha256=buAahex2iOYXZIcGOFfE9y9BYgBgvo3RilIiv1BALJ8,1706
+none_shall_parse/parse.py,sha256=77bXZAtwFksRwuZ9Ax0lPxEjFpyjkQBqRa5mBc1WkF4,6843
+none_shall_parse/strings.py,sha256=Eqrl8Sb-wOzjTu1_bbO-ALljlDKVa-1LcpcACqOmZuE,7931
+none_shall_parse/types.py,sha256=PsljcR1UyyZZizm50wgyZPRNaeYvInSQoPS3i0RLgKo,1123
+none_shall_parse-0.4.1.dist-info/WHEEL,sha256=4n27za1eEkOnA7dNjN6C5-O2rUiw6iapszm14Uj-Qmk,79
+none_shall_parse-0.4.1.dist-info/METADATA,sha256=pW01F0kYVnFckUU2KTEtETYYgwJLBT_MGsrafjtfwxY,1701
+none_shall_parse-0.4.1.dist-info/RECORD,,

none_shall_parse-0.3.0.dist-info/RECORD

@@ -1,9 +0,0 @@
-none_shall_parse/__init__.py,sha256=ElNUb98vffLm3_IvHJWLklIPWvr0p84SdpVLHof2n1o,548
-none_shall_parse/imeis.py,sha256=sNLGeeGU0K4SvTb4xp-yuV0P3c-JjYDanble9f09uBc,6911
-none_shall_parse/lists.py,sha256=3s9Oi0-aUVcfzhIdW6N9-z7ZI56VxTa3WRDj1zAiJQI,1705
-none_shall_parse/parse.py,sha256=U4FUuQqtqgEKEC-3blUd78EFYyQHbBgbWW194VXdcYw,6905
-none_shall_parse/strings.py,sha256=HAcaDOHkrUZ_pDfNjfh89GQ5EJeBo6WjH5of1B11vos,7950
-none_shall_parse/types.py,sha256=SGHhzzIxC9_89STRa9eAQt18_cZVuklpj2cUnyrW8l0,1121
-none_shall_parse-0.3.0.dist-info/WHEEL,sha256=4n27za1eEkOnA7dNjN6C5-O2rUiw6iapszm14Uj-Qmk,79
-none_shall_parse-0.3.0.dist-info/METADATA,sha256=d-W1OJJiftIMIVXi3EzRYfgAWLu_74FYrchoBHmROOs,1676
-none_shall_parse-0.3.0.dist-info/RECORD,,