python-corekit 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

corekit/schemas/pydantic/fields.py

@@ -1,35 +1,35 @@
-from typing import Any
-
-from pydantic import Field
-
-
-def DefaultStringField(*args: Any, default: Any = "", **kwargs: Any) -> Field:
-    return Field(default=default, *args, **kwargs)
-
-
-def DefaultIntField(*args: Any, default: Any = 0, **kwargs: Any) -> Field:
-    return Field(default=default, *args, **kwargs)
-
-
-def DefaultFloatField(*args: Any, default: Any = 0.0, **kwargs: Any) -> Field:
-    return Field(default=default, *args, **kwargs)
-
-
-def DefaultBoolField(*args: Any, default: Any = False, **kwargs: Any) -> Field:
-    return Field(default=default, *args, **kwargs)
-
-
-def DefaultEmptyField(*args: Any, default: Any = None, **kwargs: Any) -> Field:
-    return Field(default=default, *args, **kwargs)
-
-
-def DefaultListField(*args: Any, default_factory: Any = list, **kwargs: Any) -> Field:
-    return Field(default_factory=default_factory, *args, **kwargs)
-
-
-def DefaultSetField(*args: Any, default_factory: Any = set, **kwargs: Any) -> Field:
-    return Field(default_factory=default_factory, *args, **kwargs)
-
-
-def DefaultDictField(*args: Any, default_factory: Any = dict, **kwargs: Any) -> Field:
-    return Field(default_factory=default_factory, *args, **kwargs)
+from typing import Any
+
+from pydantic import Field
+
+
+def DefaultStringField(*args: Any, default: Any = "", **kwargs: Any) -> Field:
+    return Field(default=default, *args, **kwargs)
+
+
+def DefaultIntField(*args: Any, default: Any = 0, **kwargs: Any) -> Field:
+    return Field(default=default, *args, **kwargs)
+
+
+def DefaultFloatField(*args: Any, default: Any = 0.0, **kwargs: Any) -> Field:
+    return Field(default=default, *args, **kwargs)
+
+
+def DefaultBoolField(*args: Any, default: Any = False, **kwargs: Any) -> Field:
+    return Field(default=default, *args, **kwargs)
+
+
+def DefaultEmptyField(*args: Any, default: Any = None, **kwargs: Any) -> Field:
+    return Field(default=default, *args, **kwargs)
+
+
+def DefaultListField(*args: Any, default_factory: Any = list, **kwargs: Any) -> Field:
+    return Field(default_factory=default_factory, *args, **kwargs)
+
+
+def DefaultSetField(*args: Any, default_factory: Any = set, **kwargs: Any) -> Field:
+    return Field(default_factory=default_factory, *args, **kwargs)
+
+
+def DefaultDictField(*args: Any, default_factory: Any = dict, **kwargs: Any) -> Field:
+    return Field(default_factory=default_factory, *args, **kwargs)

corekit/schemas/types.py

@@ -1,40 +1,40 @@
-from datetime import date, datetime
-from typing import Any, Sequence
-
-# ========== Primitive Types ==========
-Number = int | float
-AnyPrimitive = str | bool | Number
-
-# ========== Dict Types ==========
-StringDict = dict[str, str]
-CounterDict = dict[str, int]
-StatisticDict = dict[str, Number]
-AnyDict = dict[str, Any]
-UnknownDict = dict[Any, Any]
-
-# ========== Sequence Types ==========
-# Using the more broad "Sequence" type instead of "List" to allow for other sequence types like "tuple"
-StringSequence = Sequence[str]
-IntegerSequence = Sequence[int]
-FloatSequence = Sequence[float]
-NumberSequence = Sequence[Number]
-BooleanSequence = Sequence[bool]
-UnknownSequence = Sequence[Any]
-
-# Using the more specific "list" and "set types allows for more rigid type checking
-StringList = list[str]
-IntegerList = list[int]
-FloatList = list[float]
-NumberList = list[Number]
-BooleanList = list[bool]
-UnknownList = list[Any]
-
-StringSet = set[str]
-IntegerSet = set[int]
-FloatSet = set[float]
-NumberSet = set[Number]
-BooleanSet = set[bool]
-UnknownSet = set[Any]
-
-# ========== Date Types ==========
-ArbitraryDate = date | datetime
+from datetime import date, datetime
+from typing import Any, Sequence
+
+# ========== Primitive Types ==========
+Number = int | float
+AnyPrimitive = str | bool | Number
+
+# ========== Dict Types ==========
+StringDict = dict[str, str]
+CounterDict = dict[str, int]
+StatisticDict = dict[str, Number]
+AnyDict = dict[str, Any]
+UnknownDict = dict[Any, Any]
+
+# ========== Sequence Types ==========
+# Using the more broad "Sequence" type instead of "List" to allow for other sequence types like "tuple"
+StringSequence = Sequence[str]
+IntegerSequence = Sequence[int]
+FloatSequence = Sequence[float]
+NumberSequence = Sequence[Number]
+BooleanSequence = Sequence[bool]
+UnknownSequence = Sequence[Any]
+
+# Using the more specific "list" and "set types allows for more rigid type checking
+StringList = list[str]
+IntegerList = list[int]
+FloatList = list[float]
+NumberList = list[Number]
+BooleanList = list[bool]
+UnknownList = list[Any]
+
+StringSet = set[str]
+IntegerSet = set[int]
+FloatSet = set[float]
+NumberSet = set[Number]
+BooleanSet = set[bool]
+UnknownSet = set[Any]
+
+# ========== Date Types ==========
+ArbitraryDate = date | datetime

corekit/serialization/__init__.py

@@ -0,0 +1,22 @@
+"""
+Serialization with authenticated payloads.
+
+``pickle`` and ``dill`` execute code while loading, so a payload must be proven
+to come from a holder of the shared key *before* it is decoded, and the decoder
+is chosen by the receiver rather than read out of the payload. JSON is the
+default because it cannot execute code at all.
+
+Set a key with ``COREKIT_SERIALIZATION__KEY`` to use an executing engine.
+"""
+
+from corekit.serialization.enum import SerializerEngine
+from corekit.serialization.serializable import Serializable
+from corekit.serialization.serializer import Serializer, SignatureError, UnsafeEngineError
+
+__all__ = [
+    "Serializable",
+    "Serializer",
+    "SerializerEngine",
+    "SignatureError",
+    "UnsafeEngineError",
+]

corekit/serialization/serializer.py

@@ -69,7 +69,7 @@ class Serializer:
         if self._engine in EXECUTING_ENGINES and self._key is None:
             raise UnsafeEngineError(
                 f"{self._engine.value} executes code when loading, so it needs a key to authenticate "
-                f"payloads. Pass key=..., set COREKIT_SERIALIZATION_KEY, or use SerializerEngine.JSON."
+                f"payloads. Pass key=..., set COREKIT_SERIALIZATION__KEY, or use SerializerEngine.JSON."
             )
 
     @staticmethod

corekit/utils/__init__.py

@@ -1,5 +1,59 @@
-from .ids import generate_uuid
-from .raise_exc import raise_exc
-from .time import time_now, timedelta_now
-from .validators import false_validator, true_validator
-from .void import void
+"""
+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.
+"""
+
+from corekit.utils.coercion import safe_dict, safe_float, safe_int, safe_list, safe_string, safe_tuple
+from corekit.utils.collections import UNSET, MultiMatch, keygetter, repeated_get, split_list
+from corekit.utils.ids import (
+    SHORTCODE_CHARS,
+    generate_session_token,
+    generate_shortcode,
+    generate_shortcodes,
+    generate_uuid,
+)
+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
+from corekit.utils.time import isoformat_now, parse_docker_timestamp, time_now, timedelta_now, timestamp_now
+from corekit.utils.validators import false_validator, true_validator
+from corekit.utils.void import void
+
+__all__ = [
+    "SHORTCODE_CHARS",
+    "UNSET",
+    "MultiMatch",
+    "Payload",
+    "decode_payload",
+    "encode_payload",
+    "false_validator",
+    "generate_session_token",
+    "generate_shortcode",
+    "generate_shortcodes",
+    "generate_uuid",
+    "isoformat_now",
+    "join_lines",
+    "keygetter",
+    "list_to_english",
+    "parse_docker_timestamp",
+    "raise_exc",
+    "repeated_get",
+    "safe_dict",
+    "safe_float",
+    "safe_int",
+    "safe_list",
+    "safe_string",
+    "safe_tuple",
+    "sanitize_filename",
+    "split_list",
+    "time_now",
+    "timedelta_now",
+    "timestamp_now",
+    "true_validator",
+    "void",
+]

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,115 @@
+"""
+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``.
+        """
+        for key, value in data.items():
+            if self.func(key):
+                self._keymap[key] = value
+
+        if not self._keymap:
+            return UNSET
+
+        if len(self._keymap) == 1:
+            return next(iter(self._keymap.values()))
+
+        return self._keymap
+
+
+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 fallback
+
+        if isinstance(key, keygetter):
+            return key.func(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():
+                if not isinstance(branch, dict):
+                    continue
+                for child_key, child_value in branch.items():
+                    collected[child_key] = _get_item(child_value, key)
+            result = deepcopy(collected)
+        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,100 @@
+"""
+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 json
+from datetime import date, datetime
+from enum import Enum
+from typing import Any, NamedTuple
+
+__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()
+    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