none-shall-parse 0.6.2__py3-none-any.whl

none_shall_parse/imeis.py

@@ -0,0 +1,211 @@
+
+LUHN_DOUBLES = [0, 2, 4, 6, 8, 1, 3, 5, 7, 9]
+
+
+def get_luhn_digit(n: 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: 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: 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: 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: 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: 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: 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

@@ -0,0 +1,48 @@
+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.
+
+    This function takes an iterable, which may contain nested iterables,
+    and returns a generator that yields each element in a flattened order.
+    Strings and bytes are treated as atomic elements and will not be traversed
+    further as nested iterables.
+
+    :param some_list: A potentially nested iterable to be flattened.
+    :type some_list: Iterable
+    :return: A generator that yields elements from the input iterable in a
+        flattened order.
+    :rtype: Generator[Any, None, None]
+    """
+    for el in some_list:
+        if isinstance(el, Iterable) and not isinstance(el, (str, bytes)):
+            yield from flatten(el)
+        else:
+            yield el
+
+
+def safe_list_get(lst: List[T], idx: int, default: T = None) -> T:
+    """
+    Retrieve an element from a list by its index or return a default value if the index
+    is out of range or the input is not subscriptable. This function ensures safe retrieval
+    by providing a fallback value when access fails.
+
+    :param lst: The list from which the element is to be retrieved (may be None).
+    :type lst: List[T]
+    :param idx: The index of the element to retrieve from the list.
+    :type idx: int
+    :param default: The fallback value to be returned if retrieval fails.
+    :type default: T
+    :return: The element at the specified index, or the default value
+             if the index is out of range or lst is None/not subscriptable.
+    :rtype: T
+    """
+    try:
+        return lst[idx]
+    except (IndexError, TypeError):
+        return default

none_shall_parse/parse.py

@@ -0,0 +1,196 @@
+from typing import Callable, Any
+from typing import Union
+
+from .strings import slugify
+from .types import ChoicesType, StringLike
+
+_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:
+    """
+    Convert a string representation of a boolean into a boolean value.
+
+    This function takes a string input and attempts to interpret it as a boolean
+    value based on predefined sets of true and false representations. It can
+    also raise an exception for invalid inputs if specified.
+
+    :param v: The string value to be interpreted as boolean.
+    :type v: str
+    :param raise_exc: Determines whether to raise an exception for invalid inputs.
+    :type raise_exc: bool
+    :return: A boolean value interpreted from the input string or None if invalid.
+    :rtype: bool | None
+    :raises ValueError: If the input string is invalid and `raise_exc` is True.
+    """
+    if isinstance(v, str):
+        v = v.lower()
+        if v in _true_set:
+            return True
+        if v in _false_set:
+            return False
+
+    if raise_exc:
+        raise ValueError('Expected "%s"' % '", "'.join(_true_set | _false_set))
+    return None
+
+
+def is_true(v: Any) -> bool:
+    """
+    Determines whether the given value evaluates to a boolean `True`.
+
+    The function checks if the input value can be converted to a boolean
+    representation of `True` using the helper function `str_to_bool`.
+
+    :param v: The value to be evaluated for boolean truthiness
+    :type v: Any
+    :return: `True` if the value evaluates to boolean `True`, otherwise `False`
+    :rtype: bool
+    """
+    return str_to_bool(v) is True
+
+
+def is_false(v: Any) -> bool:
+    """
+    Determines if the given value evaluates to a boolean False.
+
+    This function utilizes the `str_to_bool` conversion to determine whether
+    the input value corresponds to a boolean `False`. It is particularly
+    useful for interpreting string-based representations of boolean values.
+
+    :param v: The value to be evaluated.
+    :type v: Any
+    :return: True if the value evaluates to False, otherwise False.
+    :rtype: bool
+    """
+    return str_to_bool(v) is False
+
+
+def str_to_strs_list(s: str | None) -> list[str]:
+    """
+    Parses a given string into an array of strings. The input string is split based on
+    commas or newline characters. Each resulting element is stripped of leading and
+    trailing whitespace, and empty items are excluded from the result. If the input
+    string is None, an empty list is returned.
+
+    :param s: The input string to be parsed. May be None.
+    :type s: str | None
+    :return: A list of non-empty, trimmed strings extracted from the input.
+    :rtype: list[str]
+    """
+    return (
+        []
+        if s is None
+        else [e.strip() for e in s.replace("\n", ",").split(",") if e.strip()]
+    )
+
+
+def int_to_bool(v: int | float) -> bool:
+    """
+    Given an integer, convert it to bool.
+    If the integer is 1, return True, otherwise, return False.
+
+    Will raise an exception if the provided value cannot be cast to an integer.
+    :param v:
+    :exceptions: ValueError, TypeError
+    :return: True or False
+    """
+    return int(v) == 1
+
+
+def int_or_none(s: int | float | str | None) -> int | None:
+    """
+    Parses the input value and attempts to convert it into an integer. If the
+    input is invalid (such as being non-numeric), `None` is returned. If the
+    input is `-1` or `None`, it also returns `None`. Otherwise, the integer
+    value of the input is returned.
+
+    :param s: The input value to be parsed. Can be of type `int`, `float`, `str`,
+        or `None`.
+    :return: Returns the integer value of the input if successful. If the input
+        is invalid, equal to `-1`, or `None`, it returns `None`.
+    """
+    if s is None:
+        return None
+    try:
+        if int(s) == -1:
+            return None
+        else:
+            return int(s)
+    except ValueError:
+        return None
+
+
+def choices_code_to_string(
+    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
+    if required.
+
+    :param choices: A mapping of codes to string representations.
+    :type choices: ChoicesType
+
+    :param default: An optional default string to be returned if the code is not found in the choices.
+    :type default: str | None
+
+    :param to_slug: Specifies whether the resulting string should be slugified. If True, the string
+                    representation is converted to a slug with hyphens replaced by underscores.
+    :type to_slug: bool
+
+    :return: A callable function that takes an input (code) and returns the corresponding string
+             representation or the default value. If to_slug is True, it returns the slugified version
+             instead.
+    :rtype: Callable[[Union[int, str]], str | None]
+    """
+    dict_map = dict(choices)
+
+    def f(code):
+        return dict_map.get(code, default)
+
+    def s(code):
+        return slugify(dict_map.get(code, default)).replace("-", "_")
+
+    return s if to_slug else f
+
+
+def choices_string_to_code(
+    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
+    mappings where string keys need to be converted into codes, while optionally allowing
+    the input to be case-insensitive.
+
+    :param choices: A dictionary-like object or sequence of tuples representing the choices.
+    :param default: Optional value returned if the input string does not match any key. Defaults to None.
+    :param to_lower: A boolean indicating whether to convert keys in the choice dictionary
+                     and input string to lowercase for case-insensitive mapping. Defaults to False.
+    :return: A callable function that accepts a string input and returns the corresponding code from
+             the dictionary, or the default value if the input does not match.
+    """
+    if to_lower:
+        dict_map = {v.lower(): k for k, v in dict(choices).items()}
+    else:
+        dict_map = {v: k for k, v in dict(choices).items()}
+
+    def f(word):
+        return dict_map.get(word, default)
+
+    return f
+
+
+def none_or_empty(s=None):
+    """
+    Check if the given thing is not empty and not None
+    :param s:
+    :return:
+    """
+    if s is None:
+        return True
+    if s.strip() == "":
+        return True
+    return False