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

none_shall_parse/__init__.py

@@ -0,0 +1,8 @@
+"""Trinity Shared Python utilities.
+
+A collection of shared utilities for Trinity projects.
+"""
+
+__version__ = "0.1.0"
+__author__ = "Jan Badenhorst, Andries Niemandt"
+__email__ = "jan@trintel.co.za"

none_shall_parse/utils/lists.py

@@ -0,0 +1,49 @@
+import collections
+from typing import Iterable, Generator, Any, TypeVar, List
+
+T = TypeVar('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, collections.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) -> T:
+    """
+    Retrieve an element from a list by its index or return a default value if the index
+    is out of range. This function ensures no IndexError is raised during the retrieval
+    process by providing a fallback value.
+
+    :param lst: The list from which the element is to be retrieved.
+    :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 the index is out of range.
+    :type default: T
+    :return: The element at the specified index, or the default value
+             if the index is out of range.
+    :rtype: T
+    """
+    try:
+        return lst[idx]
+    except IndexError:
+        return default
+

none_shall_parse/utils/parsing.py

@@ -0,0 +1,197 @@
+from typing import Any, Sequence, Tuple, Callable
+from typing import Union
+
+from .strings import slugify
+
+ChoicesType = Sequence[Tuple[Union[int, str], str]]
+
+_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, str]], str | 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

none_shall_parse/utils/strings.py

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

none_shall_parse-0.1.0.dist-info/METADATA

@@ -0,0 +1,47 @@
+Metadata-Version: 2.3
+Name: none-shall-parse
+Version: 0.1.0
+Summary: Trinity Shared Python utilities.
+Author: Jan Badenhorst, Andries Niemandt
+Author-email: Jan Badenhorst <jan.badenhorst@trintel.co.za>, Andries Niemandt <andries.niemandt@trintel.co.za>
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Dist: pytest>=8.0.0 ; extra == 'dev'
+Requires-Dist: ruff>=0.12.3 ; extra == 'dev'
+Requires-Dist: isort ; extra == 'dev'
+Requires-Dist: flake8 ; extra == 'dev'
+Requires-Dist: uv-build ; extra == 'dev'
+Requires-Dist: sphinx ; extra == 'docs'
+Requires-Dist: sphinx-rtd-theme ; extra == 'docs'
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/trinity-telecomms/tpu
+Project-URL: Issues, https://github.com/trinity-telecomms/tpu/issues
+Provides-Extra: dev
+Provides-Extra: docs
+Description-Content-Type: text/markdown
+
+# none_shall_parse
+
+Trinity Shared Python utilities.
+
+## Installation
+
+Using `uv`:
+
+```bash
+uv add git+https://bitbucket.org/trintel/py_tsu/src/v0.1.0/
+```
+
+Using `pip` with `uv`:
+
+```bash
+uv pip install git+https://bitbucket.org/trintel/py_tsu/src/v0.1.0/
+```
+
+Using `pip`:
+
+```bash
+pip install git+https://bitbucket.org/trintel/py_tsu/src/v0.1.0/
+```

none_shall_parse-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+none_shall_parse/__init__.py,sha256=fQoiVT7cbs948QuGfgYdD5zlWqk0Coe29kSEzKu595s,198
+none_shall_parse/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+none_shall_parse/utils/lists.py,sha256=IndbwxaxvByFtW88AtHyNOTDDp-E1EWLz_KY7OCcBIU,1712
+none_shall_parse/utils/parsing.py,sha256=99A_Xo3n2I2zGsgJcobjRPhgNOO1HytpZHs_hmr7t2c,6878
+none_shall_parse/utils/strings.py,sha256=_fvsQtUyjqmPj_c4NjeOsAPrd5LOzNb4SX16-ZyZIEA,3511
+none_shall_parse-0.1.0.dist-info/WHEEL,sha256=Jb20R3Ili4n9P1fcwuLup21eQ5r9WXhs4_qy7VTrgPI,79
+none_shall_parse-0.1.0.dist-info/METADATA,sha256=SF9OyXdZfJXiE--cMyMP5gzMZJoXAcKP5ERGQ1SDhus,1304
+none_shall_parse-0.1.0.dist-info/RECORD,,

none_shall_parse-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.8.15
+Root-Is-Purelib: true
+Tag: py3-none-any