python-corekit 0.4.1__py3-none-any.whl → 0.6.0__py3-none-any.whl

corekit/utils/__init__.py

@@ -1,15 +1,41 @@
 """
 Small, dependency-free helpers.
 
-Four groups: total conversions that never raise (``safe_*``), string assembly
-for human-readable output, identifier generation, and nested-dictionary lookup.
-Plus timezone-aware time helpers and the placeholder callbacks (``void``,
-``raise_exc``, ``true_validator``, ``false_validator``) that callbacks-by-
-configuration need.
+Five groups: flexible parsers with caller-controlled fallbacks (``parse_*``),
+total conversions that never raise (``safe_*`` wrappers around those parsers),
+string assembly for human-readable output, identifier generation, and
+nested-dictionary lookup. Plus timezone-aware time helpers and the placeholder
+callbacks (``void``, ``raise_exc``, ``true_validator``, ``false_validator``)
+that callbacks-by-configuration need.
 """
 
-from corekit.utils.coercion import safe_dict, safe_float, safe_int, safe_list, safe_string, safe_tuple
-from corekit.utils.collections import UNSET, MultiMatch, attr_or_key, keygetter, repeated_get, split_list
+from corekit.utils.coercion import (
+    safe_dict,
+    safe_float,
+    safe_int,
+    safe_list,
+    safe_set,
+    safe_string,
+    safe_tuple,
+)
+from corekit.utils.collections import (
+    UNSET,
+    MultiMatch,
+    aiterator,
+    attr_or_key,
+    first,
+    first_float,
+    first_int,
+    first_string,
+    getval,
+    iterator,
+    keygetter,
+    kv_string,
+    list_map,
+    repeated_get,
+    set_map,
+    split_list,
+)
 from corekit.utils.ids import (
     SHORTCODE_CHARS,
     generate_session_token,
@@ -17,6 +43,16 @@ from corekit.utils.ids import (
     generate_shortcodes,
     generate_uuid,
 )
+from corekit.utils.parsers import (
+    ParsedValue,
+    parse_dict,
+    parse_float,
+    parse_int,
+    parse_list,
+    parse_set,
+    parse_string,
+    parse_tuple,
+)
 from corekit.utils.payload import Payload, decode_payload, encode_payload
 from corekit.utils.raise_exc import raise_exc
 from corekit.utils.text import join_lines, list_to_english, sanitize_filename, truncate
@@ -28,28 +64,47 @@ __all__ = [
     "SHORTCODE_CHARS",
     "UNSET",
     "MultiMatch",
+    "ParsedValue",
     "Payload",
+    "aiterator",
     "attr_or_key",
     "decode_payload",
     "encode_payload",
     "false_validator",
+    "first",
+    "first_string",
+    "first_int",
+    "first_float",
     "generate_session_token",
     "generate_shortcode",
     "generate_shortcodes",
     "generate_uuid",
+    "getval",
     "isoformat_now",
+    "iterator",
     "join_lines",
     "keygetter",
+    "kv_string",
+    "list_map",
     "list_to_english",
+    "parse_dict",
     "parse_docker_timestamp",
+    "parse_float",
+    "parse_int",
+    "parse_list",
+    "parse_set",
+    "parse_string",
+    "parse_tuple",
     "raise_exc",
     "repeated_get",
     "safe_dict",
     "safe_float",
     "safe_int",
     "safe_list",
+    "safe_set",
     "safe_string",
     "safe_tuple",
+    "set_map",
     "sanitize_filename",
     "split_list",
     "time_now",

corekit/utils/coercion.py

@@ -6,20 +6,39 @@ empty value rather than raising. Use them at boundaries where the input is
 genuinely unknown -- an API payload, a config value, a scraped field -- and a
 crash would be worse than a default.
 
+These are thin wrappers around ``corekit.utils.parsers``. Extraction logic lives
+there once; here we only fix the fallback to the type's empty value so the
+return type is guaranteed.
+
 The tradeoff is real: ``safe_int("banana")`` is ``0``, indistinguishable from a
-genuine zero. Where telling those apart matters, parse explicitly instead.
+genuine zero. Where telling those apart matters, call the parser directly and
+inspect ``ParsedValue.success``, or pass a sentinel ``default``.
 """
 
-import json
-from datetime import date, datetime
 from typing import Any
 
-from corekit.utils.text import list_to_english
-
-__all__ = ["safe_dict", "safe_float", "safe_int", "safe_list", "safe_string", "safe_tuple"]
-
-
-def safe_string(item: Any, pretty: bool = False) -> str:
+from corekit.utils.parsers import (
+    parse_dict,
+    parse_float,
+    parse_int,
+    parse_list,
+    parse_set,
+    parse_string,
+    parse_tuple,
+)
+
+__all__ = [
+    "safe_dict",
+    "safe_float",
+    "safe_int",
+    "safe_list",
+    "safe_set",
+    "safe_string",
+    "safe_tuple",
+]
+
+
+def safe_string(item: Any, pretty: bool = False, default: str = "") -> str:
     """
     Convert anything to a string, or ``""`` if there is no sensible rendering.
 
@@ -27,92 +46,59 @@ def safe_string(item: Any, pretty: bool = False) -> str:
     list instead -- ``"a, b, c"``, or ``"key: value, ..."`` for a mapping --
     which reads better in a notification than raw JSON.
     """
-    if isinstance(item, bytes):
-        item = item.decode("utf-8", errors="ignore")
-    if isinstance(item, str):
-        return item.strip()
-    # bool is a subclass of int, so both land here and render as "True"/"1".
-    if isinstance(item, (int, float)):
-        return str(item)
-    if isinstance(item, (list, tuple, set, dict)):
-        if pretty:
-            if isinstance(item, dict):
-                return list_to_english([f"{key}: {value}" for key, value in item.items()])
-            return list_to_english([safe_string(element) for element in item])
-        return json.dumps(item)
-    if isinstance(item, (date, datetime)):
-        return item.isoformat()
-    return ""
-
-
-def safe_int(item: Any) -> int:
+    return parse_string(item, pretty=pretty, default=default).value
+
+
+def safe_int(item: Any, default: int = 0) -> int:
     """
     Convert anything to an int, or ``0`` if it will not convert.
     """
-    if isinstance(item, int):
-        return item
-    if isinstance(item, bytes):
-        item = item.decode("utf-8", errors="ignore")
-    if isinstance(item, (float, str)):
-        try:
-            return int(item)
-        except ValueError:
-            return 0
-    return 0
-
-
-def safe_float(item: Any) -> float:
+    return parse_int(item, default=default).value
+
+
+def safe_float(item: Any, default: float = 0.0) -> float:
     """
     Convert anything to a float, or ``0.0`` if it will not convert.
     """
-    if isinstance(item, float):
-        return item
-    if isinstance(item, bytes):
-        item = item.decode("utf-8", errors="ignore")
-    if isinstance(item, (int, str)):
-        try:
-            return float(item)
-        except ValueError:
-            return 0.0
-    return 0.0
-
-
-def safe_list(item: Any) -> list[Any]:
+    return parse_float(item, default=default).value
+
+
+def safe_list(item: Any, default: list[Any] | None = None) -> list[Any]:
     """
     Convert a collection to a list, or ``[]`` for anything else.
 
     A mapping yields its values. A string is *not* treated as a collection --
     exploding it into characters is almost never what the caller meant.
     """
-    if isinstance(item, list):
-        return item
-    if isinstance(item, (tuple, set)):
-        return list(item)
-    if isinstance(item, dict):
-        return list(item.values())
-    return []
+    return parse_list(item, default=default if default is not None else []).value
 
 
-def safe_tuple(item: Any) -> tuple[Any, ...]:
+def safe_tuple(item: Any, default: tuple[Any, ...] | None = None) -> tuple[Any, ...]:
     """
     Convert a collection to a tuple, or ``()`` for anything else.
 
     A mapping yields its values. A string is *not* treated as a collection --
     exploding it into characters is almost never what the caller meant.
     """
-    if isinstance(item, tuple):
-        return item
-    if isinstance(item, (list, set)):
-        return tuple(item)
-    if isinstance(item, dict):
-        return tuple(item.values())
-    return ()
+    return parse_tuple(item, default=default if default is not None else ()).value
+
 
+def safe_set(item: Any, default: set[Any] | None = None) -> set[Any]:
+    """
+    Convert a collection to a set, or ``set()`` for anything else.
 
-def safe_dict(item: Any) -> dict[str, Any]:
+    A mapping yields its values. A string is *not* treated as a collection --
+    exploding it into characters is almost never what the caller meant.
+    Unhashable elements yield ``set()``.
+    """
+    return parse_set(item, default=default if default is not None else set()).value
+
+
+def safe_dict(item: Any, default: dict[str, Any] | None = None) -> dict[str, Any]:
     """
     Return the mapping unchanged, or ``{}`` for anything else.
+
+    Also accepts objects that expose ``to_dict``, ``model_dump``, or ``dict``,
+    and falls back to ``__dict__`` when present.
     """
-    if isinstance(item, dict):
-        return item
-    return {}
+    return parse_dict(item, default=default if default is not None else {}).value

corekit/utils/collections.py

@@ -4,13 +4,42 @@ Nested lookup and small collection helpers.
 ``repeated_get`` walks a path into nested dictionaries without a pile of
 ``.get()`` calls, and ``keygetter`` lets a step in that path match many keys at
 once. Built for JSON from somewhere you do not control, where any level may be
-missing or the wrong type.
+missing or the wrong type. ``getval`` is the mixed-source counterpart: it walks
+dicts and attribute-bearing objects alike, with ordered fallback keys.
 """
 
-from copy import deepcopy
-from typing import Any, Callable
+from __future__ import annotations
 
-__all__ = ["MultiMatch", "attr_or_key", "keygetter", "repeated_get", "split_list"]
+import inspect
+from collections.abc import AsyncIterable, AsyncIterator, Iterable, Mapping
+from copy import deepcopy
+from typing import Any, Awaitable, Callable, Iterator, Literal, Sequence
+
+from corekit.utils.coercion import safe_float, safe_int, safe_string
+
+__all__ = [
+    "MultiMatch",
+    "aiterator",
+    "attr_or_key",
+    "first",
+    "first_float",
+    "first_int",
+    "first_string",
+    "getval",
+    "iterator",
+    "keygetter",
+    "kv_string",
+    "list_map",
+    "repeated_get",
+    "set_map",
+    "split_list",
+]
+
+WhereSeq = Callable[[Any], bool]
+WhereMap = Callable[[Any, Any], bool]
+AsyncWhereSeq = Callable[[Any], bool | Awaitable[bool]]
+AsyncWhereMap = Callable[[Any, Any], bool | Awaitable[bool]]
+IteratorMode = Literal["keys", "values", "items"]
 
 KEY_SEPARATOR = "."
 
@@ -40,6 +69,215 @@ def attr_or_key(obj: Any, name: str) -> Any:
     return getattr(obj, name, None)
 
 
+def _mapping_item(key: Any, value: Any, mode: IteratorMode) -> Any:
+    if mode == "values":
+        return value
+    if mode == "items":
+        return key, value
+    return key
+
+
+def iterator(
+    obj: Iterable[Any] | Mapping[Any, Any] | None = None,
+    *,
+    mode: IteratorMode = "keys",
+    where: WhereSeq | WhereMap | None = None,
+    compact: bool = False,
+) -> Iterator[Any]:
+    """
+    Iterate an iterable or mapping, optionally filtered.
+
+    Non-mappings ignore ``mode`` and yield elements. Mappings yield keys,
+    values, or items according to ``mode`` (default ``keys``).
+
+    ``compact=True`` skips ``None`` items, or mapping entries whose **value**
+    is ``None``. ``where`` is a sync predicate: one argument for iterables,
+    ``(key, value)`` for mappings — the entry is filtered, then ``mode``
+    selects what is yielded.
+
+    ``None`` yields nothing.
+    """
+    if obj is None:
+        return
+
+    if isinstance(obj, Mapping):
+        for key, value in obj.items():
+            if compact and value is None:
+                continue
+            if where is not None and not bool(where(key, value)):  # type: ignore[call-arg, arg-type]
+                continue
+            yield _mapping_item(key, value, mode)
+        return
+
+    for item in obj:
+        if compact and item is None:
+            continue
+        if where is not None and not bool(where(item)):  # type: ignore[call-arg, arg-type]
+            continue
+        yield item
+
+
+async def aiterator(
+    obj: AsyncIterable[Any] | Iterable[Any] | Mapping[Any, Any] | None = None,
+    *,
+    mode: IteratorMode = "keys",
+    where: AsyncWhereSeq | AsyncWhereMap | None = None,
+    compact: bool = False,
+) -> AsyncIterator[Any]:
+    """
+    Async counterpart to ``iterator``.
+
+    Accepts async iterables, sync iterables, and mappings. ``where`` may be
+    sync or async; mapping predicates still receive ``(key, value)``. Use with
+    ``async for``.
+    """
+    if obj is None:
+        return
+
+    async def _allow_mapping(_key: Any, _value: Any) -> bool:
+        if where is None:
+            return True
+        result = where(_key, _value)  # type: ignore[call-arg, arg-type]
+        if inspect.isawaitable(result):
+            result = await result
+        return bool(result)
+
+    async def _allow_item(_item: Any) -> bool:
+        if where is None:
+            return True
+        result = where(_item)  # type: ignore[call-arg, arg-type]
+        if inspect.isawaitable(result):
+            result = await result
+        return bool(result)
+
+    if isinstance(obj, Mapping):
+        for key, value in obj.items():
+            if compact and value is None:
+                continue
+            if not await _allow_mapping(key, value):
+                continue
+            yield _mapping_item(key, value, mode)
+        return
+
+    if isinstance(obj, AsyncIterable):
+        async for item in obj:
+            if compact and item is None:
+                continue
+            if not await _allow_item(item):
+                continue
+            yield item
+        return
+
+    for item in obj:
+        if compact and item is None:
+            continue
+        if not await _allow_item(item):
+            continue
+        yield item
+
+
+def first(seq: Sequence[Any], default: Any = None) -> Any:
+    """
+    Get the first item from a sequence, or ``default`` if empty.
+    """
+    if not seq:
+        return default
+    return next(iter(seq), default)
+
+
+def first_string(seq: Sequence[Any], default: str = "") -> str:
+    """
+    First item of ``seq`` as a string, or ``default`` if empty/unconvertible.
+    """
+    return safe_string(first(seq, default), default=default)
+
+
+def first_int(seq: Sequence[Any], default: int = 0) -> int:
+    """
+    First item of ``seq`` as an int, or ``default`` if empty/unconvertible.
+    """
+    return safe_int(first(seq, default), default=default)
+
+
+def first_float(seq: Sequence[Any], default: float = 0.0) -> float:
+    """
+    First item of ``seq`` as a float, or ``default`` if empty/unconvertible.
+    """
+    return safe_float(first(seq, default), default=default)
+
+
+def list_map(
+    obj: Iterable[Any] | Mapping[Any, Any] | None,
+    func: Callable[[Any], Any],
+    *,
+    mode: IteratorMode = "keys",
+    where: WhereSeq | WhereMap | None = None,
+    compact: bool = False,
+) -> list[Any]:
+    return [func(item) for item in iterator(obj, mode=mode, where=where, compact=compact)]
+
+
+def set_map(
+    obj: Iterable[Any] | Mapping[Any, Any] | None,
+    func: Callable[[Any], Any],
+    *,
+    mode: IteratorMode = "keys",
+    where: WhereSeq | WhereMap | None = None,
+    compact: bool = False,
+) -> set[Any]:
+    return {func(item) for item in iterator(obj, mode=mode, where=where, compact=compact)}
+
+
+def getval(
+    obj: Any,
+    key: str,
+    default: Any = None,
+    default_factory: Callable[[], Any] | None = None,
+    fallback_keys: list[str] | None = None,
+) -> Any:
+    """
+    Read `key` (dot-paths supported) from a dict, pydantic model, dataclass, or any other
+    arbitrary object. Returns `default` on miss, or `default_factory`, if provided. Use
+    `default_factory` for mutable defaults so callers never share an instance. Before the
+    default is applied, we will try each item in `fallback_keys` (in order).
+
+    A key that is present with value ``None`` is a hit, not a miss: ``None``
+    is returned and neither fallbacks nor defaults apply. For dict-only walks
+    with predicate steps, use ``repeated_get`` instead.
+    """
+
+    def _get(_obj: Any, _key: str) -> Any:
+        if _obj is UNSET or _obj is None:
+            return UNSET
+        if isinstance(_obj, dict):
+            return _obj.get(_key, UNSET)
+        if hasattr(_obj, _key):
+            return getattr(_obj, _key, UNSET)
+        return UNSET
+
+    value = obj
+    for next_key in key.split("."):
+        value = _get(value, next_key)
+
+    if value is not UNSET:
+        return value
+
+    if fallback_keys:
+        next_key, *remaining = fallback_keys
+        return getval(obj, next_key, default, default_factory, remaining)
+
+    if default_factory is not None and callable(default_factory):
+        return default_factory()
+    return default
+
+
+def kv_string(key: str, value: Any, sep: str = ": ", prefix: str = "") -> str:
+    """
+    Format a key-value pair into a string.
+    """
+    return f"{prefix}{key}{sep}{value}"
+
+
 class MultiMatch(dict[str, Any]):
     """
     The result of a path step that matched more than one key.