none-shall-parse 0.2.2__py3-none-any.whl → 0.4.0__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,682 @@
+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) -> 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, 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
+
+    # 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
+        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)
+
+        # 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
+
+
+# ------------------------------------------------------------------[ 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[
+    [], 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[[], 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() -> Tuple[datetime, datetime]:
+        """
+        :return: tuple of datetime objects (start, end)
+        """
+        if naive:
+            return begin.naive(), end.naive()
+        return begin, end
+
+    return find_dates
+
+
+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)
+
+    # One-liner for both values
+    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,
+                                      ordinal: int | float) -> 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

@@ -0,0 +1,212 @@
+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:
+    """
+    Calculates the Luhn checksum digit for a given number.
+
+    The function processes a number using the Luhn algorithm. It computes
+    the Luhn checksum digit based on the provided digits, ensuring that the
+    resulting number adheres to the Luhn standard. The method is useful for
+    validating numerical identifiers like credit card numbers or IMEIs.
+
+    Parameters:
+        n (str | int): A number represented as a string or integer that
+        requires Luhn checksum digit calculation.
+
+    Returns:
+        int: The Luhn checksum digit as an integer.
+    """
+    chars = [int(ch) for ch in str(n)]
+    firsts = [ch for ch in chars[0::2]]
+    doubles = [LUHN_DOUBLES[ch] for ch in chars[1::2]]
+    check = 10 - divmod(sum((sum(firsts), sum(doubles))), 10)[1]
+    return divmod(check, 10)[1]
+
+
+def is_valid_luhn(n: Union[str, int]) -> bool:
+    """
+    Determines if a given number, represented as a string or integer, adheres
+    to the Luhn algorithm.
+
+    The Luhn algorithm, also known as the mod 10 algorithm, is a simple checksum
+    formula used to validate identification numbers such as credit card numbers.
+
+    Parameters:
+    n : Union[str, int]
+        The input number to be validated. It can be provided as a string or an integer.
+
+    Returns:
+    bool
+        Returns True if the input number satisfies the Luhn algorithm; otherwise, False.
+    """
+    n = "".join(
+        [
+            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",
+            ]
+        ]
+    )
+    chars = [int(ch) for ch in str(n)][::-1]  # Reversed Digits
+    firsts = [ch for ch in chars[0::2]]
+    doubles = [LUHN_DOUBLES[ch] for ch in chars[1::2]]
+    final = sum((sum(firsts), sum(doubles)))
+    return divmod(final, 10)[1] == 0
+
+
+def is_valid_imei(n: Union[str, int]) -> bool:
+    """
+    Determines whether the given number is a valid IMEI (International Mobile
+    Equipment Identity) number.
+
+    An IMEI number is a 15-digit unique identifier for a mobile device. This function
+    first checks that the length of the input is 15 characters and then validates
+    it using the Luhn algorithm.
+
+    Parameters:
+    n: Union[str, int]
+        The number to be checked, represented as a string or integer.
+
+    Returns:
+    bool
+        True if the given number is a valid IMEI, otherwise False.
+    """
+    return len(str(n)) == 15 and is_valid_luhn(n)
+
+
+def normalize_imei(c: Union[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.
+
+    The IMEI (International Mobile Equipment Identity) is a unique identifier
+    typically consisting of 15 digits. This function ensures that the provided
+    IMEI-like input is converted into a valid IMEI format by calculating and appending
+    the appropriate check digit.
+
+    Parameters:
+    c: Union[str, int]
+        The input IMEI or a value resembling an IMEI. It can be provided as a string
+        or an integer.
+
+    Returns:
+    str
+        A 15-digit valid IMEI as a string.
+
+    Raises:
+    Exception
+        Raises any exceptions occurring internally within the `get_luhn_digit` function
+        if the calculation of the check digit fails.
+
+    Notes:
+    This function assumes the presence of the `get_luhn_digit` function for Luhn
+    digit calculation.
+    """
+    t = str(c)[:14]
+    check_digit = get_luhn_digit(t)
+    return "%s%s" % (t, check_digit)
+
+
+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
+    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
+    and a string representing the TAC if valid or a placeholder if invalid.
+    """
+    tac = "Not a Valid IMEI"
+    is_valid = is_valid_imei(n)
+    if not is_valid:
+        return False, tac
+    else:
+        tac = str(n)[:8]
+        return True, tac
+
+
+def decrement_imei(n: Union[str, int]) -> tuple[bool, str]:
+    """
+    Decrements the given IMEI number by one and normalizes it.
+
+    This function validates the provided IMEI number. If it is a valid IMEI, the
+    function decrements the first 14 digits by one and computes the new IMEI
+    checksum to generate a normalized IMEI. If the provided IMEI is not valid,
+    it returns a failure status and an error message.
+
+    Parameters:
+    n: int
+        The IMEI number to be validated and decremented.
+
+    Returns:
+    tuple[bool, str]
+        A tuple where the first element is a boolean indicating whether the
+        operation was successful, and the second element is the resulting IMEI
+        or an error message if the input was invalid.
+    """
+    result = "Not a Valid IMEI"
+    is_valid = is_valid_imei(n)
+    if not is_valid:
+        return False, result
+    else:
+        result = normalize_imei(int(str(n)[:14]) - 1)
+        return True, result
+
+
+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
+    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,
+    it returns a predefined invalid result.
+
+    Parameters:
+    n: int
+        IMEI number to be validated and potentially incremented.
+
+    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
+        IMEI number if valid or an error message if not valid.
+    """
+    result = "Not a Valid IMEI"
+    is_valid = is_valid_imei(n)
+    if not is_valid:
+        return False, result
+    else:
+        result = normalize_imei(int(str(n)[:14]) + 1)
+        return True, result

none_shall_parse/lists.py

@@ -1,7 +1,7 @@
 import collections
-from typing import Iterable, Generator, Any, TypeVar, List
+from typing import Iterable, Generator, Any, List
 
-T = TypeVar('T')
+from .types import T
 
 
 def flatten(some_list: Iterable) -> Generator[Any, None, None]:
@@ -46,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,12 +1,11 @@
-from typing import Any, Sequence, Tuple, Callable
+from typing import Callable, Any
 from typing import Union
 
 from .strings import slugify
+from .types import ChoicesType, StringLike
 
-ChoicesType = Sequence[Tuple[Union[int, str], str]]
-
-_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:
@@ -124,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, str]], str | 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
@@ -158,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

@@ -6,14 +6,16 @@ import re
 import secrets
 import string
 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+")
 
 
-def slugify(value, allow_unicode=False):
+def slugify(value: object, allow_unicode: bool = False) -> str:
     """
     Maps directly to Django's slugify function.
     Convert to ASCII if 'allow_unicode' is False. Convert spaces or repeated
@@ -38,10 +40,26 @@ def random_16():
     return "".join(random.choices(string.ascii_letters + string.digits, k=16))
 
 
-def to_human_string(s):
+def to_human_string(s: Any) -> tuple[Any | str, bool]:
     """
-    This replaces all tabs and newlines with spaces and removes all non-printing
-    control characters.
+    Cleans up a string by removing extra whitespace and control characters.
+
+    Removes unnecessary whitespace and control characters from the input string.
+    This function is designed to validate and clean user-provided string input
+    while preserving input that does not require modification. It returns the
+    cleaned string along with a boolean indicating whether changes were made
+    to the original string.
+
+    Parameters:
+    s : any
+        The input value to clean and validate. If it is not a string, it is
+        returned unchanged with a modification flag of False.
+
+    Returns:
+    tuple
+        A tuple where the first element is the cleaned string (or the original
+        input if it is not a string), and the second element is a boolean
+        indicating whether the string was modified.
     """
     if not isinstance(s, str):
         return s, False
@@ -53,7 +71,28 @@ def to_human_string(s):
     return clean_string, True
 
 
-def is_quoted_string(s, strip=False):
+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 `strip` parameter is set to True, it removes the enclosing quotes and returns
+    the unquoted string.
+
+    Parameters:
+    s : str
+        The input string to check and possibly process.
+    strip : bool, optional
+        Indicates whether to remove the enclosing quotes if the string is quoted.
+        Defaults to False.
+
+    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
+        version if `strip` is True.
+    """
     is_quoted = False
     result = s
     if not isinstance(s, str):
@@ -70,7 +109,32 @@ def is_quoted_string(s, strip=False):
     return is_quoted, result
 
 
-def is_numeric_string(s, convert=False):
+def is_numeric_string(s: str, convert: bool = False) -> tuple[bool, str | int | float]:
+    """
+    Checks if the given string represents a numeric value and optionally converts it.
+
+    This function determines if the provided string represents a numeric value.
+    If the input is numeric and the `convert` flag is set to True, it returns
+    the numeric value converted to either an integer (if the float represents
+    an integer) or a float. If the input is not numeric, it returns the original
+    input string.
+
+    Parameters
+    ----------
+    s : str
+        The input string to check.
+    convert : bool, optional
+        A flag indicating whether to convert the numeric string to a numeric
+        type (default is False).
+
+    Returns
+    -------
+    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;
+              otherwise, the original string.
+    """
     is_numeric = False
     result = s
     f = None
@@ -88,7 +152,7 @@ def is_numeric_string(s, convert=False):
     return is_numeric, result
 
 
-def custom_slug(s):
+def custom_slug(s: str) -> str:
     # Remove all non-word characters (everything except numbers and letters)
     s = re.sub(r"[^\w\s]", "", s)
 
@@ -98,34 +162,87 @@ def custom_slug(s):
     return s
 
 
-def b64_encode(s):
-    return base64.b64encode(s).decode("utf-8").strip("=")
+def b64_encode(s: str | bytes) -> str:
+    """
+    Encodes a string or bytes into its Base64 representation.
+
+    This function takes an input, either a string or bytes, and encodes it
+    into its Base64 representation. If the input is a string, it is first
+    encoded into bytes using UTF-8 encoding. The resulting Base64 encoded
+    value is returned as a string.
+
+    Args:
+        s: The input to encode, which can be either a string or bytes.
+
+    Returns:
+        The Base64 encoded representation of the input as a string.
+    """
+    if isinstance(s, str):
+        s = s.encode("utf-8")
+    return base64.b64encode(s).decode("utf-8")
+
+
+def b64_decode(s: str) -> bytes:
+    """
+    Decodes a Base64 encoded string to its original binary format.
+
+    This function takes a Base64 encoded string and decodes it to its
+    original bytes form. Base64 encoding may omit padding characters, so
+    the function ensures the input is properly padded before decoding.
+
+    Parameters:
+    s: str
+        A Base64 encoded string that needs to be decoded.
 
+    Returns:
+    bytes
+        The decoded binary data.
 
-def b64_decode(s):
+    Raises:
+    ValueError
+        If the input string contains invalid Base64 characters.
+    """
     pad = "=" * (-len(s) % 4)
     return base64.b64decode(s + pad)
 
 
-def calc_hash(*args):
+def calc_hash(*args: Any) -> str:
     """
-    Calculate a hash over the set of arguments.
-    This is useful to compare models against each other for equality
-    if the assumption is that if some combination of fields are equal, then
-    the models represent equal ideas.
+    Calculate and return a SHA-1 hash for the given arguments.
+
+    This function joins the provided arguments into a single string, encodes it
+    using UTF-16, and calculates the SHA-1 hash of the resulting bytes.
+
+    Args:
+        *args: A variable number of arguments to include in the hash.
+
+    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=10):
+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
+    password can be customized using the 'n' parameter.
+
+    Parameters:
+        n (int): Length of the password to be generated. Default is 10.
+
+    Returns:
+        str: A randomly generated password that meets the specified criteria.
+    """
     alphabet = string.ascii_letters + string.digits
     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

@@ -0,0 +1,32 @@
+from typing import Protocol, Sequence, Tuple, Union, TypeVar
+
+
+class StringLike(Protocol):
+    """
+    Protocol that defines the expected behavior for string-like objects.
+
+    This protocol specifies the methods and properties that an object
+    must implement to be considered string-like. It defines basic
+    string operations such as getting the string representation and
+    length, string concatenation, containment checks, and several
+    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: ...
+    def __contains__(self, item: str) -> bool: ...
+
+    # Most commonly used string methods
+    def upper(self) -> str: ...
+    def lower(self) -> str: ...
+    def strip(self) -> str: ...
+    def startswith(self, prefix: str) -> bool: ...
+    def endswith(self, suffix: str) -> bool: ...
+    def replace(self, old: str, new: str) -> str: ...
+
+
+ChoicesType = Sequence[Tuple[Union[int, str], StringLike]]
+
+T = TypeVar("T")

{none_shall_parse-0.2.2.dist-info → none_shall_parse-0.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: none-shall-parse
-Version: 0.2.2
+Version: 0.4.0
 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.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+none_shall_parse/__init__.py,sha256=3uhWV40LVbfVnCtRGCDLdTKyBBcoH56zgIApAQWWN0Q,549
+none_shall_parse/dates.py,sha256=njpvrozrbAqWsfdXTl5crR9SiQWONSv8W27QE-CCV94,23430
+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.0.dist-info/WHEEL,sha256=4n27za1eEkOnA7dNjN6C5-O2rUiw6iapszm14Uj-Qmk,79
+none_shall_parse-0.4.0.dist-info/METADATA,sha256=x4drnmVl1J-P9Mp8NQ3R-8EKC5VTJgZ0jZ8n9IcvzK8,1701
+none_shall_parse-0.4.0.dist-info/RECORD,,

none_shall_parse-0.2.2.dist-info/RECORD

@@ -1,7 +0,0 @@
-none_shall_parse/__init__.py,sha256=ElNUb98vffLm3_IvHJWLklIPWvr0p84SdpVLHof2n1o,548
-none_shall_parse/lists.py,sha256=IndbwxaxvByFtW88AtHyNOTDDp-E1EWLz_KY7OCcBIU,1712
-none_shall_parse/parse.py,sha256=99A_Xo3n2I2zGsgJcobjRPhgNOO1HytpZHs_hmr7t2c,6878
-none_shall_parse/strings.py,sha256=_fvsQtUyjqmPj_c4NjeOsAPrd5LOzNb4SX16-ZyZIEA,3511
-none_shall_parse-0.2.2.dist-info/WHEEL,sha256=4n27za1eEkOnA7dNjN6C5-O2rUiw6iapszm14Uj-Qmk,79
-none_shall_parse-0.2.2.dist-info/METADATA,sha256=iCpKl9FrsBF2jCeC9aciK7Wc0oMWciAxfgx-obdobvg,1676
-none_shall_parse-0.2.2.dist-info/RECORD,,