python-corekit 0.4.0__py3-none-any.whl → 0.5.0__py3-none-any.whl

corekit/utils/coercion.py

@@ -6,17 +6,36 @@ 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"]
+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) -> str:
@@ -27,54 +46,21 @@ 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 ""
+    return parse_string(item, pretty=pretty, default="").value
 
 
 def safe_int(item: Any) -> 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
+    return parse_int(item, default=0).value
 
 
 def safe_float(item: Any) -> 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
+    return parse_float(item, default=0.0).value
 
 
 def safe_list(item: Any) -> list[Any]:
@@ -84,13 +70,7 @@ def safe_list(item: Any) -> list[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.
     """
-    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=[]).value
 
 
 def safe_tuple(item: Any) -> tuple[Any, ...]:
@@ -100,19 +80,25 @@ def safe_tuple(item: Any) -> tuple[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.
     """
-    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=()).value
+
+
+def safe_set(item: Any) -> set[Any]:
+    """
+    Convert a collection to a set, or ``set()`` 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.
+    Unhashable elements yield ``set()``.
+    """
+    return parse_set(item, default=set()).value
 
 
 def safe_dict(item: Any) -> 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={}).value

corekit/utils/collections.py

@@ -7,10 +7,29 @@ once. Built for JSON from somewhere you do not control, where any level may be
 missing or the wrong type.
 """
 
-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
+
+__all__ = [
+    "MultiMatch",
+    "aiterator",
+    "attr_or_key",
+    "iterator",
+    "keygetter",
+    "kv_string",
+    "repeated_get",
+    "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 +59,120 @@ 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 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 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 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.

corekit/utils/parsers.py

@@ -0,0 +1,205 @@
+"""
+Flexible parsers with caller-controlled fallbacks.
+
+Each helper attempts to extract the target type and returns a ``ParsedValue``
+carrying both the result and a ``success`` flag. On failure the ``value`` is
+whatever ``default`` the caller supplied (``None`` unless overridden).
+
+These are the extraction layer. For a guaranteed target type with that type's
+empty value as the fallback, use the ``safe_*`` wrappers in
+``corekit.utils.coercion``.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import date, datetime
+from typing import Any, NamedTuple
+
+from corekit.utils.text import list_to_english
+
+__all__ = [
+    "ParsedValue",
+    "parse_dict",
+    "parse_float",
+    "parse_int",
+    "parse_list",
+    "parse_set",
+    "parse_string",
+    "parse_tuple",
+]
+
+
+class ParsedValue(NamedTuple):
+    """Outcome of a parse attempt."""
+
+    value: Any
+    success: bool
+
+    @classmethod
+    def ok(cls, value: Any) -> ParsedValue:
+        return cls(value=value, success=True)
+
+    @classmethod
+    def error(cls, value: Any) -> ParsedValue:
+        return cls(value=value, success=False)
+
+
+def parse_string(
+    item: Any,
+    *,
+    pretty: bool = False,
+    strip: bool = True,
+    default: Any = None,
+) -> ParsedValue:
+    """
+    Extract a string rendering of ``item``, or ``default`` if there is none.
+
+    Collections become JSON by default. With ``pretty`` they become an English
+    list instead -- ``"a, b, c"``, or ``"key: value, ..."`` for a mapping --
+    which reads better in a notification than raw JSON.
+    """
+
+    def _clean(text: str) -> str:
+        return text.strip() if strip else text
+
+    def _parse_collection(collection: Any) -> str:
+        if pretty:
+            if isinstance(collection, dict):
+                return list_to_english([f"{key}: {value}" for key, value in collection.items()])
+            return list_to_english(
+                [parse_string(element, pretty=pretty, strip=strip, default="").value for element in collection]
+            )
+        return json.dumps(collection)
+
+    if isinstance(item, bytes):
+        item = item.decode("utf-8", errors="ignore")
+    if isinstance(item, str):
+        return ParsedValue.ok(_clean(item))
+    # bool is a subclass of int, so both land here and render as "True"/"1".
+    if isinstance(item, (int, float)):
+        return ParsedValue.ok(str(item))
+    if isinstance(item, (list, tuple, set, dict)):
+        return ParsedValue.ok(_parse_collection(item))
+    if isinstance(item, (date, datetime)):
+        return ParsedValue.ok(item.isoformat())
+    return ParsedValue.error(default)
+
+
+def parse_int(item: Any, *, default: Any = None) -> ParsedValue:
+    """
+    Extract an int from ``item``, or ``default`` if it will not convert.
+    """
+    if isinstance(item, bool):
+        return ParsedValue.ok(int(item))
+    if isinstance(item, int):
+        return ParsedValue.ok(item)
+    if isinstance(item, bytes):
+        item = item.decode("utf-8", errors="ignore")
+    if isinstance(item, (float, str)):
+        try:
+            return ParsedValue.ok(int(item))
+        except (TypeError, ValueError):
+            return ParsedValue.error(default)
+    return ParsedValue.error(default)
+
+
+def parse_float(item: Any, *, default: Any = None) -> ParsedValue:
+    """
+    Extract a float from ``item``, or ``default`` if it will not convert.
+    """
+    if isinstance(item, bool):
+        return ParsedValue.ok(float(item))
+    if isinstance(item, float):
+        return ParsedValue.ok(item)
+    if isinstance(item, bytes):
+        item = item.decode("utf-8", errors="ignore")
+    if isinstance(item, (int, str)):
+        try:
+            return ParsedValue.ok(float(item))
+        except (TypeError, ValueError):
+            return ParsedValue.error(default)
+    return ParsedValue.error(default)
+
+
+def parse_list(item: Any, *, default: Any = None) -> ParsedValue:
+    """
+    Extract a list from a collection, or ``default`` 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 ParsedValue.ok(item)
+    if isinstance(item, (tuple, set)):
+        return ParsedValue.ok(list(item))
+    if isinstance(item, dict):
+        return ParsedValue.ok(list(item.values()))
+    return ParsedValue.error(default)
+
+
+def parse_tuple(item: Any, *, default: Any = None) -> ParsedValue:
+    """
+    Extract a tuple from a collection, or ``default`` 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 ParsedValue.ok(item)
+    if isinstance(item, (list, set)):
+        return ParsedValue.ok(tuple(item))
+    if isinstance(item, dict):
+        return ParsedValue.ok(tuple(item.values()))
+    return ParsedValue.error(default)
+
+
+def parse_set(item: Any, *, default: Any = None) -> ParsedValue:
+    """
+    Extract a set from a collection, or ``default`` 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.
+    Unhashable elements fail the conversion and yield ``default``.
+    """
+    if isinstance(item, set):
+        return ParsedValue.ok(item)
+    if isinstance(item, (list, tuple)):
+        try:
+            return ParsedValue.ok(set(item))
+        except TypeError:
+            return ParsedValue.error(default)
+    if isinstance(item, dict):
+        try:
+            return ParsedValue.ok(set(item.values()))
+        except TypeError:
+            return ParsedValue.error(default)
+    return ParsedValue.error(default)
+
+
+def parse_dict(item: Any, *, default: Any = None) -> ParsedValue:
+    """
+    Extract a mapping from ``item``, or ``default`` if none is available.
+
+    Accepts a ``dict`` directly, then common dump protocols (``to_dict``,
+    ``model_dump``, ``dict``), then a plain ``__dict__``.
+    """
+    if isinstance(item, dict):
+        return ParsedValue.ok(item)
+
+    for method_name in ("to_dict", "model_dump", "dict"):
+        method = getattr(item, method_name, None)
+        if not callable(method):
+            continue
+        try:
+            result = method()
+        except Exception:
+            continue
+        if isinstance(result, dict):
+            return ParsedValue.ok(result)
+
+    namespace = getattr(item, "__dict__", None)
+    if isinstance(namespace, dict):
+        return ParsedValue.ok(namespace)
+
+    return ParsedValue.error(default)

corekit/utils/text.py

@@ -2,13 +2,14 @@
 String assembly helpers.
 
 Small formatters for turning collections into text a human will read -- log
-lines, notification bodies, error messages -- plus filename sanitization.
+lines, notification bodies, error messages -- plus filename sanitization and
+length limits.
 """
 
 import re
 from typing import Any, Literal
 
-__all__ = ["join_lines", "list_to_english", "sanitize_filename"]
+__all__ = ["join_lines", "list_to_english", "sanitize_filename", "truncate"]
 
 FALLBACK_FILENAME = "unnamed"
 _UNSAFE_CHARS = re.compile(r"[^a-z0-9\-]")
@@ -43,6 +44,24 @@ def list_to_english(items: list[str], ending: Literal["and", "or"] | None = None
     return f"{buffer}, {ending} {last}"
 
 
+def truncate(text: str, limit: int, *, suffix: str = "") -> str:
+    """
+    Cut ``text`` to at most ``limit`` characters, appending ``suffix`` when cut.
+
+    ``suffix`` counts toward ``limit``, so the returned string is never longer
+    than ``limit`` (unless ``suffix`` itself is longer than ``limit``, in which
+    case ``suffix`` is returned truncated to ``limit``).
+    """
+    if limit <= 0:
+        return ""
+    if len(text) <= limit:
+        return text
+    if len(suffix) >= limit:
+        return suffix[:limit]
+    keep = limit - len(suffix)
+    return text[:keep] + suffix
+
+
 def sanitize_filename(raw: str, fallback: str = FALLBACK_FILENAME) -> str:
     """
     Reduce a string to lowercase kebab-case safe for use as a filename stem.

{python_corekit-0.4.0.dist-info → python_corekit-0.5.0.dist-info}/METADATA

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: python-corekit
-Version: 0.4.0
-Summary: Shared foundations for Python projects: logging, benchmarking, registries, FastAPI application and routers, SQL statements and migrations, background tasks, ETL, and LLM chat/tool primitives
+Version: 0.5.0
+Summary: Shared foundations for Python projects: logging, benchmarking, registries, FastAPI application and routers, SQL statements and migrations, background tasks, ETL, LLM chat/tool primitives, and HTML scraping
 Author: Steven Jacobsen
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/stevejaker/corekit
@@ -23,6 +23,7 @@ Requires-Dist: sqlmodel<0.1,>=0.0.16
 Requires-Dist: SQLAlchemy<3,>=2.0
 Requires-Dist: redis<7,>=5.0
 Requires-Dist: httpx<1,>=0.27
+Requires-Dist: selectolax<1,>=0.3
 Requires-Dist: docker<8,>=7.0
 Requires-Dist: PyYAML<7,>=6.0
 Requires-Dist: dill<0.5,>=0.3.8
@@ -90,6 +91,29 @@ class Report(Benchmarkable):
         self.timing("queried")   # logs the time since the previous split
 ```
 
+## Exceptionator
+
+Catch an exception, run one action, then rethrow so the existing failure path
+still happens. Built-in actions are no-op and log-traceback; apps supply their
+own (persist, notify, …).
+
+```python
+from corekit.exceptionator import (
+    Exceptionator,
+    ExceptionatorMiddleware,
+    LogTracebackAction,
+    install_run_task_hook,
+    set_process_exceptionator,
+)
+
+exceptionator = Exceptionator(LogTracebackAction(), service="api")
+set_process_exceptionator(exceptionator)
+install_run_task_hook(exceptionator)  # optional; run_task captures with task name
+```
+
+`ExceptionatorMiddleware` is raw ASGI (not `BaseHTTPMiddleware`). With no
+`run_task` hook installed, jobs behave as in 0.4.0.
+
 ## Assembling an application
 
 `Application` is a plain `FastAPI` subclass — every constructor argument,
@@ -324,13 +348,13 @@ class GithubClient(BaseApiClient):
         return "https://api.github.com"
 
 response = GithubClient().get("/users/octocat")
-response.data["login"]
+response.data.login
 ```
 
-Retries 429 and 5xx with exponential backoff. Every response is a
-`BaseApiResponse`, so a non-JSON error page leaves `data` empty rather than
-raising. The same methods are awaitable inside a running event loop:
-`await client.get(...)`.
+Retries 429 and 5xx with exponential backoff. ``BaseHttpClient`` returns a
+``BaseHttpResponse`` (text + metadata); ``BaseApiClient`` adds structured
+``data`` from JSON (``None`` when the body is not JSON). The same methods are
+awaitable inside a running event loop: `await client.get(...)`.
 
 ## Serialization