extended-data-types 1.0.0__py3-none-any.whl

extended_data_types/matcher_utils.py

@@ -0,0 +1,68 @@
+"""This module provides utilities for string and value matching.
+
+It includes functions to partially match strings and to compare non-empty values
+for equality, handling different data types including strings, mappings, and lists.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+from .json_utils import encode_json
+from .state_utils import is_nothing
+
+
+def is_partial_match(
+    a: str | None,
+    b: str | None,
+    check_prefix_only: bool = False,
+) -> bool:
+    """Checks if two strings partially match.
+
+    Args:
+        a (str | None): The first string.
+        b (str | None): The second string.
+        check_prefix_only (bool): Whether to check only the prefix.
+
+    Returns:
+        bool: True if there is a partial match, False otherwise.
+    """
+    if is_nothing(a) or is_nothing(b):
+        return False
+
+    a = a.casefold() if a is not None else ""
+    b = b.casefold() if b is not None else ""
+
+    if check_prefix_only:
+        return a.startswith(b) or b.startswith(a)
+
+    return a in b or b in a
+
+
+def is_non_empty_match(a: Any, b: Any) -> bool:
+    """Checks if two non-empty values match.
+
+    Args:
+        a (Any): The first value.
+        b (Any): The second value.
+
+    Returns:
+        bool: True if the values match, False otherwise.
+    """
+    if is_nothing(a) or is_nothing(b):
+        return False
+
+    if not isinstance(a, type(b)):
+        return False
+
+    if isinstance(a, str):
+        a = a.casefold()
+        b = b.casefold()
+    elif isinstance(a, Mapping):
+        a = encode_json(a, sort_keys=True)
+        b = encode_json(b, sort_keys=True)
+    elif isinstance(a, list):
+        a.sort()
+        b.sort()
+
+    return bool(a == b)

extended_data_types/splitter_utils.py

@@ -0,0 +1,54 @@
+"""This module contains utility functions for splitting lists and dictionaries by the type of their items.
+
+It includes functions `split_list_by_type` and `split_dict_by_type` which categorize elements
+based on their type and return defaultdict of type list or dict respectively.
+
+Functions:
+    - split_list_by_type: Splits a list by the type of its items.
+    - split_dict_by_type: Splits a dictionary by the type of its values.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from typing import Any
+
+from .type_utils import typeof
+
+
+def split_list_by_type(
+    input_list: list[Any], primitive_only: bool = False
+) -> defaultdict[type, list[Any]]:
+    """Split a list by the type of its items, with an option to categorize by primitive types only.
+
+    Args:
+        input_list (List[Any]): The list to split.
+        primitive_only (bool): If True, categorize items based on primitive types (int, float, str, etc.)
+        rather than their exact type.
+
+    Returns:
+        DefaultDict[type, List[Any]]: A defaultdict storing lists of elements categorized by their type.
+    """
+    result: defaultdict[type, list[Any]] = defaultdict(list)
+    for item in input_list:
+        result[typeof(item, primitive_only=primitive_only)].append(item)
+    return result
+
+
+def split_dict_by_type(
+    input_dict: dict[Any, Any], primitive_only: bool = False
+) -> defaultdict[type, dict[Any, Any]]:
+    """Split a dictionary by the type of its values, with an option to categorize by primitive types only.
+
+    Args:
+        input_dict (Dict[Any, Any]): The dictionary to split.
+        primitive_only (bool): If True, categorize values based on primitive types (int, float, str, etc.)
+        rather than their exact type.
+
+    Returns:
+        DefaultDict[type, Dict[Any, Any]]: A defaultdict storing dictionaries of elements categorized by their type.
+    """
+    result: defaultdict[type, dict[Any, Any]] = defaultdict(dict)
+    for key, value in input_dict.items():
+        result[typeof(value, primitive_only=primitive_only)][key] = value
+    return result

extended_data_types/stack_utils.py

@@ -0,0 +1,87 @@
+"""This module provides utilities for inspecting the call stack and methods of classes.
+
+It includes functions to get the caller's name, filter methods, and retrieve available
+methods and their docstrings for a class.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from inspect import getmembers, ismethod
+from typing import Any
+
+
+def get_caller() -> str:
+    """Gets the name of the caller function.
+
+    Returns:
+        str: The name of the caller function.
+    """
+    return sys._getframe(2).f_code.co_name  # noqa: SLF001
+
+
+def get_unique_signature(obj: Any, delim: str = "/") -> str:
+    """Generate a unique signature for an object based on its class and module.
+
+    Args:
+        obj (Any): The object to generate a signature for.
+        delim (str): The delimiter to use between the module and class names. Defaults to "/".
+
+    Returns:
+        str: A unique signature string for the object.
+    """
+    return str(obj.__class__.__module__) + delim + str(obj.__class__.__name__)
+
+
+def filter_methods(methods: list[str]) -> list[str]:
+    """Filters out private methods from a list of method names.
+
+    Args:
+        methods (list[str]): The list of method names to filter.
+
+    Returns:
+        list[str]: The filtered list of method names.
+    """
+    return [method for method in methods if not method.startswith("_")]
+
+
+def get_available_methods(cls: type[Any]) -> dict[str, str | None]:
+    """Gets available methods and their docstrings for a class.
+
+    An "available method" is a public method that:
+    - Does not contain '__' in its name.
+    - Belongs to the same module as the class.
+    - Does not have 'NOPARSE' in its docstring.
+
+    Args:
+        cls (type[Any]): The class to inspect.
+
+    Returns:
+        dict[str, str | None]: A dictionary of method names and their docstrings.
+    """
+    module_name = cls.__class__.__module__
+    methods = getmembers(cls, ismethod)
+
+    return {
+        method_name: method_signature.__doc__
+        for method_name, method_signature in methods
+        if "__" not in method_name
+        and method_signature.__self__.__class__.__module__ == module_name
+        and "NOPARSE" not in (method_signature.__doc__ or "")
+    }
+
+
+def current_python_version_is_at_least(minor: int, major: int = 3) -> bool:
+    """Checks if the current Python version is at least the specified version.
+
+    Args:
+        minor (int): The minimum minor version.
+        major (int, optional): The minimum major version. Defaults to 3.
+
+    Returns:
+        bool: True if the current Python version is at least the specified version, False otherwise.
+    """
+    return (sys.version_info.major > major) or (
+        sys.version_info.major == major and sys.version_info.minor >= minor
+    )

extended_data_types/state_utils.py

@@ -0,0 +1,169 @@
+"""The `state_utils` module provides utility functions for handling and evaluating data structure "emptiness".
+
+It includes functions to determine whether a value is considered "nothing", to extract
+non-empty values, and to assess the state of provided arguments and keyword arguments.
+
+Functions:
+    - is_nothing: Determines if a value is considered "nothing" (e.g., None, empty string, empty list, empty dict).
+    - are_nothing: Checks if all provided values (both positional and keyword arguments) are "nothing".
+    - all_non_empty: Returns all non-empty values from provided arguments and keyword arguments.
+    - all_non_empty_in_list: Returns a list of non-empty values from the provided list.
+    - all_non_empty_in_dict: Returns a dictionary of non-empty values from the provided dictionary.
+    - first_non_empty: Retrieves the first non-empty value from a set of provided values.
+    - any_non_empty: Retrieves the first non-empty value from a mapping for a given set of keys.
+    - yield_non_empty: Yields non-empty values from a mapping for a given set of keys.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Generator
+
+
+def is_nothing(v: Any) -> bool:
+    """Checks if a value is considered 'nothing'.
+
+    Args:
+        v (Any): The value to check.
+
+    Returns:
+        bool: True if the value is considered 'nothing', False otherwise.
+    """
+    if v in [None, "", {}, []]:
+        return True
+
+    if str(v) == "" or str(v).isspace():
+        return True
+
+    if isinstance(v, (list, set)):
+        v = [vv for vv in v if vv not in [None, "", {}, []]]
+        if len(v) == 0:
+            return True
+
+    return False
+
+
+def are_nothing(*args: Any, **kwargs: Any) -> bool:
+    """Checks if all provided values (both args and kwargs) are considered 'nothing'.
+
+    Args:
+        args (Any): Positional arguments to check.
+        kwargs (Any): Keyword arguments to check.
+
+    Returns:
+        bool: True if all values are considered 'nothing', False otherwise.
+    """
+    non_empty = all_non_empty(*args, **kwargs)
+
+    if non_empty is None:
+        return True
+
+    if isinstance(non_empty, (list, dict)):
+        return len(non_empty) == 0
+
+    if isinstance(non_empty, tuple):
+        list_part, dict_part = non_empty
+        return len(list_part) == 0 and len(dict_part) == 0
+
+    return False
+
+
+def all_non_empty(
+    *args: Any, **kwargs: Any
+) -> list[Any] | dict[str, Any] | tuple[list[Any], dict[str, Any]] | None:
+    """Returns all non-empty values from the provided args and kwargs.
+
+    Args:
+        args (Any): Positional arguments to check.
+        kwargs (Any): Keyword arguments to check.
+
+    Returns:
+        Union[List[Any], Dict[str, Any], Tuple[List[Any], Dict[str, Any]], None]:
+            A list, dict, tuple of list
+    """
+    if len(args) == 0 and len(kwargs) == 0:
+        return None
+
+    if len(args) == 0:
+        return all_non_empty_in_dict(dict(kwargs))
+
+    results = all_non_empty_in_list(list(args))
+    if len(kwargs) == 0:
+        return results
+
+    return results, all_non_empty_in_dict(dict(kwargs))
+
+
+def all_non_empty_in_list(input_list: list[Any]) -> list[Any]:
+    """Returns a list of all non-empty values from the input list.
+
+    Args:
+        input_list (List[Any]): A list of items to check for emptiness.
+
+    Returns:
+        List: A list of non-empty values.
+    """
+    return [item for item in input_list if not is_nothing(item)]
+
+
+def all_non_empty_in_dict(input_dict: dict[Any, Any]) -> dict[Any, Any]:
+    """Returns a dictionary of all non-empty values from the input dictionary.
+
+    Args:
+        input_dict (Dict[Any, Any]): A dictionary of items to check for emptiness.
+
+    Returns:
+        Dict: A dictionary of non-empty values.
+    """
+    return {key: value for key, value in input_dict.items() if not is_nothing(value)}
+
+
+def first_non_empty(*vals: Any) -> Any:
+    """Returns the first non-empty value.
+
+    Args:
+        vals (Any): The values to check.
+
+    Returns:
+        Any: The first non-empty value, or None if all are 'nothing'.
+    """
+    non_empty_vals = all_non_empty(*vals)
+    return (
+        non_empty_vals[0]
+        if isinstance(non_empty_vals, list) and non_empty_vals
+        else None
+    )
+
+
+def any_non_empty(m: dict[Any, Any], *keys: Any) -> dict[Any, Any]:
+    """Returns the first non-empty value from a mapping for the given keys.
+
+    Args:
+        m (Dict): The mapping to check.
+        keys (Any): The keys to check.
+
+    Returns:
+        Dict[Any, Any]: A mapping containing the first non-empty value.
+    """
+    for k in keys:
+        v = m.get(k)
+        if not is_nothing(v):
+            return {k: v}
+    return {}
+
+
+def yield_non_empty(
+    m: dict[Any, Any], *keys: Any
+) -> Generator[dict[Any, Any], None, None]:
+    """Yields non-empty values from a mapping for the given keys.
+
+    Args:
+        m (Dict): The mapping to check.
+        keys (Any): The keys to check.
+
+    Yields:
+        Generator[Dict[Any, Any], None, None]: A generator yielding non-empty values.
+    """
+    for k in keys:
+        v = m.get(k)
+        if not is_nothing(v):
+            yield {k: v}

extended_data_types/string_data_type.py

@@ -0,0 +1,161 @@
+"""This module provides utilities for string manipulation and validation.
+
+It includes functions to sanitize keys, truncate messages, manipulate character
+cases, validate URLs, convert camelCase to TitleCase, and convert string representations
+of truth to boolean values.
+"""
+
+from __future__ import annotations
+
+import inflection
+import validators
+
+from .stack_utils import current_python_version_is_at_least
+
+
+def sanitize_key(key: str, delim: str = "_") -> str:
+    """Sanitizes a key by replacing non-alphanumeric characters with a delimiter.
+
+    Args:
+        key (str): The key to sanitize.
+        delim (str): The delimiter to replace non-alphanumeric characters with. Defaults to "_".
+
+    Returns:
+        str: The sanitized key.
+    """
+    return "".join(x if (x.isalnum() or x == delim) else delim for x in key)
+
+
+def truncate(msg: str, max_length: int, ender: str = "...") -> str:
+    """Truncates a message to a maximum length, appending an ender if truncated.
+
+    Args:
+        msg (str): The message to truncate.
+        max_length (int): The maximum length of the truncated message.
+        ender (str): The string to append to the truncated message. Defaults to "...".
+
+    Returns:
+        str: The truncated message.
+    """
+    if len(msg) <= max_length:
+        return msg
+    return msg[: max_length - len(ender)] + ender
+
+
+def lower_first_char(inp: str) -> str:
+    """Converts the first character of a string to lowercase.
+
+    Args:
+        inp (str): The input string.
+
+    Returns:
+        str: The string with the first character in lowercase.
+    """
+    return inp[:1].lower() + inp[1:] if inp else ""
+
+
+def upper_first_char(inp: str) -> str:
+    """Converts the first character of a string to uppercase.
+
+    Args:
+        inp (str): The input string.
+
+    Returns:
+        str: The string with the first character in uppercase.
+    """
+    return inp[:1].upper() + inp[1:] if inp else ""
+
+
+def is_url(url: str) -> bool:
+    """Checks if the given string is a valid URL.
+
+    Args:
+        url (str): The string to check.
+
+    Returns:
+        bool: True if the file path is a valid URL, False otherwise.
+    """
+    return validators.url(url.strip()) is True
+
+
+def titleize_name(name: str) -> str:
+    """Converts a camelCase name to a TitleCase name.
+
+    Args:
+        name (str): The camelCase name.
+
+    Returns:
+        str: The TitleCase name.
+    """
+    return inflection.titleize(inflection.underscore(name))
+
+
+def strtobool(val: str | bool | None, raise_on_error: bool = False) -> bool | None:
+    """Converts a string representation of truth to boolean.
+
+    Args:
+        val (str | bool | None): The value to convert.
+        raise_on_error (bool): Whether to raise an error on invalid value. Defaults to False.
+
+    Returns:
+        bool | None: The converted boolean value, or None if invalid and raise_on_error is False.
+    """
+    if isinstance(val, bool) or val is None:
+        return val
+
+    if isinstance(val, str):
+        val = val.lower()
+        if val in ("y", "yes", "t", "true", "on", "1"):
+            return True
+        if val in ("n", "no", "f", "false", "off", "0"):
+            return False
+
+    if raise_on_error:
+        error_msg = f"invalid truth value {val!r}"
+        raise ValueError(error_msg)
+
+    return None
+
+
+def removeprefix(string: str, prefix: str) -> str:
+    """Removes the specified prefix from the string if present.
+
+    For Python versions less than 3.9, the function mimics the behavior of
+    str.removeprefix.
+
+    Args:
+        string (str): The string from which to remove the prefix.
+        prefix (str): The prefix to remove.
+
+    Returns:
+        str: The string with the prefix removed if it was present, otherwise the original string.
+    """
+    if current_python_version_is_at_least(9):
+        return string.removeprefix(prefix)
+
+    if prefix and string.startswith(prefix):
+        string = string[len(prefix) :]
+
+    return string
+
+
+def removesuffix(string: str, suffix: str) -> str:
+    """Removes the specified suffix from the string if present.
+
+    For Python versions less than 3.9, the function mimics the behavior of
+    str.removesuffix.
+
+    Args:
+        string (str): The string from which to remove the suffix.
+        suffix (str): The suffix to remove.
+
+    Returns:
+        str: The string with the suffix removed if it was present, otherwise the original string.
+    """
+    if current_python_version_is_at_least(9):
+        return string.removesuffix(suffix)
+
+    if suffix and string.endswith(suffix):
+        string = string[: -len(suffix)]
+
+    return string

extended_data_types/type_utils.py

@@ -0,0 +1,67 @@
+"""Type Utilities.
+
+This module provides utility functions related to Python types, specifically for retrieving
+default values based on the type. It includes functions for getting default values for common
+types like lists, dictionaries, and strings, and for determining whether to return primitive
+or exact types of a given value.
+
+Functions:
+    - get_default_value_for_type: Returns the default value for a given type.
+    - get_primitive_type_for_instance_type: Returns the primitive type for a given value.
+    - typeof: Returns the type (or primitive type) of a given value.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def get_default_value_for_type(input_type: type) -> Any:
+    """Returns the default value for a given type.
+
+    Args:
+        input_type (type): The type to get the default value for.
+
+    Returns:
+        Any: The default value for the given type.
+    """
+    if input_type is list:
+        return []
+    if input_type is dict:
+        return {}
+    if input_type is str:
+        return ""
+    return None
+
+
+def get_primitive_type_for_instance_type(value: Any) -> type:
+    """Gets the primitive type for a given value.
+
+    Args:
+        value (Any): The value to match.
+
+    Returns:
+        type: The primitive type for the given value.
+    """
+    if isinstance(value, (bool, int, float, str, bytes, bytearray)):
+        return type(value)
+    if isinstance(value, (list, tuple)):
+        return list
+    if isinstance(value, dict):
+        return dict
+    if isinstance(value, (set, frozenset)):
+        return set
+    return type(None) if value is None else object
+
+
+def typeof(item: Any, primitive_only: bool = False) -> type:
+    """Determines either the primitive or exact type of a given value.
+
+    Args:
+        item (Any): The value to determine the type of.
+        primitive_only (bool): Whether to return the primitive type.
+
+    Returns:
+        type: The type (or primitive type) of the value.
+    """
+    return get_primitive_type_for_instance_type(item) if primitive_only else type(item)

extended_data_types/yaml_utils/__init__.py

@@ -0,0 +1,31 @@
+"""This module provides utilities for handling YAML data.
+
+It includes custom loaders, dumpers, and utility functions for working with YAML.
+"""
+
+from .constructors import yaml_construct_pairs, yaml_construct_undefined
+from .dumpers import PureDumper
+from .loaders import PureLoader
+from .representers import (
+    yaml_represent_pairs,
+    yaml_represent_tagged,
+    yaml_str_representer,
+)
+from .tag_classes import YamlPairs, YamlTagged
+from .utils import decode_yaml, encode_yaml, is_yaml_data
+
+
+__all__ = [
+    "YamlTagged",
+    "YamlPairs",
+    "PureLoader",
+    "PureDumper",
+    "decode_yaml",
+    "encode_yaml",
+    "is_yaml_data",
+    "yaml_construct_undefined",
+    "yaml_construct_pairs",
+    "yaml_represent_tagged",
+    "yaml_represent_pairs",
+    "yaml_str_representer",
+]

extended_data_types/yaml_utils/constructors.py

@@ -0,0 +1,58 @@
+"""This module provides constructors for custom YAML tags and types.
+
+It includes functions to construct undefined YAML tags and YAML pairs.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from yaml import MappingNode, SafeLoader, ScalarNode, SequenceNode
+
+from .tag_classes import YamlPairs, YamlTagged
+
+
+def yaml_construct_undefined(
+    loader: SafeLoader,
+    node: ScalarNode | SequenceNode | MappingNode,
+) -> YamlTagged:
+    """Construct a YAML tagged object for undefined tags.
+
+    Args:
+        loader (SafeLoader): The YAML loader.
+        node (ScalarNode | SequenceNode | MappingNode): The YAML node.
+
+    Returns:
+        YamlTagged: The constructed YAML tagged object.
+    """
+    value: Any
+    if isinstance(node, ScalarNode):
+        value = loader.construct_scalar(node)
+    elif isinstance(node, SequenceNode):
+        value = loader.construct_sequence(node)
+    elif isinstance(node, MappingNode):
+        value = loader.construct_mapping(node)
+    else:
+        node_type = type(node).__name__
+        raise TypeError(f"Unexpected node type: {node_type}")  # noqa: TRY003, EM102
+    return YamlTagged(node.tag, value)
+
+
+def yaml_construct_pairs(
+    loader: SafeLoader,
+    node: MappingNode,
+) -> dict[Any, Any] | YamlPairs:
+    """Construct YAML pairs.
+
+    Args:
+        loader (SafeLoader): The YAML loader.
+        node (MappingNode): The YAML mapping node.
+
+    Returns:
+        Union[Dict[Any, Any], YamlPairs]: The constructed YAML pairs.
+    """
+    value: list[tuple[Any, Any]] = loader.construct_pairs(node)  # type: ignore[no-untyped-call]
+    try:
+        return dict(value)
+    except TypeError:
+        return YamlPairs(value)