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

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

@@ -0,0 +1,10 @@
+"""
+Shared types.
+
+The enum bases validate their members on construction, so an unknown value
+raises where it is introduced rather than somewhere further along.
+"""
+
+from corekit.schemas.enum import IntegerEnum, StringEnum, ValidatingEnum
+
+__all__ = ["IntegerEnum", "StringEnum", "ValidatingEnum"]

corekit/schemas/enum.py

@@ -1,49 +1,70 @@
-from enum import Enum
-from typing import Any
-
-
-class ValidatingEnum(Enum):
-    """
-    A base class for enums that validates values against a set of allowed values.
-    """
-
-    @classmethod
-    def is_member(cls, value: Any) -> bool:
-        """
-        Check if the value is a member of the enum.
-        """
-        return value in cls._value2member_map_
-
-    @classmethod
-    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}")
-
-    @classmethod
-    def get_all_members(cls) -> list["ValidatingEnum"]:
-        """
-        Get all members of the enum.
-        """
-        return list(cls._value2member_map_.values())  # type: ignore[return-value]
-
-    def display_name(self) -> str:
-        return self.name.replace("_", " ").title()
-
-
-class StringEnum(str, ValidatingEnum):
-    @classmethod
-    def from_string(cls, value: str) -> "StringEnum":
-        """
-        Convert a string to the corresponding enum member.
-        """
-        return cls.validate_and_create(value)
-
-
-class IntegerEnum(int, ValidatingEnum):
-    @classmethod
-    def from_int(cls, value: int) -> "IntegerEnum":
-        """
-        Convert an integer to the corresponding enum member.
-        """
-        return cls.validate_and_create(value)
+from enum import Enum
+from typing import Any
+
+
+class ValidatingEnum(Enum):
+    """
+    A base class for enums that validates values against a set of allowed values.
+    """
+
+    @classmethod
+    def is_member(cls, value: Any) -> bool:
+        """
+        Check if the value is a member of the enum.
+        """
+        return value in cls._value2member_map_
+
+    @classmethod
+    def validate_and_create(cls, value: Any) -> "ValidatingEnum":
+        if cls.is_member(value):
+            return cls(value)
+        raise ValueError(f"{cls.__name__} does not contain {value!r}")
+
+    @classmethod
+    def get_all_members(cls) -> list["ValidatingEnum"]:
+        """
+        Get all members of the enum.
+        """
+        return list(cls._value2member_map_.values())  # type: ignore[return-value]
+
+    def display_name(self) -> str:
+        return self.name.replace("_", " ").title()
+
+
+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":
+        """
+        Convert a string 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)
+
+
+class IntegerEnum(int, ValidatingEnum):
+    @classmethod
+    def from_int(cls, value: int) -> "IntegerEnum":
+        """
+        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/models/arbitrary.py

@@ -1,11 +1,11 @@
-from pydantic import BaseModel
-
-
-class ArbitraryModel(BaseModel):
-    """
-    Base model for arbitrary data. This model is used to take unstructured data and convert it into
-    a structured format that can be easily mapped to a model. This model is capable of parsing any type of data
-    and converting it into a structured format that can be easily accessed and manipulated.
-    """
-
-    pass
+from pydantic import BaseModel
+
+
+class ArbitraryModel(BaseModel):
+    """
+    Base model for arbitrary data. This model is used to take unstructured data and convert it into
+    a structured format that can be easily mapped to a model. This model is capable of parsing any type of data
+    and converting it into a structured format that can be easily accessed and manipulated.
+    """
+
+    pass

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,45 @@
-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, Awaitable, Callable, Coroutine, 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
+
+# ========== Function Types ==========
+AsyncFunction = Callable[..., Awaitable[Any] | Coroutine[Any, Any, Any]]
+SyncFunction = Callable[..., Any]
+ArbitraryFunction = AsyncFunction | SyncFunction

corekit/serialization/__init__.py

@@ -0,0 +1,24 @@
+"""
+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.pickle_file import PickleFileManager
+from corekit.serialization.serializable import Serializable
+from corekit.serialization.serializer import Serializer, SignatureError, UnsafeEngineError
+
+__all__ = [
+    "PickleFileManager",
+    "Serializable",
+    "Serializer",
+    "SerializerEngine",
+    "SignatureError",
+    "UnsafeEngineError",
+]

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:
     """
@@ -69,7 +76,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",
+]