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

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,8 +1,6 @@
 import collections
-from typing import Iterable, Generator, Any, TypeVar, List
-
-T = TypeVar('T')
-
+from typing import Iterable, Generator, Any, List
+from .types import T
 
 def flatten(some_list: Iterable) -> Generator[Any, None, None]:
     """

none_shall_parse/parse.py

@@ -1,9 +1,8 @@
-from typing import Any, Sequence, Tuple, Callable
+from typing import Callable, Any
 from typing import Union
 
-from .strings import slugify
-
-ChoicesType = Sequence[Tuple[Union[int, str], str]]
+from src.none_shall_parse.strings import slugify
+from src.none_shall_parse.types import ChoicesType, StringLike
 
 _true_set = {'yes', 'true', 't', 'y', '1'}
 _false_set = {'no', 'false', 'f', 'n', '0'}
@@ -125,7 +124,7 @@ 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]:
+        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

none_shall_parse/strings.py

@@ -6,6 +6,7 @@ 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))))
@@ -13,7 +14,7 @@ _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 +39,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 +70,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 +108,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 +151,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,27 +161,80 @@ 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))
     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))

none_shall_parse/types.py

@@ -0,0 +1,31 @@
+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.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: none-shall-parse
-Version: 0.2.2
+Version: 0.3.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>

none_shall_parse-0.3.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+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,,

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,,