python-corekit 0.1.1__py3-none-any.whl → 0.3.0__py3-none-any.whl

corekit/utils/coercion.py

@@ -0,0 +1,118 @@
+"""
+Total conversions.
+
+Each helper turns anything into its target type, falling back to that type's
+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.
+
+The tradeoff is real: ``safe_int("banana")`` is ``0``, indistinguishable from a
+genuine zero. Where telling those apart matters, parse explicitly instead.
+"""
+
+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:
+    """
+    Convert anything to a string, or ``""`` if there is no sensible rendering.
+
+    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.
+    """
+    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:
+    """
+    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:
+    """
+    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]:
+    """
+    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 []
+
+
+def safe_tuple(item: Any) -> 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 ()
+
+
+def safe_dict(item: Any) -> dict[str, Any]:
+    """
+    Return the mapping unchanged, or ``{}`` for anything else.
+    """
+    if isinstance(item, dict):
+        return item
+    return {}

corekit/utils/collections.py

@@ -0,0 +1,124 @@
+"""
+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.
+"""
+
+from copy import deepcopy
+from typing import Any, Callable
+
+__all__ = ["MultiMatch", "keygetter", "repeated_get", "split_list"]
+
+KEY_SEPARATOR = "."
+
+# Distinct from None, which is a legitimate value to find at a key.
+UNSET: Any = object()
+
+
+def split_list(items: list[Any], index: int) -> tuple[list[Any], list[Any]]:
+    """
+    Split a list in two at ``index``. Out-of-range indices yield an empty side.
+    """
+    return items[:index], items[index:]
+
+
+class MultiMatch(dict[str, Any]):
+    """
+    The result of a path step that matched more than one key.
+
+    A dict subclass, so it reads like the mapping it is, but a distinct type so
+    ``repeated_get`` can tell "several matches" from "one match that happened to
+    be a dict".
+    """
+
+
+class keygetter:
+    """
+    A path step that selects keys by predicate rather than by name.
+
+    Use where key names are not known ahead of time::
+
+        repeated_get(payload, keys=["items", keygetter(lambda k: k.startswith("id_"))])
+
+    One match returns that value; several return a ``MultiMatch``.
+    """
+
+    def __init__(self, func: Callable[..., Any]) -> None:
+        """
+        Build a step from a predicate over key names.
+        """
+        self.func = func
+        self._keymap: MultiMatch = MultiMatch()
+
+    def call(self, data: dict[str, Any]) -> Any | MultiMatch:
+        """
+        Apply the predicate, returning the match, a ``MultiMatch``, or ``UNSET``.
+
+        The keymap is replaced on every call. The same instance can be a step
+        more than once in one path; keeping the previous matches would make
+        the second step see keys from the first.
+        """
+        matches = MultiMatch()
+        for key, value in data.items():
+            if self.func(key):
+                matches[key] = value
+        self._keymap = matches
+
+        if not matches:
+            return UNSET
+
+        if len(matches) == 1:
+            return next(iter(matches.values()))
+
+        return matches
+
+
+def repeated_get(
+    data: dict[str, Any],
+    keys: list[str | keygetter] | None = None,
+    keypath: str | None = None,
+    separator: str = KEY_SEPARATOR,
+    fallback: Any = None,
+) -> Any | MultiMatch:
+    """
+    Follow a path into nested dictionaries, returning ``fallback`` if it breaks.
+
+    Give either ``keys`` (which may contain ``keygetter`` steps) or a dotted
+    ``keypath``. Any level that is missing, or is not a mapping, ends the walk
+    at ``fallback`` rather than raising.
+    """
+    if keys is None:
+        if keypath is None:
+            raise ValueError("repeated_get needs either keys or keypath")
+        keys = list(keypath.split(separator))
+
+    def _get_item(current: Any, key: str | keygetter) -> Any | MultiMatch:
+        if current is UNSET or not isinstance(current, dict):
+            return UNSET
+
+        if isinstance(key, keygetter):
+            return key.call(current)
+        if callable(key):
+            # A bare predicate is the same step as a keygetter. A reused
+            # instance still goes through call(), which owns the keymap.
+            return keygetter(key).call(current)
+
+        return current.get(key, UNSET)
+
+    # Copied so a keygetter's predicate cannot mutate the caller's data.
+    result = deepcopy(data)
+    for key in keys:
+        if isinstance(result, MultiMatch):
+            collected = MultiMatch()
+            for parent_key, branch in result.items():
+                child = _get_item(branch, key)
+                if child is not UNSET:
+                    collected[parent_key] = child
+            result = collected if collected else UNSET
+        else:
+            result = _get_item(result, key)
+
+    return fallback if result is UNSET else result

corekit/utils/ids.py

@@ -1,5 +1,61 @@
-import uuid
-
-
-def generate_uuid() -> str:
-    return str(uuid.uuid4())
+"""
+Identifier generation.
+
+UUIDs for internal keys, URL-safe tokens for sessions, and short human-readable
+codes for anything someone has to read aloud or type in by hand.
+"""
+
+import secrets
+import string
+import uuid
+
+__all__ = [
+    "SHORTCODE_CHARS",
+    "generate_session_token",
+    "generate_shortcode",
+    "generate_shortcodes",
+    "generate_uuid",
+]
+
+# Uppercase alphanumerics minus the characters people confuse when reading a
+# code off a screen: O/0 and I/1.
+SHORTCODE_CHARS = string.ascii_uppercase.replace("O", "").replace("I", "") + string.digits.replace("0", "").replace(
+    "1", ""
+)
+
+
+def generate_uuid() -> str:
+    """
+    Return a random UUID4 as a string.
+    """
+    return str(uuid.uuid4())
+
+
+def generate_session_token(length: int = 32) -> str:
+    """
+    Return a cryptographically random URL-safe token.
+
+    ``length`` is the number of random *bytes*; the returned string is longer,
+    since base64 encoding expands it by about a third.
+    """
+    return secrets.token_urlsafe(length)
+
+
+def generate_shortcode(length: int, alphabet: str = SHORTCODE_CHARS) -> str:
+    """
+    Return a cryptographically random code of ``length`` characters.
+
+    Drawn from an unambiguous alphabet, so the result survives being read over
+    the phone or copied off a screen.
+    """
+    return "".join(secrets.choice(alphabet) for _ in range(length))
+
+
+def generate_shortcodes(length: int, count: int, alphabet: str = SHORTCODE_CHARS) -> list[str]:
+    """
+    Return ``count`` shortcodes.
+
+    Codes are independent, so duplicates are possible; if they must be distinct,
+    check them against whatever store they are destined for.
+    """
+    return [generate_shortcode(length, alphabet) for _ in range(count)]

corekit/utils/payload.py

@@ -0,0 +1,112 @@
+"""
+JSON argument payloads.
+
+Encodes a call's arguments as JSON so they can cross a process boundary -- a
+queue, a subprocess, a scheduler entry -- as data rather than as a serialized
+object. ``pickle`` and ``dill`` execute code while loading, so a channel
+carrying serialized objects turns "can write to the channel" into "can run code
+on the other side". JSON cannot construct an arbitrary object, so whatever runs
+always comes from the receiver's own code.
+
+Arguments are validated when they are encoded rather than when they are used,
+so a value that cannot cross fails at the call site where the offending
+argument is still visible.
+"""
+
+import base64
+import json
+from datetime import date, datetime
+from decimal import Decimal
+from enum import Enum
+from pathlib import Path
+from typing import Any, NamedTuple
+from uuid import UUID
+
+__all__ = ["Payload", "decode_payload", "encode_payload"]
+
+
+class Payload(NamedTuple):
+    """
+    The positional and keyword arguments a call was made with.
+
+    A tuple, so it still unpacks as ``args, kwargs``, but the fields are named
+    at the point they are read.
+    """
+
+    args: list[Any]
+    kwargs: dict[str, Any]
+
+
+def encode_payload(args: tuple[Any, ...] | list[Any] = (), kwargs: dict[str, Any] | None = None) -> str:
+    """
+    Encode positional and keyword arguments as a JSON string.
+
+    Raises:
+        TypeError: If any argument is not JSON-serializable, naming the value.
+            Enums encode as their value and datetimes as ISO 8601, so those
+            cross as plain data; the receiver gets the encoded form, not the
+            original object.
+    """
+    try:
+        return json.dumps({"args": list(args), "kwargs": kwargs or {}}, default=_encode_extra)
+    except TypeError as exc:
+        raise TypeError(
+            f"Arguments must be JSON-serializable so they can cross as data: {exc}. "
+            f"Pass an id or another plain value and load the object on the other side."
+        ) from exc
+
+
+def _encode_extra(value: Any) -> Any:
+    """
+    Encode the few non-JSON types that appear in ordinary arguments.
+
+    The receiver gets what comes back out -- ``"GET"`` rather than
+    ``HTTPMethod.GET`` -- so code wanting the original type reconstructs it.
+    Anything not handled here raises, which is the point: an object that cannot
+    cross as data has to be looked up on the other side instead.
+    """
+    if isinstance(value, Enum):
+        return value.value
+    if isinstance(value, (datetime, date)):
+        return value.isoformat()
+    if isinstance(value, UUID):
+        return str(value)
+    if isinstance(value, Path):
+        return str(value)
+    if isinstance(value, Decimal):
+        return str(value)
+    if isinstance(value, bytes):
+        return base64.b64encode(value).decode("ascii")
+    raise TypeError(f"Object of type {type(value).__name__} is not JSON serializable")
+
+
+def decode_payload(payload: str | bytes | None) -> Payload:
+    """
+    Decode a payload produced by ``encode_payload``.
+
+    Returns:
+        The positional arguments and keyword arguments.
+
+    Raises:
+        ValueError: If the payload is not the expected JSON object.
+    """
+    if not payload:
+        return Payload(args=[], kwargs={})
+
+    try:
+        decoded = json.loads(payload)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"Payload is not valid JSON: {exc}") from exc
+
+    if not isinstance(decoded, dict):
+        raise ValueError(f"Payload must be a JSON object, got {type(decoded).__name__}")
+
+    args = decoded.get("args", [])
+    kwargs = decoded.get("kwargs", {})
+
+    if not isinstance(args, list):
+        raise ValueError(f"Payload 'args' must be a list, got {type(args).__name__}")
+    if not isinstance(kwargs, dict):
+        raise ValueError(f"Payload 'kwargs' must be an object, got {type(kwargs).__name__}")
+
+    return Payload(args=args, kwargs=kwargs)

corekit/utils/raise_exc.py

@@ -1,8 +1,8 @@
-from typing import Any
-
-
-def raise_exc(ex: Exception, *args: Any, **kwargs: Any) -> None:
-    """
-    Generic callback function that raises the exception
-    """
-    raise ex
+from typing import Any
+
+
+def raise_exc(ex: Exception, *args: Any, **kwargs: Any) -> None:
+    """
+    Generic callback function that raises the exception
+    """
+    raise ex

corekit/utils/text.py

@@ -0,0 +1,56 @@
+"""
+String assembly helpers.
+
+Small formatters for turning collections into text a human will read -- log
+lines, notification bodies, error messages -- plus filename sanitization.
+"""
+
+import re
+from typing import Any, Literal
+
+__all__ = ["join_lines", "list_to_english", "sanitize_filename"]
+
+FALLBACK_FILENAME = "unnamed"
+_UNSAFE_CHARS = re.compile(r"[^a-z0-9\-]")
+_REPEATED_HYPHENS = re.compile(r"-{2,}")
+
+
+def join_lines(*items: Any, prefix: str = "") -> str:
+    """
+    Join items with newlines, optionally prefixing each one.
+    """
+    return "\n".join(f"{prefix}{item}" for item in items)
+
+
+def list_to_english(items: list[str], ending: Literal["and", "or"] | None = None) -> str:
+    """
+    Join items into a readable list: ``"a, b, and c"``.
+
+    Without ``ending`` the final item is joined with a plain comma, which suits
+    a bare enumeration; pass ``"and"`` or ``"or"`` for prose.
+    """
+    if not items:
+        return ""
+
+    if len(items) == 1:
+        return items[0]
+
+    buffer = ", ".join(items[:-1])
+    last = items[-1]
+
+    if ending is None:
+        return f"{buffer}, {last}"
+    return f"{buffer}, {ending} {last}"
+
+
+def sanitize_filename(raw: str, fallback: str = FALLBACK_FILENAME) -> str:
+    """
+    Reduce a string to lowercase kebab-case safe for use as a filename stem.
+
+    Everything outside ``a-z0-9-`` becomes a hyphen, runs collapse, and the
+    result is trimmed. A string with nothing usable in it returns ``fallback``
+    rather than the empty string, which would produce a nameless file.
+    """
+    cleaned = _UNSAFE_CHARS.sub("-", raw.strip().lower())
+    cleaned = _REPEATED_HYPHENS.sub("-", cleaned).strip("-")
+    return cleaned or fallback

corekit/utils/time.py

@@ -1,21 +1,74 @@
-from datetime import UTC, datetime, timedelta
-
-
-def time_now() -> datetime:
-    """
-    Helper for getting the current UTC time
-    """
-    return datetime.now(UTC)
-
-
-def timedelta_now(delta_seconds: int | None = None, add_time: bool = False, **kwargs) -> datetime:
-    """
-    Helper for getting a quick timedelta
-    """
-    if delta_seconds is not None:
-        kwargs = {"seconds": delta_seconds}
-
-    delta = timedelta(**kwargs)
-    if add_time:
-        return time_now() + delta
-    return time_now() - delta
+"""
+Timezone-aware time helpers.
+
+Every function returns UTC. Naive datetimes are the usual source of "works on
+my machine" time bugs, so nothing here produces one.
+"""
+
+import re
+from datetime import UTC, datetime, timedelta
+from typing import Any
+
+__all__ = ["isoformat_now", "parse_docker_timestamp", "time_now", "timedelta_now", "timestamp_now"]
+
+# Docker reports nanosecond precision; fromisoformat accepts at most microseconds.
+_DOCKER_TS_PATTERN = re.compile(r"(\.\d{6})\d*")
+
+# Docker's zero value for "this never happened".
+_DOCKER_ZERO_TIME = "0001-01-01"
+
+
+def time_now() -> datetime:
+    """
+    Return the current UTC time, timezone-aware.
+    """
+    return datetime.now(UTC)
+
+
+def isoformat_now() -> str:
+    """
+    Return the current UTC time as an ISO 8601 string.
+    """
+    return time_now().isoformat()
+
+
+def timestamp_now() -> float:
+    """
+    Return the current UTC time as a Unix timestamp.
+    """
+    return time_now().timestamp()
+
+
+def timedelta_now(delta_seconds: int | None = None, add_time: bool = False, **kwargs: Any) -> datetime:
+    """
+    Return a time offset from now, in the past by default.
+
+    Pass ``delta_seconds`` for the common case, or any ``timedelta`` keyword
+    (``days``, ``hours``, ...) for the rest. ``add_time`` moves forward instead
+    of back.
+    """
+    if delta_seconds is not None:
+        kwargs = {"seconds": delta_seconds}
+
+    delta = timedelta(**kwargs)
+    if add_time:
+        return time_now() + delta
+    return time_now() - delta
+
+
+def parse_docker_timestamp(value: str | None) -> float | None:
+    """
+    Parse a docker API timestamp into a Unix timestamp, or ``None``.
+
+    Docker emits nanosecond-precision ISO 8601 (a container's ``State.StartedAt``,
+    for instance), which ``fromisoformat`` rejects. Returns ``None`` for empty
+    input, docker's zero timestamp, and anything unparseable, so a caller can
+    treat "no such time" and "bad time" the same way.
+    """
+    if not value or value.startswith(_DOCKER_ZERO_TIME):
+        return None
+    try:
+        trimmed = _DOCKER_TS_PATTERN.sub(r"\1", value.replace("Z", "+00:00"))
+        return datetime.fromisoformat(trimmed).timestamp()
+    except ValueError:
+        return None

corekit/utils/validators.py

@@ -1,15 +1,15 @@
-from typing import Any
-
-
-def true_validator(*args: Any, **kwargs: Any) -> bool:
-    """
-    Generic placeholder validator function that always returns True
-    """
-    return True
-
-
-def false_validator(*args: Any, **kwargs: Any) -> bool:
-    """
-    Generic placeholder validator function that always returns False
-    """
-    return False
+from typing import Any
+
+
+def true_validator(*args: Any, **kwargs: Any) -> bool:
+    """
+    Generic placeholder validator function that always returns True
+    """
+    return True
+
+
+def false_validator(*args: Any, **kwargs: Any) -> bool:
+    """
+    Generic placeholder validator function that always returns False
+    """
+    return False

corekit/utils/void.py

@@ -1,8 +1,8 @@
-from typing import Any
-
-
-def void(ex: Exception, *args: Any, **kwargs: Any) -> None:
-    """
-    Generic callback function that does nothing and returns nothing
-    """
-    pass
+from typing import Any
+
+
+def void(ex: Exception, *args: Any, **kwargs: Any) -> None:
+    """
+    Generic callback function that does nothing and returns nothing
+    """
+    pass