lionherd-core 1.0.0a3__py3-none-any.whl

lionherd_core/ln/_list_call.py

@@ -0,0 +1,110 @@
+# Copyright (c) 2025, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+from collections.abc import Callable, Iterable
+from typing import Any, ParamSpec, TypeVar
+
+from ._to_list import to_list
+
+R = TypeVar("R")
+T = TypeVar("T")
+P = ParamSpec("P")
+
+__all__ = ("lcall",)
+
+
+def lcall(
+    input_: Iterable[T] | T,
+    func: Callable[[T], R] | Iterable[Callable[[T], R]],
+    /,
+    *args: Any,
+    input_flatten: bool = False,
+    input_dropna: bool = False,
+    input_unique: bool = False,
+    input_use_values: bool = False,
+    input_flatten_tuple_set: bool = False,
+    output_flatten: bool = False,
+    output_dropna: bool = False,
+    output_unique: bool = False,
+    output_flatten_tuple_set: bool = False,
+    **kwargs: Any,
+) -> list[R]:
+    """Apply function to each element synchronously with optional input/output processing.
+
+    Args:
+        input_: Items to process
+        func: Callable to apply to each element
+        *args: Positional arguments passed to func
+        input_flatten: Flatten input structures
+        input_dropna: Remove None/undefined from input
+        input_unique: Remove duplicate inputs
+        input_use_values: Extract values from enums/mappings
+        input_flatten_tuple_set: Include tuples/sets in input flattening
+        output_flatten: Flatten output structures
+        output_dropna: Remove None/undefined from output
+        output_unique: Remove duplicate outputs
+        output_flatten_tuple_set: Include tuples/sets in output flattening
+        **kwargs: Keyword arguments passed to func
+
+    Returns:
+        List of results
+
+    Raises:
+        ValueError: If func is not callable or output_unique without flatten/dropna
+        TypeError: If func or input processing fails
+    """
+    # Validate and extract callable function
+    if not callable(func):
+        try:
+            func_list = list(func)
+            if len(func_list) != 1 or not callable(func_list[0]):
+                raise ValueError("func must contain exactly one callable function.")
+            func = func_list[0]
+        except TypeError as e:
+            raise ValueError("func must be callable or iterable with one callable.") from e
+
+    # Validate output processing options
+    if output_unique and not (output_flatten or output_dropna):
+        raise ValueError("output_unique requires output_flatten or output_dropna.")
+
+    # Process input based on sanitization flag
+    if input_flatten or input_dropna:
+        input_ = to_list(
+            input_,
+            flatten=input_flatten,
+            dropna=input_dropna,
+            unique=input_unique,
+            flatten_tuple_set=input_flatten_tuple_set,
+            use_values=input_use_values,
+        )
+    else:
+        if not isinstance(input_, list):
+            try:
+                input_ = list(input_)
+            except TypeError:
+                input_ = [input_]
+
+    # Process elements and collect results
+    out = []
+    append = out.append
+
+    for item in input_:
+        try:
+            result = func(item, *args, **kwargs)
+            append(result)
+        except InterruptedError:
+            return out
+        except Exception:
+            raise
+
+    # Apply output processing if requested
+    if output_flatten or output_dropna:
+        out = to_list(
+            out,
+            flatten=output_flatten,
+            dropna=output_dropna,
+            unique=output_unique,
+            flatten_tuple_set=output_flatten_tuple_set,
+        )
+
+    return out

lionherd_core/ln/_to_dict.py

@@ -0,0 +1,373 @@
+# Copyright (c) 2025, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import contextlib
+import dataclasses
+from collections.abc import Callable, Iterable, Mapping, Sequence
+from enum import Enum as _Enum
+from typing import Any, cast
+
+import orjson
+
+from ..libs.string_handlers._fuzzy_json import fuzzy_json
+
+
+def _is_na(obj: Any) -> bool:
+    """None / Pydantic undefined sentinels -> treat as NA."""
+    if obj is None:
+        return True
+    # Avoid importing pydantic types; match by typename to stay lightweight
+    tname = type(obj).__name__
+    return tname in {
+        "Undefined",
+        "UndefinedType",
+        "PydanticUndefined",
+        "PydanticUndefinedType",
+    }
+
+
+def _enum_class_to_dict(enum_cls: type[_Enum], use_enum_values: bool) -> dict[str, Any]:
+    members = dict(enum_cls.__members__)  # cheap, stable
+    if use_enum_values:
+        return {k: v.value for k, v in members.items()}
+    return {k: v for k, v in members.items()}
+
+
+def _parse_str(
+    s: str,
+    *,
+    fuzzy_parse: bool,
+    parser: Callable[[str], Any] | None,
+    **kwargs: Any,
+) -> Any:
+    """Parse str -> Python object (JSON only).
+
+    Keep imports local to avoid cold start overhead.
+    """
+    if parser is not None:
+        return parser(s, **kwargs)
+
+    # JSON path
+    if fuzzy_parse:
+        # If the caller supplied a fuzzy parser in scope, use it; otherwise fallback.
+        # We intentionally do not import anything heavy here.
+        with contextlib.suppress(NameError):
+            return fuzzy_json(s, **kwargs)  # type: ignore[name-defined]
+    # orjson.loads() doesn't accept kwargs like parse_float, object_hook, etc.
+    return orjson.loads(s)
+
+
+def _object_to_mapping_like(
+    obj: Any,
+    *,
+    prioritize_model_dump: bool = False,
+    **kwargs: Any,
+) -> Mapping | dict | Any:
+    """
+    Convert 'custom' objects to mapping-like, if possible.
+    Order:
+      1) Pydantic v2 'model_dump' (duck-typed)
+      2) Common methods: to_dict, dict, to_json/json (parsed if string)
+      3) Dataclass
+      4) __dict__
+      5) dict(obj)
+    """
+    # 1) Pydantic v2
+    if prioritize_model_dump and hasattr(obj, "model_dump"):
+        return obj.model_dump(**kwargs)
+
+    # 2) Common methods
+    for name in ("to_dict", "dict", "to_json", "json", "model_dump"):
+        if hasattr(obj, name):
+            res = getattr(obj, name)(**kwargs)
+            return orjson.loads(res) if isinstance(res, str) else res
+
+    # 3) Dataclass
+    if dataclasses.is_dataclass(obj) and not isinstance(obj, type):
+        # asdict is already recursive; keep it (fast enough & simple)
+        return dataclasses.asdict(obj)  # type: ignore[arg-type]
+
+    # 4) __dict__
+    if hasattr(obj, "__dict__"):
+        return obj.__dict__
+
+    # 5) Try dict() fallback
+    return dict(obj)  # may raise -> handled by caller
+
+
+def _enumerate_iterable(it: Iterable) -> dict[int, Any]:
+    return {i: v for i, v in enumerate(it)}
+
+
+# ---------------------------------------
+# Recursive pre-processing (single pass)
+# ---------------------------------------
+
+
+def _preprocess_recursive(
+    obj: Any,
+    *,
+    depth: int,
+    max_depth: int,
+    recursive_custom_types: bool,
+    str_parse_opts: dict[str, Any],
+    prioritize_model_dump: bool,
+) -> Any:
+    """
+    Recursively process nested structures:
+      - Parse strings (JSON only, or custom parser)
+      - Recurse into dict/list/tuple/set/etc.
+      - If recursive_custom_types=True, convert custom objects to mapping-like then continue
+    Containers retain their original types (dict stays dict, list stays list, set stays set, etc.)
+    """
+    if depth >= max_depth:
+        return obj
+
+    # Fast paths by exact type where possible
+    t = type(obj)
+
+    # Strings: try to parse; on failure, keep as-is
+    if t is str:
+        with contextlib.suppress(Exception):
+            return _preprocess_recursive(
+                _parse_str(obj, **str_parse_opts),
+                depth=depth + 1,
+                max_depth=max_depth,
+                recursive_custom_types=recursive_custom_types,
+                str_parse_opts=str_parse_opts,
+                prioritize_model_dump=prioritize_model_dump,
+            )
+        return obj
+
+    # Dict-like
+    if isinstance(obj, Mapping):
+        # Recurse only into values (keys kept as-is)
+        return {
+            k: _preprocess_recursive(
+                v,
+                depth=depth + 1,
+                max_depth=max_depth,
+                recursive_custom_types=recursive_custom_types,
+                str_parse_opts=str_parse_opts,
+                prioritize_model_dump=prioritize_model_dump,
+            )
+            for k, v in obj.items()
+        }
+
+    # Sequence/Set-like (but not str)
+    if isinstance(obj, list | tuple | set | frozenset):
+        items = [
+            _preprocess_recursive(
+                v,
+                depth=depth + 1,
+                max_depth=max_depth,
+                recursive_custom_types=recursive_custom_types,
+                str_parse_opts=str_parse_opts,
+                prioritize_model_dump=prioritize_model_dump,
+            )
+            for v in obj
+        ]
+        if t is list:
+            return items
+        if t is tuple:
+            return tuple(items)
+        if t is set:
+            return set(items)
+        if t is frozenset:
+            return frozenset(items)
+
+    # Enum *class* (rare in values, but preserve your original attempt)
+    if isinstance(obj, type) and issubclass(obj, _Enum):
+        with contextlib.suppress(Exception):
+            enum_map = _enum_class_to_dict(
+                obj,
+                use_enum_values=str_parse_opts.get("use_enum_values", True),
+            )
+            return _preprocess_recursive(
+                enum_map,
+                depth=depth + 1,
+                max_depth=max_depth,
+                recursive_custom_types=recursive_custom_types,
+                str_parse_opts=str_parse_opts,
+                prioritize_model_dump=prioritize_model_dump,
+            )
+        return obj
+
+    # Custom objects
+    if recursive_custom_types:
+        with contextlib.suppress(Exception):
+            mapped = _object_to_mapping_like(obj, prioritize_model_dump=prioritize_model_dump)
+            return _preprocess_recursive(
+                mapped,
+                depth=depth + 1,
+                max_depth=max_depth,
+                recursive_custom_types=recursive_custom_types,
+                str_parse_opts=str_parse_opts,
+                prioritize_model_dump=prioritize_model_dump,
+            )
+
+    return obj
+
+
+# ---------------------------------------
+# Top-level conversion (non-recursive)
+# ---------------------------------------
+
+
+def _convert_top_level_to_dict(
+    obj: Any,
+    *,
+    fuzzy_parse: bool,
+    parser: Callable[[str], Any] | None,
+    prioritize_model_dump: bool,
+    use_enum_values: bool,
+    **kwargs: Any,
+) -> dict[str | int, Any]:
+    """
+    Convert a *single* object to dict using the 'brute force' rules.
+    Mirrors your original order, with fixes & optimizations.
+    """
+    # Set -> {v: v}
+    if isinstance(obj, set):
+        return cast(dict[str | int, Any], {v: v for v in obj})
+
+    # Enum class -> members mapping
+    if isinstance(obj, type) and issubclass(obj, _Enum):
+        return cast(dict[str | int, Any], _enum_class_to_dict(obj, use_enum_values))
+
+    # Mapping -> copy to plain dict (preserve your copy semantics)
+    if isinstance(obj, Mapping):
+        return cast(dict[str | int, Any], dict(obj))
+
+    # None / pydantic undefined -> {}
+    if _is_na(obj):
+        return cast(dict[str | int, Any], {})
+
+    # str -> parse (and return *as parsed*, which may be list, dict, etc.)
+    if isinstance(obj, str):
+        return _parse_str(
+            obj,
+            fuzzy_parse=fuzzy_parse,
+            parser=parser,
+            **kwargs,
+        )
+
+    # Try "custom" object conversions
+    # (Covers BaseModel via model_dump, dataclasses, __dict__, json-strings, etc.)
+    with contextlib.suppress(Exception):
+        # If it's *not* a Sequence (e.g., numbers, objects) we try object conversion first,
+        # faithfully following your previous "non-Sequence -> model path" behavior.
+        if not isinstance(obj, Sequence):
+            converted = _object_to_mapping_like(
+                obj, prioritize_model_dump=prioritize_model_dump, **kwargs
+            )
+            # If conversion returned a string, try to parse JSON to mapping; else pass-through
+            if isinstance(converted, str):
+                return _parse_str(
+                    converted,
+                    fuzzy_parse=fuzzy_parse,
+                    parser=None,
+                )
+            if isinstance(converted, Mapping):
+                return dict(converted)
+            # If it's a list/tuple/etc., enumerate (your original did that after the fact)
+            if isinstance(converted, Iterable) and not isinstance(
+                converted, str | bytes | bytearray
+            ):
+                return cast(dict[str | int, Any], _enumerate_iterable(converted))
+            # Best effort final cast
+            return dict(converted)
+
+    # Iterable (list/tuple/namedtuple/frozenset/…): enumerate
+    if isinstance(obj, Iterable) and not isinstance(obj, str | bytes | bytearray):
+        return cast(dict[str | int, Any], _enumerate_iterable(obj))
+
+    # Dataclass fallback (reachable only if it wasn't caught above)
+    with contextlib.suppress(Exception):
+        if dataclasses.is_dataclass(obj) and not isinstance(obj, type):
+            return cast(dict[str | int, Any], dataclasses.asdict(obj))  # type: ignore[arg-type]
+
+    # Last-ditch attempt
+    return dict(obj)  # may raise, handled by top-level try/except
+
+
+def to_dict(
+    input_: Any,
+    /,
+    *,
+    prioritize_model_dump: bool = False,
+    fuzzy_parse: bool = False,
+    suppress: bool = False,
+    parser: Callable[[str], Any] | None = None,
+    recursive: bool = False,
+    max_recursive_depth: int | None = None,
+    recursive_python_only: bool = True,
+    use_enum_values: bool = False,
+    **kwargs: Any,
+) -> dict[str | int, Any]:
+    """
+    Convert various input types to a dictionary, with optional recursive processing.
+
+    Supports JSON string parsing via orjson (or custom parser).
+
+    Args:
+        input_: Object to convert to dict
+        prioritize_model_dump: If True, prefer .model_dump() for Pydantic models
+        fuzzy_parse: If True, use fuzzy JSON parsing for strings
+        suppress: If True, return {} on errors instead of raising
+        parser: Custom parser callable for string inputs
+        recursive: If True, recursively process nested structures
+        max_recursive_depth: Maximum recursion depth (default 5, max 10)
+        recursive_python_only: If True, only recurse into Python builtins
+        use_enum_values: If True, use .value for Enum members
+        **kwargs: Additional kwargs passed to parser
+
+    Returns:
+        Dictionary representation of input
+    """
+    try:
+        # Clamp recursion depth (match your constraints)
+        if not isinstance(max_recursive_depth, int):
+            max_depth = 5
+        else:
+            if max_recursive_depth < 0:
+                raise ValueError("max_recursive_depth must be a non-negative integer")
+            if max_recursive_depth > 10:
+                raise ValueError("max_recursive_depth must be less than or equal to 10")
+            max_depth = max_recursive_depth
+
+        # Prepare one small dict to avoid repeated arg passing and lookups
+        str_parse_opts = {
+            "fuzzy_parse": fuzzy_parse,
+            "parser": parser,
+            "use_enum_values": use_enum_values,  # threaded for enum class in recursion
+            **kwargs,
+        }
+
+        obj = input_
+        if recursive:
+            obj = _preprocess_recursive(
+                obj,
+                depth=0,
+                max_depth=max_depth,
+                recursive_custom_types=not recursive_python_only,
+                str_parse_opts=str_parse_opts,
+                prioritize_model_dump=prioritize_model_dump,
+            )
+
+        # Final top-level conversion
+        return _convert_top_level_to_dict(
+            obj,
+            fuzzy_parse=fuzzy_parse,
+            parser=parser,
+            prioritize_model_dump=prioritize_model_dump,
+            use_enum_values=use_enum_values,
+            **kwargs,
+        )
+
+    except Exception as e:
+        if suppress or input_ == "":
+            return {}
+        raise e

lionherd_core/ln/_to_list.py

@@ -0,0 +1,190 @@
+# Copyright (c) 2025, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass
+from enum import Enum as _Enum
+from typing import Any, ClassVar
+
+from lionherd_core.types import Params
+
+from ._hash import hash_dict
+
+__all__ = ("ToListParams", "to_list")
+
+
+_INITIALIZED = False
+_MODEL_LIKE = None
+_MAP_LIKE = None
+_SINGLETONE_TYPES = None
+_SKIP_TYPE = None
+_SKIP_TUPLE_SET = None
+_BYTE_LIKE = (str, bytes, bytearray)
+_TUPLE_SET = (tuple, set, frozenset)
+
+
+def to_list(
+    input_: Any,
+    /,
+    *,
+    flatten: bool = False,
+    dropna: bool = False,
+    unique: bool = False,
+    use_values: bool = False,
+    flatten_tuple_set: bool = False,
+) -> list:
+    """Convert input to list with optional transformations.
+
+    Args:
+        input_: Value to convert
+        flatten: Recursively flatten nested iterables
+        dropna: Remove None and undefined values
+        unique: Remove duplicates (requires flatten=True)
+        use_values: Extract values from enums/mappings
+        flatten_tuple_set: Include tuples/sets in flattening
+
+    Returns:
+        Processed list
+
+    Raises:
+        ValueError: If unique=True without flatten=True
+    """
+    global _INITIALIZED
+    if _INITIALIZED is False:
+        from pydantic import BaseModel
+        from pydantic_core import PydanticUndefinedType
+
+        from lionherd_core.types import UndefinedType, UnsetType
+
+        global _MODEL_LIKE, _MAP_LIKE, _SINGLETONE_TYPES, _SKIP_TYPE, _SKIP_TUPLE_SET
+        _MODEL_LIKE = (BaseModel,)
+        _MAP_LIKE = (Mapping, *_MODEL_LIKE)
+        _SINGLETONE_TYPES = (UndefinedType, UnsetType, PydanticUndefinedType)
+        _SKIP_TYPE = (*_BYTE_LIKE, *_MAP_LIKE, _Enum)
+        _SKIP_TUPLE_SET = (*_SKIP_TYPE, *_TUPLE_SET)
+        _INITIALIZED = True
+
+    def _process_list(
+        lst: list[Any],
+        flatten: bool,
+        dropna: bool,
+        skip_types: tuple[type, ...],
+    ) -> list[Any]:
+        """Process list according to flatten and dropna options."""
+        assert _SINGLETONE_TYPES is not None
+
+        result: list[Any] = []
+
+        for item in lst:
+            if dropna and (item is None or isinstance(item, _SINGLETONE_TYPES)):
+                continue
+
+            is_iterable = isinstance(item, Iterable)
+            should_skip = isinstance(item, skip_types)
+
+            if is_iterable and not should_skip:
+                item_list = list(item)
+                if flatten:
+                    result.extend(_process_list(item_list, flatten, dropna, skip_types))
+                else:
+                    result.append(_process_list(item_list, flatten, dropna, skip_types))
+            else:
+                result.append(item)
+
+        return result
+
+    def _to_list_type(input_: Any, use_values: bool) -> list[Any]:
+        """Convert input to initial list based on type."""
+        assert _SINGLETONE_TYPES is not None
+        assert _MODEL_LIKE is not None
+        assert _MAP_LIKE is not None
+
+        if input_ is None or isinstance(input_, _SINGLETONE_TYPES):
+            return []
+
+        if isinstance(input_, list):
+            return input_
+
+        if isinstance(input_, type) and issubclass(input_, _Enum):
+            members = input_.__members__.values()
+            return [member.value for member in members] if use_values else list(members)
+
+        if isinstance(input_, _BYTE_LIKE):
+            return list(input_) if use_values else [input_]
+
+        if isinstance(input_, Mapping):
+            return list(input_.values()) if use_values and hasattr(input_, "values") else [input_]
+
+        if isinstance(input_, _MODEL_LIKE):
+            return [input_]
+
+        if isinstance(input_, Iterable) and not isinstance(input_, _BYTE_LIKE):
+            return list(input_)
+
+        return [input_]
+
+    if unique and not flatten:
+        raise ValueError("unique=True requires flatten=True")
+
+    initial_list = _to_list_type(input_, use_values=use_values)
+    # Decide skip set once (micro-optimization)
+    skip_types = _SKIP_TYPE if flatten_tuple_set else _SKIP_TUPLE_SET
+    processed = _process_list(initial_list, flatten=flatten, dropna=dropna, skip_types=skip_types)
+
+    if unique:
+        seen = set()
+        out = []
+        use_hash_fallback = False
+        for i in processed:
+            try:
+                if not use_hash_fallback and i not in seen:
+                    # Direct approach - try to use the item as hash key
+                    seen.add(i)
+                    out.append(i)
+            except TypeError:
+                # Switch to hash-based approach and restart
+                if not use_hash_fallback:
+                    use_hash_fallback = True
+                    seen = set()
+                    out = []
+                    # Restart from beginning with hash-based approach
+                    for j in processed:
+                        try:
+                            hash_value = hash(j)
+                        except TypeError:
+                            if isinstance(j, _MAP_LIKE):
+                                hash_value = hash_dict(j)
+                            else:
+                                raise ValueError(
+                                    "Unhashable type encountered in list unique value processing."
+                                )
+                        if hash_value not in seen:
+                            seen.add(hash_value)
+                            out.append(j)
+                    break
+        return out
+
+    return processed
+
+
+@dataclass(slots=True, frozen=True, init=False)
+class ToListParams(Params):
+    _func: ClassVar[Any] = to_list
+
+    flatten: bool
+    """If True, recursively flatten nested iterables."""
+    dropna: bool
+    """If True, remove None and undefined values."""
+    unique: bool
+    """If True, remove duplicates (requires flatten=True)."""
+    use_values: bool
+    """If True, extract values from enums/mappings."""
+    flatten_tuple_set: bool
+    """If True, include tuples and sets in flattening."""
+
+    def __call__(self, input_: Any, **kw) -> list:
+        """Apply to_list with stored parameters."""
+        kwargs = {**self.default_kw(), **kw}
+        return to_list(input_, **kwargs)