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

corekit/observability/timing/split.py

@@ -8,6 +8,20 @@ class Split(BaseModel):
     name: str | None = None
     split_name: str | None = None
 
+    @property
+    def total_ms(self) -> float:
+        """
+        ``total`` in milliseconds.
+        """
+        return self.total * 1000
+
+    @property
+    def latest_ms(self) -> float:
+        """
+        ``latest`` in milliseconds.
+        """
+        return self.latest * 1000
+
     def __str__(self) -> str:
         identifier = ""
         if self.name:

corekit/observability/timing/timer.py

@@ -5,26 +5,50 @@ from corekit.observability.timing.split import Split
 
 
 class Timer:
+    start: float
+    latest: float
+    num: int
+    precision: int
+    name: str
+
     def __init__(self, precision: int = DEFAULT_PRECISION) -> None:
-        _time = time.time()
-        self.start = _time
-        self.latest = _time
-        self.num = 0
-        self.name = type(self).__name__
+        # perf_counter is monotonic. time.time() can step backwards, which
+        # makes a split look negative for no reason the caller can act on.
         self.precision = precision if precision > 0 else DEFAULT_PRECISION
+        self.name = type(self).__name__
+        self.reset()
+
+    def reset(self) -> None:
+        """
+        Restart the clock and clear split numbering.
+
+        Use at the start of a new timed unit of work (a request, a model turn,
+        a pipeline stage) so ``total`` measures that unit rather than the
+        object's whole lifetime.
+        """
+        now = time.perf_counter()
+        self.start = now
+        self.latest = now
+        self.num = 0
 
     def _round(self, value: float) -> float:
         return round(value, self.precision)
 
+    def elapsed(self) -> float:
+        """
+        Seconds since start (or last ``reset``), without recording a split.
+        """
+        return self._round(time.perf_counter() - self.start)
+
     def split(self, split_name: str | None = None) -> Split:
-        _time = time.time()
+        now = time.perf_counter()
         self.num += 1
         split = Split(
             num=self.num,
-            total=self._round(_time - self.start),
-            latest=self._round(_time - self.latest),
+            total=self._round(now - self.start),
+            latest=self._round(now - self.latest),
             name=self.name,
             split_name=split_name,
         )
-        self.latest = _time
+        self.latest = now
         return split

corekit/registry/__init__.py

@@ -12,6 +12,6 @@ duplicates. Reach for it when position is what matters and no name is needed.
 """
 
 from corekit.registry.ordered import OrderedRegistry
-from corekit.registry.registry import SmartRegistry
+from corekit.registry.registry import SmartRegistry, normalize_key
 
-__all__ = ["OrderedRegistry", "SmartRegistry"]
+__all__ = ["OrderedRegistry", "SmartRegistry", "normalize_key"]

corekit/registry/registry.py

@@ -1,11 +1,17 @@
+import logging
 import re
 from typing import Any, Iterator
 
+from corekit.config import get_settings
+
 REPLACEMENT_CHAR = "-"
 NORMALIZATION_PATTERN = re.compile(r"[\s_-]+")
 # Split CamelCase into words: "HTTPServerError" -> "HTTP-Server-Error".
 CAMEL_BOUNDARY_PATTERN = re.compile(r"(?<=[a-z0-9])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])")
 
+_logger = logging.getLogger("SmartRegistry")
+_MISSING = object()
+
 
 class SmartRegistry:
     """
@@ -31,19 +37,33 @@ class SmartRegistry:
         """
         Retrieve an item from the registry using a normalized key.
         """
-        return self.__registry__[self.__normalize_key__(key)]
+        return self.__registry__[normalize_key(key)]
 
     def __setitem__(self, key: str, value: Any) -> None:
         """
         Store an item in the registry with a normalized key.
-        """
-        self.__registry__[self.__normalize_key__(key)] = value
+
+        A second write to the same normalized key used to replace the first
+        with no signal. That drops a handler that spelled the same name a
+        different way. The replacement is still allowed so an intentional
+        update works; it is warned, and refused when ``strict_mode`` is on.
+        """
+        normalized = normalize_key(key)
+        existing = self.__registry__.get(normalized, _MISSING)
+        if existing is not _MISSING and existing is not value:
+            if _strict_mode():
+                raise ValueError(
+                    f"Registry already contains {normalized!r}. "
+                    f"strict_mode refuses a second registration under the same key."
+                )
+            _logger.warning(f"Overwriting registry key {normalized!r}")
+        self.__registry__[normalized] = value
 
     def __delitem__(self, key: str) -> None:
         """
         Remove an item from the registry.
         """
-        del self.__registry__[self.__normalize_key__(key)]
+        del self.__registry__[normalize_key(key)]
 
     def __iter__(self) -> Iterator[str]:
         """
@@ -73,7 +93,7 @@ class SmartRegistry:
         """
         Check if a normalized key exists in the registry.
         """
-        return self.__normalize_key__(key) in self.__registry__
+        return normalize_key(key) in self.__registry__
 
     def __str__(self) -> str:
         """
@@ -114,21 +134,42 @@ class SmartRegistry:
         self.__registry__ = state
 
     @staticmethod
-    def __normalize_key__(key: str) -> str:
+    def normalize_key(key: str) -> str:
         """
         Reduce a key to a canonical hyphenated form.
 
-        Word boundaries are taken from CamelCase as well as from whitespace,
-        underscores and hyphens, so ``"GreetingHandler"``, ``"greeting_handler"``
-        and ``"Greeting Handler"`` all normalize to ``"greeting-handler"``.
-        Without the CamelCase step a class registered under its ``__name__``
-        could not be found by the snake_case name a caller would naturally type.
+        Public so callers do not have to reach for the old private name.
+        ``__normalize_key__`` remains as an alias.
         """
-        spaced = CAMEL_BOUNDARY_PATTERN.sub(REPLACEMENT_CHAR, key.strip())
-        return NORMALIZATION_PATTERN.sub(REPLACEMENT_CHAR, spaced.lower()).strip(REPLACEMENT_CHAR)
+        return normalize_key(key)
+
+    # Kept so existing callers, including ThreadLocalRegistry and tests, keep
+    # working. New code should call ``normalize_key``.
+    __normalize_key__ = staticmethod(normalize_key)
 
     def get(self, key: str, fallback: Any = None) -> Any:
         """
         Safely retrieve an item from the registry with an optional fallback.
         """
-        return self.__registry__.get(self.__normalize_key__(key), fallback)
+        return self.__registry__.get(normalize_key(key), fallback)
+
+
+def _strict_mode() -> bool:
+    """
+    Whether a colliding key should be refused.
+    """
+    return get_settings().standards.strict_mode
+
+
+def normalize_key(key: str) -> str:
+    """
+    Reduce a key to a canonical hyphenated form.
+
+    Word boundaries are taken from CamelCase as well as from whitespace,
+    underscores and hyphens, so ``"GreetingHandler"``, ``"greeting_handler"``
+    and ``"Greeting Handler"`` all normalize to ``"greeting-handler"``.
+    Without the CamelCase step a class registered under its ``__name__``
+    could not be found by the snake_case name a caller would naturally type.
+    """
+    spaced = CAMEL_BOUNDARY_PATTERN.sub(REPLACEMENT_CHAR, key.strip())
+    return NORMALIZATION_PATTERN.sub(REPLACEMENT_CHAR, spaced.lower()).strip(REPLACEMENT_CHAR)

corekit/schemas/__init__.py

@@ -6,5 +6,6 @@ raises where it is introduced rather than somewhere further along.
 """
 
 from corekit.schemas.enum import IntegerEnum, StringEnum, ValidatingEnum
+from corekit.schemas.version import SemanticVersion
 
-__all__ = ["IntegerEnum", "StringEnum", "ValidatingEnum"]
+__all__ = ["IntegerEnum", "SemanticVersion", "StringEnum", "ValidatingEnum"]

corekit/schemas/enum.py

@@ -18,7 +18,7 @@ class ValidatingEnum(Enum):
     def validate_and_create(cls, value: Any) -> "ValidatingEnum":
         if cls.is_member(value):
             return cls(value)
-        raise ValueError(f"{cls.__name__} does not contain {cls}")
+        raise ValueError(f"{cls.__name__} does not contain {value!r}")
 
     @classmethod
     def get_all_members(cls) -> list["ValidatingEnum"]:
@@ -32,6 +32,15 @@ class ValidatingEnum(Enum):
 
 
 class StringEnum(str, ValidatingEnum):
+    """
+    String-valued enum that stringifies to its value.
+
+    Plain ``(str, Enum)`` members compare equal to their value but ``str()`` /
+    f-strings still render as ``ClassName.MEMBER``. Override that so DB defaults,
+    status comparisons, and log lines get ``"pending"`` rather than
+    ``"AccountRequestStatus.PENDING"``.
+    """
+
     @classmethod
     def from_string(cls, value: str) -> "StringEnum":
         """
@@ -39,6 +48,12 @@ class StringEnum(str, ValidatingEnum):
         """
         return cls.validate_and_create(value)
 
+    def __str__(self) -> str:
+        return str(self.value)
+
+    def __format__(self, format_spec: str) -> str:
+        return self.value.__format__(format_spec)
+
 
 class IntegerEnum(int, ValidatingEnum):
     @classmethod
@@ -47,3 +62,9 @@ class IntegerEnum(int, ValidatingEnum):
         Convert an integer to the corresponding enum member.
         """
         return cls.validate_and_create(value)
+
+    def __str__(self) -> str:
+        return str(self.value)
+
+    def __format__(self, format_spec: str) -> str:
+        return self.value.__format__(format_spec)

corekit/schemas/types.py

@@ -1,5 +1,5 @@
 from datetime import date, datetime
-from typing import Any, Sequence
+from typing import Any, Awaitable, Callable, Coroutine, Sequence
 
 # ========== Primitive Types ==========
 Number = int | float
@@ -38,3 +38,8 @@ UnknownSet = set[Any]
 
 # ========== Date Types ==========
 ArbitraryDate = date | datetime
+
+# ========== Function Types ==========
+AsyncFunction = Callable[..., Awaitable[Any] | Coroutine[Any, Any, Any]]
+SyncFunction = Callable[..., Any]
+ArbitraryFunction = AsyncFunction | SyncFunction

corekit/schemas/version.py

@@ -0,0 +1,58 @@
+"""
+Semantic version (``major.minor.patch`` with optional ``-extra``).
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Self
+
+from pydantic import BaseModel, Field
+
+from corekit.utils import safe_int, safe_string
+
+__all__ = ["SemanticVersion"]
+
+_VERSION_RE = re.compile(r"^(?P<major>\d+)(?:\.(?P<minor>\d+)(?:\.(?P<patch>\d+)?)?)?(?:-(?P<extra>[A-Za-z0-9._-]+))?$")
+
+
+class SemanticVersion(BaseModel):
+    """
+    Structured ``major.minor.patch`` with an optional ``-extra`` suffix.
+
+    Suitable for filenames, config pins, and other places that need a parsed
+    SemVer-like value without tying to packaging metadata.
+    """
+
+    major: int = Field(ge=0)
+    minor: int = Field(default=0, ge=0)
+    patch: int = Field(default=0, ge=0)
+    extra: str | None = None
+
+    def __str__(self) -> str:
+        version = f"{self.major}.{self.minor}.{self.patch}"
+        if self.extra:
+            return f"{version}-{self.extra}"
+        return version
+
+    def __repr__(self) -> str:
+        return f"SemanticVersion({self})"
+
+    @classmethod
+    def parse(cls, value: SemanticVersion | str | int) -> Self:
+        """
+        Accept a version object, ``\"1.0.0\"``, or a bare major ``1`` (→ ``1.0.0``).
+        """
+        if isinstance(value, SemanticVersion):
+            return value
+        if isinstance(value, int):
+            return cls(major=value)
+        match = _VERSION_RE.fullmatch(safe_string(value))
+        if match is None:
+            raise ValueError(f"Invalid semantic version: {value!r}")
+        return cls(
+            major=safe_int(match.group("major")),
+            minor=safe_int(match.group("minor")),
+            patch=safe_int(match.group("patch")),
+            extra=match.group("extra"),
+        )

corekit/serialization/__init__.py

@@ -10,10 +10,12 @@ Set a key with ``COREKIT_SERIALIZATION__KEY`` to use an executing engine.
 """
 
 from corekit.serialization.enum import SerializerEngine
+from corekit.serialization.pickle_file import PickleFileManager
 from corekit.serialization.serializable import Serializable
 from corekit.serialization.serializer import Serializer, SignatureError, UnsafeEngineError
 
 __all__ = [
+    "PickleFileManager",
     "Serializable",
     "Serializer",
     "SerializerEngine",

corekit/serialization/pickle_file.py

@@ -0,0 +1,61 @@
+"""
+Reading and writing signed pickle files.
+
+Pickle executes code on load. ``PickleFileManager`` therefore requires a key
+and stores authenticated payloads via ``Serializer``, never bare ``pickle.dumps``.
+Partial reads and line streaming are refused: a pickle document is not
+line-oriented and a fragment is not a valid payload.
+
+Lives under ``serialization`` rather than ``files`` so ``corekit.config`` can
+import ``TomlFileManager`` without forming a files ↔ serialization cycle.
+"""
+
+from typing import Any, Iterator
+
+from corekit.files.base import FileContent, FileError, FileManager
+from corekit.files.enum import FileMode
+from corekit.serialization.enum import SerializerEngine
+from corekit.serialization.serializer import Serializer
+
+__all__ = ["PickleFileManager"]
+
+
+class PickleFileManager(FileManager):
+    """
+    A FileManager that round-trips values through a signed pickle ``Serializer``.
+    """
+
+    def __init__(
+        self,
+        file_path: str,
+        mode: FileMode | None = None,
+        *,
+        key: bytes | str,
+        binary: bool = True,
+    ) -> None:
+        if not binary:
+            raise FileError("PickleFileManager requires binary mode; pickle payloads are bytes.")
+        super().__init__(file_path, mode=mode or FileMode.get_default(binary=True), binary=True)
+        self._serializer = Serializer(SerializerEngine.PICKLE, key=key)
+
+    def _serialize(self, content: Any) -> FileContent:
+        return self._serializer.serialize(content)
+
+    def _deserialize(self, content: FileContent) -> Any:
+        if isinstance(content, str):
+            content = content.encode("utf-8")
+        return self._serializer.deserialize(content)
+
+    def read(self, size: int = -1) -> Any:
+        """
+        Read and verify the whole file. Partial reads are refused.
+        """
+        if size != -1:
+            raise FileError("PickleFileManager refuses partial reads; read the whole file with size=-1.")
+        return super().read(size)
+
+    def readline(self) -> Any:
+        raise FileError("PickleFileManager cannot readline; pickle payloads are not line-oriented.")
+
+    def stream(self) -> Iterator[Any]:
+        raise FileError("PickleFileManager cannot stream; pickle payloads are not line-oriented.")

corekit/serialization/serializable.py

@@ -15,11 +15,28 @@ class Serializable:
 
     Serializing an arbitrary object needs pickle or dill, both of which execute
     code on load, so a key is required -- see ``Serializer``.
+
+    The HMAC key on ``_serializer`` is never written into the payload. Signing
+    authenticates provenance; it is not encryption.
     """
 
     def __init__(self, **kwargs: Any) -> None:
         self._serializer = Serializer(**kwargs)
 
+    def __getstate__(self) -> dict[str, Any]:
+        """
+        Drop ``_serializer`` so a pickle/dill payload cannot carry the HMAC key.
+        """
+        state = self.__dict__.copy()
+        state.pop("_serializer", None)
+        return state
+
+    def __setstate__(self, state: dict[str, Any]) -> None:
+        """
+        Restore instance state. The serializer is reattached by ``from_serialized``.
+        """
+        self.__dict__.update(state)
+
     @classmethod
     def from_serialized(cls, serialized: bytes, **kwargs: Any) -> Any:
         """
@@ -28,11 +45,14 @@ class Serializable:
         The engine and key are supplied by the caller rather than read from the
         payload, so the receiver decides how the bytes are decoded.
         """
-        return Serializer(**kwargs).deserialize(serialized)
+        obj = Serializer(**kwargs).deserialize(serialized)
+        if isinstance(obj, Serializable):
+            obj._serializer = Serializer(**kwargs)
+        return obj
 
     def serialize(self) -> bytes:
         """
-        Encode this object.
+        Encode this object without embedding the HMAC key.
         """
         if not self._serializer.is_valid_for_class():
             raise TypeError(

corekit/serialization/serializer.py

@@ -24,6 +24,7 @@ from typing import Any
 import dill
 
 from corekit.config import get_settings
+from corekit.exceptions import InternalCoreException, Retryability
 from corekit.serialization.enum import SerializerEngine
 
 __all__ = ["Serializer", "SignatureError", "UnsafeEngineError"]
@@ -42,17 +43,23 @@ _ENGINE_MODULES = {
 }
 
 
-class SignatureError(Exception):
+class SignatureError(InternalCoreException):
     """
     Raised when a payload's signature is missing or does not verify.
     """
 
+    def __init__(self, message: str, *, error: str | None = None) -> None:
+        super().__init__(message, retryable=Retryability.NON_RETRYABLE, error=error)
 
-class UnsafeEngineError(Exception):
+
+class UnsafeEngineError(InternalCoreException):
     """
     Raised when a code-executing engine is requested without a key.
     """
 
+    def __init__(self, message: str, *, error: str | None = None) -> None:
+        super().__init__(message, retryable=Retryability.NON_RETRYABLE, error=error)
+
 
 class Serializer:
     """

corekit/utils/__init__.py

@@ -9,7 +9,7 @@ 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.collections import UNSET, MultiMatch, attr_or_key, keygetter, repeated_get, split_list
 from corekit.utils.ids import (
     SHORTCODE_CHARS,
     generate_session_token,
@@ -29,6 +29,7 @@ __all__ = [
     "UNSET",
     "MultiMatch",
     "Payload",
+    "attr_or_key",
     "decode_payload",
     "encode_payload",
     "false_validator",

corekit/utils/collections.py

@@ -10,7 +10,7 @@ missing or the wrong type.
 from copy import deepcopy
 from typing import Any, Callable
 
-__all__ = ["MultiMatch", "keygetter", "repeated_get", "split_list"]
+__all__ = ["MultiMatch", "attr_or_key", "keygetter", "repeated_get", "split_list"]
 
 KEY_SEPARATOR = "."
 
@@ -25,6 +25,21 @@ def split_list(items: list[Any], index: int) -> tuple[list[Any], list[Any]]:
     return items[:index], items[index:]
 
 
+def attr_or_key(obj: Any, name: str) -> Any:
+    """
+    Read ``name`` from a mapping or an object attribute.
+
+    Returns ``None`` when ``obj`` is ``None``, the key is missing, or the
+    attribute is absent. Useful for SDK payloads that arrive as either dicts
+    or attribute-bearing chunk objects.
+    """
+    if obj is None:
+        return None
+    if isinstance(obj, dict):
+        return obj.get(name)
+    return getattr(obj, name, None)
+
+
 class MultiMatch(dict[str, Any]):
     """
     The result of a path step that matched more than one key.
@@ -56,18 +71,24 @@ class keygetter:
     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):
-                self._keymap[key] = value
+                matches[key] = value
+        self._keymap = matches
 
-        if not self._keymap:
+        if not matches:
             return UNSET
 
-        if len(self._keymap) == 1:
-            return next(iter(self._keymap.values()))
+        if len(matches) == 1:
+            return next(iter(matches.values()))
 
-        return self._keymap
+        return matches
 
 
 def repeated_get(
@@ -91,10 +112,14 @@ def repeated_get(
 
     def _get_item(current: Any, key: str | keygetter) -> Any | MultiMatch:
         if current is UNSET or not isinstance(current, dict):
-            return fallback
+            return UNSET
 
         if isinstance(key, keygetter):
-            return key.func(current)
+            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)
 
@@ -103,12 +128,11 @@ def repeated_get(
     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)
+            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)
 

corekit/utils/payload.py

@@ -13,10 +13,14 @@ 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"]
 
@@ -65,6 +69,14 @@ def _encode_extra(value: Any) -> Any:
         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")