none-shall-parse 0.2.2__tar.gz → 0.3.1__tar.gz

{none_shall_parse-0.2.2 → none_shall_parse-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: none-shall-parse
-Version: 0.2.2
+Version: 0.3.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>
@@ -53,7 +53,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.2.2 → none_shall_parse-0.3.1}/README.md

@@ -32,7 +32,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.2.2 → none_shall_parse-0.3.1}/pyproject.toml

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

{none_shall_parse-0.2.2 → none_shall_parse-0.3.1}/src/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-0.3.1/src/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-0.2.2 → none_shall_parse-0.3.1}/src/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-0.2.2 → none_shall_parse-0.3.1}/src/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-0.3.1/src/none_shall_parse/strings.py

@@ -0,0 +1,248 @@
+import base64
+import hashlib
+import itertools
+import random
+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)))
+)
+_re_control_char = re.compile("[%s]" % re.escape(_control_chars))
+_re_combine_whitespace = re.compile(r"\s+")
+
+
+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
+    dashes to single dashes. Remove characters that aren't alphanumerics,
+    underscores, or hyphens. Convert to lowercase. Also strip leading and
+    trailing whitespace, dashes, and underscores.
+    """
+    value = str(value)
+    if allow_unicode:
+        value = unicodedata.normalize("NFKC", value)
+    else:
+        value = (
+            unicodedata.normalize("NFKD", value)
+            .encode("ascii", "ignore")
+            .decode("ascii")
+        )
+    value = re.sub(r"[^\w\s-]", "", value.lower())
+    return re.sub(r"[-\s]+", "-", value).strip("-_")
+
+
+def random_16():
+    return "".join(random.choices(string.ascii_letters + string.digits, k=16))
+
+
+def to_human_string(s: Any) -> tuple[Any | str, bool]:
+    """
+    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
+
+    c = _re_combine_whitespace.sub(" ", s).strip()
+    clean_string = _re_control_char.sub("", c)
+    if clean_string == s:
+        return s, False
+    return clean_string, True
+
+
+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):
+        return is_quoted, result
+
+    if s[0] == s[-1]:
+        if s[0] in ['"', "'"]:
+            is_quoted = True
+            if strip:
+                if s[0] == "'":
+                    result = s.strip("'")
+                elif s[0] == '"':
+                    result = s.strip('"')
+    return is_quoted, result
+
+
+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
+    if not isinstance(s, str):
+        return is_numeric, result
+    try:
+        f = float(s)
+        is_numeric = True
+    except ValueError:
+        is_numeric = False
+
+    if is_numeric and convert:
+        result = int(f) if f.is_integer() else f
+
+    return is_numeric, result
+
+
+def custom_slug(s: str) -> str:
+    # Remove all non-word characters (everything except numbers and letters)
+    s = re.sub(r"[^\w\s]", "", s)
+
+    # Replace all runs of whitespace with a single dash
+    s = re.sub(r"\s+", "_", s)
+
+    return s
+
+
+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.
+
+    Raises:
+    ValueError
+        If the input string contains invalid Base64 characters.
+    """
+    pad = "=" * (-len(s) % 4)
+    return base64.b64decode(s + pad)
+
+
+def calc_hash(*args: Any) -> str:
+    """
+    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))
+    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
+    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
+        ):
+            break
+    return password

none_shall_parse-0.3.1/src/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/src/none_shall_parse/strings.py

@@ -1,131 +0,0 @@
-import base64
-import hashlib
-import itertools
-import random
-import re
-import secrets
-import string
-import unicodedata
-
-_control_chars = "".join(
-    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):
-    """
-    Maps directly to Django's slugify function.
-    Convert to ASCII if 'allow_unicode' is False. Convert spaces or repeated
-    dashes to single dashes. Remove characters that aren't alphanumerics,
-    underscores, or hyphens. Convert to lowercase. Also strip leading and
-    trailing whitespace, dashes, and underscores.
-    """
-    value = str(value)
-    if allow_unicode:
-        value = unicodedata.normalize("NFKC", value)
-    else:
-        value = (
-            unicodedata.normalize("NFKD", value)
-            .encode("ascii", "ignore")
-            .decode("ascii")
-        )
-    value = re.sub(r"[^\w\s-]", "", value.lower())
-    return re.sub(r"[-\s]+", "-", value).strip("-_")
-
-
-def random_16():
-    return "".join(random.choices(string.ascii_letters + string.digits, k=16))
-
-
-def to_human_string(s):
-    """
-    This replaces all tabs and newlines with spaces and removes all non-printing
-    control characters.
-    """
-    if not isinstance(s, str):
-        return s, False
-
-    c = _re_combine_whitespace.sub(" ", s).strip()
-    clean_string = _re_control_char.sub("", c)
-    if clean_string == s:
-        return s, False
-    return clean_string, True
-
-
-def is_quoted_string(s, strip=False):
-    is_quoted = False
-    result = s
-    if not isinstance(s, str):
-        return is_quoted, result
-
-    if s[0] == s[-1]:
-        if s[0] in ['"', "'"]:
-            is_quoted = True
-            if strip:
-                if s[0] == "'":
-                    result = s.strip("'")
-                elif s[0] == '"':
-                    result = s.strip('"')
-    return is_quoted, result
-
-
-def is_numeric_string(s, convert=False):
-    is_numeric = False
-    result = s
-    f = None
-    if not isinstance(s, str):
-        return is_numeric, result
-    try:
-        f = float(s)
-        is_numeric = True
-    except ValueError:
-        is_numeric = False
-
-    if is_numeric and convert:
-        result = int(f) if f.is_integer() else f
-
-    return is_numeric, result
-
-
-def custom_slug(s):
-    # Remove all non-word characters (everything except numbers and letters)
-    s = re.sub(r"[^\w\s]", "", s)
-
-    # Replace all runs of whitespace with a single dash
-    s = re.sub(r"\s+", "_", s)
-
-    return s
-
-
-def b64_encode(s):
-    return base64.b64encode(s).decode("utf-8").strip("=")
-
-
-def b64_decode(s):
-    pad = "=" * (-len(s) % 4)
-    return base64.b64decode(s + pad)
-
-
-def calc_hash(*args):
-    """
-    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.
-    """
-    s = '_'.join(map(str, args))
-    return hashlib.sha1(s.encode("utf-16")).hexdigest()
-
-
-def generate_random_password(n=10):
-    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
-        ):
-            break
-    return password