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

extended_data_types/__init__.py

@@ -0,0 +1,90 @@
+"""Extended Data Types Library.
+
+This library provides extended functionality for handling various data types in Python.
+It includes utilities for YAML, JSON, Base64, file paths, strings, lists, maps, and more.
+"""
+
+from __future__ import annotations
+
+from .base64_utils import base64_encode
+from .export_utils import wrap_raw_data_for_export
+from .hcl2_utils import decode_hcl2
+from .json_utils import decode_json, encode_json
+from .list_data_type import filter_list, flatten_list
+from .map_data_type import (
+    all_values_from_map,
+    deduplicate_map,
+    filter_map,
+    first_non_empty_value_from_map,
+    flatten_map,
+    get_default_dict,
+    unhump_map,
+    zipmap,
+)
+from .matcher_utils import is_non_empty_match, is_partial_match
+from .splitter_utils import split_dict_by_type, split_list_by_type
+from .stack_utils import filter_methods, get_available_methods, get_caller
+from .state_utils import (
+    all_non_empty,
+    all_non_empty_in_dict,
+    all_non_empty_in_list,
+    any_non_empty,
+    are_nothing,
+    first_non_empty,
+    is_nothing,
+    yield_non_empty,
+)
+from .string_data_type import (
+    is_url,
+    lower_first_char,
+    sanitize_key,
+    strtobool,
+    titleize_name,
+    truncate,
+    upper_first_char,
+)
+from .yaml_utils import decode_yaml, encode_yaml, is_yaml_data
+
+
+__all__ = [
+    "base64_encode",
+    "wrap_raw_data_for_export",
+    "decode_hcl2",
+    "decode_json",
+    "encode_json",
+    "flatten_list",
+    "filter_list",
+    "first_non_empty_value_from_map",
+    "deduplicate_map",
+    "all_values_from_map",
+    "flatten_map",
+    "zipmap",
+    "get_default_dict",
+    "unhump_map",
+    "filter_map",
+    "is_partial_match",
+    "is_non_empty_match",
+    "is_nothing",
+    "all_non_empty",
+    "all_non_empty_in_list",
+    "all_non_empty_in_dict",
+    "are_nothing",
+    "first_non_empty",
+    "any_non_empty",
+    "yield_non_empty",
+    "split_list_by_type",
+    "split_dict_by_type",
+    "get_caller",
+    "filter_methods",
+    "get_available_methods",
+    "sanitize_key",
+    "truncate",
+    "lower_first_char",
+    "upper_first_char",
+    "is_url",
+    "titleize_name",
+    "strtobool",
+    "decode_yaml",
+    "encode_yaml",
+    "is_yaml_data",
+]

extended_data_types/base64_utils.py

@@ -0,0 +1,53 @@
+"""This module provides utilities for encoding and decoding data to and from Base64 format.
+
+It includes functions to encode data to Base64 strings, with optional data
+wrapping for export, and to decode Base64 strings back to their original data.
+"""
+
+from __future__ import annotations
+
+from base64 import b64decode, b64encode
+
+from .export_utils import wrap_raw_data_for_export
+from .import_utils import unwrap_raw_data_from_import
+
+
+def base64_encode(raw_data: str | bytes, wrap_raw_data: bool = True) -> str:
+    """Encodes data to base64 format.
+
+    Args:
+        raw_data (str | bytes): The data to encode.
+        wrap_raw_data (bool): Whether to wrap the raw data for export.
+
+    Returns:
+        str: The base64 encoded string.
+    """
+    if wrap_raw_data:
+        if isinstance(raw_data, bytes):
+            raw_data = raw_data.decode("utf-8")
+        raw_data = wrap_raw_data_for_export(raw_data).encode("utf-8")
+    elif isinstance(raw_data, str):
+        raw_data = raw_data.encode("utf-8")
+
+    return b64encode(raw_data).decode("utf-8")
+
+
+def base64_decode(
+    encoded_data: str,
+    unwrap_raw_data: bool = True,
+    encoding: str = "yaml",
+) -> str | bytes:
+    """Decodes data from base64 format.
+
+    Args:
+        encoded_data (str): The base64 encoded string to decode.
+        unwrap_raw_data (bool): Whether to unwrap the raw data after decoding.
+        encoding (str): The encoding format used for wrapping (default is 'yaml').
+
+    Returns:
+        str | bytes: The decoded data, as a string if unwrapped, otherwise as bytes.
+    """
+    decoded_data = b64decode(encoded_data).decode("utf-8")
+    if unwrap_raw_data:
+        decoded_data = unwrap_raw_data_from_import(decoded_data, encoding=encoding)
+    return decoded_data

extended_data_types/export_utils.py

@@ -0,0 +1,98 @@
+"""This module provides utilities for exporting raw data in various formats.
+
+It includes functions to make raw data export-safe and to wrap raw data for export
+with optional encoding formats such as YAML or JSON.
+"""
+
+from __future__ import annotations
+
+import datetime
+import pathlib
+
+from typing import Any, Mapping
+
+from .json_utils import encode_json
+from .string_data_type import strtobool
+from .yaml_utils import YamlPairs, YamlTagged, encode_yaml, is_yaml_data
+
+
+def make_raw_data_export_safe(raw_data: Any, export_to_yaml: bool = False) -> Any:
+    """Makes raw data export safe by converting certain types to strings.
+
+    Args:
+        raw_data (Any): The raw data to process.
+        export_to_yaml (bool): Flag to indicate if the data is for YAML export.
+
+    Returns:
+        Any: The processed data.
+    """
+    if isinstance(raw_data, Mapping):
+        return {
+            k: make_raw_data_export_safe(v, export_to_yaml=export_to_yaml)
+            for k, v in raw_data.items()
+        }
+    if isinstance(raw_data, (set, list)):
+        return [
+            make_raw_data_export_safe(v, export_to_yaml=export_to_yaml)
+            for v in raw_data
+        ]
+
+    if isinstance(raw_data, YamlTagged):
+        raw_data = raw_data.__wrapped__
+    elif isinstance(raw_data, YamlPairs):
+        raw_data = list(raw_data)
+
+    if isinstance(raw_data, (datetime.date, datetime.datetime)):
+        return raw_data.isoformat()
+    if isinstance(raw_data, pathlib.Path):
+        return str(raw_data)
+    if isinstance(raw_data, (int, float, str, bool, type(None))):
+        return raw_data
+
+    # For all other types, convert to string representation
+    return str(raw_data)
+
+
+def wrap_raw_data_for_export(
+    raw_data: Mapping[str, Any] | Any,
+    allow_encoding: bool | str = True,
+    **format_opts: Any,
+) -> str:
+    """Wraps raw data for export, optionally encoding it.
+
+    Args:
+        raw_data (Mapping[str, Any] | Any): The raw data to wrap.
+        allow_encoding (bool | str): The encoding format or flag (default is 'yaml').
+        format_opts (Any): Additional options for formatting the output.
+
+    Returns:
+        str: The wrapped and encoded data.
+    """
+    raw_data = make_raw_data_export_safe(raw_data)
+
+    if isinstance(allow_encoding, str):
+        allow_encoding_lower = allow_encoding.casefold()
+        if allow_encoding_lower == "yaml":
+            return encode_yaml(raw_data)
+        if allow_encoding_lower == "json":
+            return encode_json(raw_data, **format_opts)
+        if allow_encoding_lower == "raw":
+            return str(raw_data)
+
+        try:
+            allow_encoding_bool = strtobool(allow_encoding, raise_on_error=True)
+            allow_encoding = (
+                allow_encoding_bool
+                if isinstance(allow_encoding_bool, bool)
+                else allow_encoding
+            )
+        except ValueError as e:
+            error_message = f"Invalid allow_encoding value: {allow_encoding}"
+            raise ValueError(error_message) from e
+
+    if allow_encoding:
+        if is_yaml_data(raw_data):
+            return encode_yaml(raw_data)
+        return encode_json(raw_data, **format_opts)
+
+    return str(raw_data)

extended_data_types/hcl2_utils.py

@@ -0,0 +1,52 @@
+"""This module provides utilities for decoding and encoding HCL2 data.
+
+It includes functions to decode HCL2 strings into Python objects with appropriate
+error handling, and to encode Python objects into HCL2 strings.
+
+Credits:
+    The approach for encoding HCL2 data is inspired by Nicolai Antiferov's article:
+    https://nklya.medium.com/how-to-write-hcl2-from-python-53ac12e45874
+"""
+
+from __future__ import annotations
+
+import json
+
+from io import StringIO
+from typing import Any
+
+import hcl2
+
+from lark.exceptions import UnexpectedToken
+
+
+def decode_hcl2(hcl2_data: str) -> Any:
+    """Decodes HCL2 data into a Python object.
+
+    Args:
+        hcl2_data (str): The HCL2 data to decode.
+
+    Returns:
+        Any: The decoded Python object.
+
+    Raises:
+        ValueError: If the HCL2 data cannot be parsed.
+    """
+    hcl2_data_stream = StringIO(hcl2_data)
+    try:
+        return hcl2.load(hcl2_data_stream)  # type: ignore[attr-defined]
+    except UnexpectedToken as e:
+        error_message = f"Invalid HCL2 data: {e}"
+        raise ValueError(error_message) from e
+
+
+def encode_hcl2(data: Any) -> str:
+    """Encodes a Python object into an HCL2 string.
+
+    Args:
+        data (Any): The Python object to encode.
+
+    Returns:
+        str: The encoded HCL2 string.
+    """
+    return json.dumps(data, indent=2, separators=(",", " = "))

extended_data_types/import_utils.py

@@ -0,0 +1,26 @@
+"""This module provides utilities for unwrapping data after import."""
+
+from typing import Any
+
+from .json_utils import decode_json
+from .yaml_utils import decode_yaml
+
+
+def unwrap_raw_data_from_import(wrapped_data: str, encoding: str = "yaml") -> Any:
+    """Unwraps the data that was wrapped for import.
+
+    Args:
+        wrapped_data (str): The wrapped data.
+        encoding (str): The encoding format (default is 'yaml').
+
+    Returns:
+        Any: The unwrapped data.
+    """
+    encoding_lower = encoding.casefold()
+    if encoding_lower == "yaml":
+        return decode_yaml(wrapped_data)
+    if encoding_lower == "json":
+        return decode_json(wrapped_data)
+
+    error_message = f"Unsupported encoding format: {encoding}"
+    raise ValueError(error_message)

extended_data_types/json_utils.py

@@ -0,0 +1,35 @@
+"""JSON Utilities Module.
+
+This module provides utilities for encoding and decoding JSON using the standard `json` library.
+"""
+
+from __future__ import annotations
+
+import json
+
+from typing import Any
+
+
+def decode_json(json_data: str) -> Any:
+    """Decodes a JSON string into a Python object using json.
+
+    Args:
+        json_data (str): The JSON string to decode.
+
+    Returns:
+        Any: The decoded Python object.
+    """
+    return json.loads(json_data)
+
+
+def encode_json(raw_data: Any, **format_opts: Any) -> str:
+    """Encodes a Python object into a JSON string using json.
+
+    Args:
+        raw_data (Any): The Python object to encode.
+        format_opts (Any): Options for formatting the JSON output.
+
+    Returns:
+        str: The encoded JSON string.
+    """
+    return json.dumps(raw_data, **format_opts)

extended_data_types/list_data_type.py

@@ -0,0 +1,78 @@
+"""This module provides utilities for handling lists.
+
+It includes functions to flatten lists and to filter lists based on allowlists
+and denylists.
+
+Functions:
+    - flatten_list: Flattens a list of lists into a single list.
+    - filter_list: Filters a list based on allowlist and denylist.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def flatten_list(matrix: list[Any]) -> list[Any]:
+    """Flattens a list of lists into a single list.
+
+    Args:
+        matrix (list[Any]): The list of lists to flatten.
+
+    Returns:
+        list[Any]: The flattened list.
+    """
+
+    def _flatten(lst: list[Any]) -> list[Any]:
+        """Recursively flattens a nested list.
+
+        Args:
+            lst (list[Any]): The list to flatten.
+
+        Returns:
+            list[Any]: The flattened list.
+        """
+        flattened = []
+        for item in lst:
+            if isinstance(item, list):
+                flattened.extend(_flatten(item))
+            else:
+                flattened.append(item)
+        return flattened
+
+    return _flatten(matrix)
+
+
+def filter_list(
+    items: list[str] | None,
+    allowlist: list[str] | None = None,
+    denylist: list[str] | None = None,
+) -> list[str]:
+    """Filters a list based on allowlist and denylist.
+
+    Args:
+        items (list[str] | None): The list to filter.
+        allowlist (list[str] | None): The list of allowed items.
+        denylist (list[str] | None): The list of denied items.
+
+    Returns:
+        list[str]: The filtered list.
+    """
+    if items is None:
+        items = []
+
+    if allowlist is None:
+        allowlist = []
+
+    if denylist is None:
+        denylist = []
+
+    filtered = []
+
+    for elem in items:
+        if (len(allowlist) > 0 and elem not in allowlist) or elem in denylist:
+            continue
+
+        filtered.append(elem)
+
+    return filtered

extended_data_types/map_data_type.py

@@ -0,0 +1,226 @@
+"""This module provides utilities for handling maps (dictionaries).
+
+It includes functions to manipulate, flatten, and filter dictionaries, and to
+convert keys from camelCase to snake_case.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from typing import Any, Mapping, MutableMapping
+
+import inflection
+
+from sortedcontainers import SortedDict
+
+from .export_utils import make_raw_data_export_safe
+
+
+def first_non_empty_value_from_map(m: Mapping[str, Any], *keys: str) -> Any:
+    """Returns the first non-empty value from a map for the given keys.
+
+    Args:
+        m (Mapping[str, Any]): The map to search.
+        keys: The keys to search for.
+
+    Returns:
+        Any: The first non-empty value.
+    """
+    for key in keys:
+        if m.get(key):
+            return m[key]
+    return None
+
+
+def deduplicate_map(m: Mapping[str, Any]) -> dict[str, Any]:
+    """Removes duplicate values from a map.
+
+    Args:
+        m (Mapping[str, Any]): The map to deduplicate.
+
+    Returns:
+        dict[str, Any]: The deduplicated map.
+    """
+    deduplicated_map: dict[str, Any] = make_raw_data_export_safe(m)
+
+    for k, v in m.items():
+        if isinstance(v, list):
+            deduplicated_map[k] = []
+
+            for elem in v:
+                if elem in deduplicated_map[k]:
+                    continue
+
+                deduplicated_map[k].append(elem)
+
+            continue
+
+        if isinstance(v, Mapping):
+            deduplicated_map[k] = deduplicate_map(v)
+            continue
+
+        if k not in deduplicated_map:
+            deduplicated_map[k] = v
+
+    return deduplicated_map
+
+
+def all_values_from_map(m: Mapping[str, Any]) -> list[Any]:
+    """Returns all values from a nested map.
+
+    Args:
+        m (Mapping[str, Any]): The map to retrieve values from.
+
+    Returns:
+        List[Any]: A list of all values.
+    """
+    values = []
+
+    for v in m.values():
+        if isinstance(v, Mapping):
+            values.extend(all_values_from_map(v))
+        elif isinstance(v, list):
+            for item in v:
+                if isinstance(item, Mapping):
+                    values.extend(all_values_from_map(item))
+                else:
+                    values.append(item)
+        else:
+            values.append(v)
+
+    return values
+
+
+def flatten_map(
+    dictionary: Mapping[str, Any],
+    parent_key: str | None = "",
+    separator: str = ".",
+) -> dict[str, Any]:
+    """Flattens a nested dictionary into a flat dictionary.
+
+    Args:
+        dictionary (Mapping[str, Any]): The dictionary to flatten.
+        parent_key (Optional[str]): The string to prepend to dictionary's keys.
+        separator (str): The string used to separate flattened keys.
+
+    Returns:
+        Dict[str, Any]: The flattened dictionary.
+    """
+    items: list[tuple[str, Any]] = []
+    for key, value in dictionary.items():
+        new_key = f"{parent_key}{separator}{key}" if parent_key else key
+        if isinstance(value, MutableMapping):
+            items.extend(flatten_map(value, new_key, separator).items())
+        elif isinstance(value, list):
+            for k, v in enumerate(value):
+                items.extend(flatten_map({str(k): v}, new_key).items())
+        else:
+            items.append((new_key, value))
+    return dict(items)
+
+
+def zipmap(a: list[str], b: list[str]) -> dict[str, str]:
+    """Creates a dictionary from two lists by zipping them together.
+
+    Args:
+        a (List[str]): The first list.
+        b (List[str]): The second list.
+
+    Returns:
+        Dict[str, str]: The resulting dictionary.
+    """
+    zipped = {}
+
+    for idx, val in enumerate(a):
+        if idx >= len(b):
+            break
+
+        zipped[val] = b[idx]
+
+    return zipped
+
+
+def get_default_dict(
+    use_sorted_dict: bool = False,
+    default_type: type[dict[str, Any]] = dict,
+) -> Any:
+    """Returns a default dictionary with nested default dictionaries.
+
+    Args:
+        use_sorted_dict (bool): Whether to use SortedDict for sorting keys.
+        default_type (Type[Dict[str, Any]]): The type of the default dictionary.
+
+    Returns:
+        Any: The default dictionary.
+    """
+
+    def default_factory() -> Any:
+        return SortedDict() if use_sorted_dict else default_type()
+
+    return defaultdict(default_factory)
+
+
+def unhump_map(
+    m: Mapping[str, Any],
+    drop_without_prefix: str | None = None,
+) -> dict[str, Any]:
+    """Converts keys in a dictionary from camelCase to snake_case.
+
+    Args:
+        m (Mapping[str, Any]): The dictionary to convert.
+        drop_without_prefix (Optional[str]): Drop keys without this prefix.
+
+    Returns:
+        Dict[str, Any]: The converted dictionary.
+    """
+    unhumped = {}
+
+    for k, v in m.items():
+        if drop_without_prefix is not None and not k.startswith(drop_without_prefix):
+            continue
+
+        unhumped_key = inflection.underscore(k)
+
+        if isinstance(v, Mapping):
+            unhumped[unhumped_key] = unhump_map(v)
+            continue
+
+        unhumped[unhumped_key] = v
+
+    return unhumped
+
+
+def filter_map(
+    m: Mapping[str, Any] | None,
+    allowlist: list[str] | None = None,
+    denylist: list[str] | None = None,
+) -> tuple[dict[str, Any], dict[str, Any]]:
+    """Filters a map based on allowlist and denylist.
+
+    Args:
+        m (Optional[Mapping[str, Any]]): The map to filter.
+        allowlist (List[str]): The list of allowed keys.
+        denylist (List[str]): The list of denied keys.
+
+    Returns:
+        tuple[Dict[str, Any], Dict[str, Any]]: The filtered and remaining maps.
+    """
+    if m is None:
+        m = {}
+
+    if allowlist is None:
+        allowlist = []
+
+    if denylist is None:
+        denylist = []
+
+    fm = {}
+    rm = {}
+
+    for k, v in m.items():
+        if (len(allowlist) > 0 and k not in allowlist) or k in denylist:
+            rm[k] = v
+        else:
+            fm[k] = v
+
+    return fm, rm