python-corekit 0.1.0__py3-none-any.whl

corekit/observability/benchmarkable.py

@@ -0,0 +1,12 @@
+from corekit.observability.loggable import Loggable
+from corekit.observability.timing.timer import Timer
+
+
+class Benchmarkable(Loggable):
+    def __init__(self) -> None:
+        super().__init__()
+        self._timing = Timer()
+
+    def timing(self, split_name: str | None = None) -> None:
+        split_message = str(self._timing.split(split_name=split_name))
+        self.info(split_message)

corekit/observability/loggable.py

@@ -0,0 +1,29 @@
+import logging
+from typing import Any
+
+
+class Loggable:
+    """
+    Base class with a built-in logger named after the concrete class.
+
+    Accepts and ignores ``*args``/``**kwargs`` so it can sit anywhere in a
+    cooperative ``super().__init__()`` chain.
+    """
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        self.logger = logging.getLogger(self.__class__.__name__)
+
+    def debug(self, message: str, **kwargs: Any) -> None:
+        self.logger.debug(message, **kwargs)
+
+    def info(self, message: str, **kwargs: Any) -> None:
+        self.logger.info(message, **kwargs)
+
+    def warning(self, message: str, **kwargs: Any) -> None:
+        self.logger.warning(message, **kwargs)
+
+    def error(self, message: str, **kwargs: Any) -> None:
+        self.logger.error(message, **kwargs)
+
+    def exception(self, message: str, **kwargs: Any) -> None:
+        self.logger.exception(message, **kwargs)

corekit/observability/timing/constants.py

@@ -0,0 +1 @@
+DEFAULT_PRECISION = 4

corekit/observability/timing/split.py

@@ -0,0 +1,20 @@
+from pydantic import BaseModel
+
+
+class Split(BaseModel):
+    num: int
+    total: float
+    latest: float
+    name: str | None = None
+    split_name: str | None = None
+
+    def __str__(self) -> str:
+        identifier = ""
+        if self.name:
+            identifier += f" {self.name}"
+        if self.split_name:
+            identifier += f" {self.split_name}"
+        return f"{identifier} Split {self.num}: total={self.total}, latest_split={self.latest}".strip()
+
+    def __repr__(self) -> str:
+        return self.__str__()

corekit/observability/timing/timer.py

@@ -0,0 +1,30 @@
+import time
+
+from corekit.observability.timing.constants import DEFAULT_PRECISION
+from corekit.observability.timing.split import Split
+
+
+class Timer:
+    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__
+        self.precision = precision if precision > 0 else DEFAULT_PRECISION
+
+    def _round(self, value: float) -> float:
+        return round(value, self.precision)
+
+    def split(self, split_name: str | None = None) -> Split:
+        _time = time.time()
+        self.num += 1
+        split = Split(
+            num=self.num,
+            total=self._round(_time - self.start),
+            latest=self._round(_time - self.latest),
+            name=self.name,
+            split_name=split_name,
+        )
+        self.latest = _time
+        return split

corekit/registry/__init__.py

@@ -0,0 +1,12 @@
+"""
+Key-normalizing registry.
+
+``SmartRegistry`` folds case, trims whitespace and treats spaces and underscores
+as hyphens, so ``"AI Conversation Handler"``, ``"ai_conversation_handler"`` and
+``"ai-conversation-handler"`` all address the same entry. That forgiveness
+matters wherever a human -- or a language model -- supplies the key.
+"""
+
+from corekit.registry.registry import SmartRegistry
+
+__all__ = ["SmartRegistry"]

corekit/registry/registry.py

@@ -0,0 +1,134 @@
+import re
+from typing import Any, Iterator
+
+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])")
+
+
+class SmartRegistry:
+    """
+    A specialized registry object that handles key normalization and
+    provides a unified interface for discovery across different layers.
+    """
+
+    __slots__ = ("__registry__",)
+
+    def __init__(self) -> None:
+        """
+        Initialize an empty registry.
+        """
+        self.__registry__ = {}
+
+    def __len__(self) -> int:
+        """
+        Return the number of items in the registry.
+        """
+        return len(self.__registry__)
+
+    def __getitem__(self, key: str) -> Any:
+        """
+        Retrieve an item from the registry using a normalized key.
+        """
+        return self.__registry__[self.__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
+
+    def __delitem__(self, key: str) -> None:
+        """
+        Remove an item from the registry.
+        """
+        del self.__registry__[self.__normalize_key__(key)]
+
+    def __iter__(self) -> Iterator[str]:
+        """
+        Return an iterator over the normalized keys in the registry.
+        """
+        return iter(self.__registry__)
+
+    def items(self) -> Any:
+        """
+        Return the items in the registry as (key, value) pairs.
+        """
+        return self.__registry__.items()
+
+    def keys(self) -> Any:
+        """
+        Return the normalized keys in the registry.
+        """
+        return self.__registry__.keys()
+
+    def values(self) -> Any:
+        """
+        Return the values stored in the registry.
+        """
+        return self.__registry__.values()
+
+    def __contains__(self, key: str) -> bool:
+        """
+        Check if a normalized key exists in the registry.
+        """
+        return self.__normalize_key__(key) in self.__registry__
+
+    def __str__(self) -> str:
+        """
+        Return a string representation of the underlying registry.
+        """
+        return str(self.__registry__)
+
+    def __repr__(self) -> str:
+        """
+        Return a formal representation of the SmartRegistry.
+        """
+        return f"{self.__class__.__name__}({self.__registry__})"
+
+    def __eq__(self, other: Any) -> bool:
+        """
+        Compare this registry with another object for equality.
+        """
+        if not isinstance(other, SmartRegistry):
+            return False
+        return self.__registry__ == other.__registry__
+
+    def __ne__(self, other: Any) -> bool:
+        """
+        Compare this registry with another object for inequality.
+        """
+        return not self == other
+
+    def __getstate__(self) -> dict[str, Any]:
+        """
+        Return the internal state for serialization.
+        """
+        return self.__registry__
+
+    def __setstate__(self, state: dict[str, Any]) -> None:
+        """
+        Restore the internal state from a serialized dictionary.
+        """
+        self.__registry__ = state
+
+    @staticmethod
+    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)
+
+    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)

corekit/schemas/enum.py

@@ -0,0 +1,49 @@
+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)

corekit/schemas/models/arbitrary.py

@@ -0,0 +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

corekit/schemas/models/date_models.py

@@ -0,0 +1,18 @@
+from datetime import timedelta
+from typing import NamedTuple
+
+from corekit.schemas.types import ArbitraryDate
+
+
+class DateRange(NamedTuple):
+    start: ArbitraryDate
+    end: ArbitraryDate
+
+    def __str__(self) -> str:
+        return f"{self.start} to {self.end}"
+
+    def __repr__(self) -> str:
+        return self.__str__()
+
+    def delta(self) -> timedelta:
+        return self.end - self.start

corekit/schemas/pydantic/fields.py

@@ -0,0 +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)

corekit/schemas/types.py

@@ -0,0 +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

corekit/serialization/enum.py

@@ -0,0 +1,21 @@
+from corekit.schemas.enum import StringEnum
+
+
+class SerializerEngine(StringEnum):
+    DILL = "dill"
+    PICKLE = "pickle"
+    JSON = "json"
+
+    @classmethod
+    def get_default(cls) -> "SerializerEngine":
+        """
+        JSON, because it cannot execute code while loading.
+        """
+        return cls.JSON
+
+    @classmethod
+    def from_bytes(cls, name_in_bytes: bytes) -> "SerializerEngine":
+        return cls(name_in_bytes.decode("utf-8"))
+
+    def is_valid_for_class(self) -> bool:
+        return self in {SerializerEngine.DILL, SerializerEngine.PICKLE}

corekit/serialization/serializable.py

@@ -0,0 +1,42 @@
+"""
+Mixin for objects that can serialize themselves.
+"""
+
+from typing import Any
+
+from corekit.serialization.serializer import Serializer
+
+__all__ = ["Serializable"]
+
+
+class Serializable:
+    """
+    Gives a class ``serialize`` and ``from_serialized``.
+
+    Serializing an arbitrary object needs pickle or dill, both of which execute
+    code on load, so a key is required -- see ``Serializer``.
+    """
+
+    def __init__(self, **kwargs: Any) -> None:
+        self._serializer = Serializer(**kwargs)
+
+    @classmethod
+    def from_serialized(cls, serialized: bytes, **kwargs: Any) -> Any:
+        """
+        Rebuild an instance from bytes produced by ``serialize``.
+
+        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)
+
+    def serialize(self) -> bytes:
+        """
+        Encode this object.
+        """
+        if not self._serializer.is_valid_for_class():
+            raise TypeError(
+                f"{type(self).__name__} needs an engine that can encode arbitrary objects "
+                f"(pickle or dill), which requires a key."
+            )
+        return self._serializer.serialize(self)

corekit/serialization/serializer.py

@@ -0,0 +1,179 @@
+"""
+Serialization with authenticated payloads.
+
+``pickle`` and ``dill`` execute code while loading. Anything that reaches
+``loads`` can run arbitrary code, so a payload must be proven to come from a
+holder of the shared key **before** it is decoded, and the decoder must be
+chosen by the receiver rather than read out of the payload.
+
+    serializer = Serializer(SerializerEngine.JSON, key=b"shared-secret")
+    blob = serializer.serialize({"a": 1})
+    serializer.deserialize(blob)
+
+JSON is the default because it cannot execute code. Choosing ``pickle`` or
+``dill`` requires a key, and payloads carrying them are rejected unless their
+HMAC verifies.
+"""
+
+import hashlib
+import hmac
+import json
+import pickle
+from typing import Any
+
+import dill
+
+from corekit.config import get_settings
+from corekit.serialization.enum import SerializerEngine
+
+__all__ = ["Serializer", "SignatureError", "UnsafeEngineError"]
+
+DELIMITER = b":"
+DIGEST = hashlib.sha256
+
+# Engines that execute code while loading. A payload naming one of these is
+# only decoded after its signature verifies.
+EXECUTING_ENGINES = frozenset({SerializerEngine.PICKLE, SerializerEngine.DILL})
+
+_ENGINE_MODULES = {
+    SerializerEngine.JSON: json,
+    SerializerEngine.PICKLE: pickle,
+    SerializerEngine.DILL: dill,
+}
+
+
+class SignatureError(Exception):
+    """
+    Raised when a payload's signature is missing or does not verify.
+    """
+
+
+class UnsafeEngineError(Exception):
+    """
+    Raised when a code-executing engine is requested without a key.
+    """
+
+
+class Serializer:
+    """
+    Serializes to bytes, optionally authenticated with an HMAC.
+
+    Without a key only JSON is available. With one, every payload is signed on
+    the way out and verified on the way in.
+    """
+
+    def __init__(self, engine: SerializerEngine | None = None, key: bytes | str | None = None) -> None:
+        self._engine = engine or SerializerEngine.get_default()
+        self._key = self._resolve_key(key)
+
+        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."
+            )
+
+    @staticmethod
+    def _resolve_key(key: bytes | str | None) -> bytes | None:
+        """
+        Take the supplied key, else the configured one, else none.
+        """
+        if key is None:
+            key = get_settings().serialization.key
+        if key is None:
+            return None
+        return key.encode("utf-8") if isinstance(key, str) else key
+
+    @property
+    def encoding(self) -> str:
+        return "utf-8"
+
+    @property
+    def engine(self) -> Any:
+        """
+        The module implementing the selected engine.
+        """
+        return _ENGINE_MODULES[self._engine]
+
+    @property
+    def is_signed(self) -> bool:
+        """
+        Whether this serializer authenticates its payloads.
+        """
+        return self._key is not None
+
+    def is_valid_for_class(self) -> bool:
+        """
+        Whether the engine can serialize an arbitrary object graph.
+        """
+        return self._engine.is_valid_for_class()
+
+    def _dumps(self, value: Any) -> bytes:
+        """
+        Encode a value, normalizing JSON's str output to bytes.
+        """
+        encoded = self.engine.dumps(value)
+        return encoded.encode(self.encoding) if isinstance(encoded, str) else encoded
+
+    def _compute_mac(self, engine_bytes: bytes, payload: bytes) -> bytes:
+        """
+        Authenticate the engine name together with the payload.
+
+        Covering the engine name prevents an attacker from taking a valid JSON
+        payload and re-labelling it as pickle.
+        """
+        assert self._key is not None
+        return hmac.new(self._key, engine_bytes + DELIMITER + payload, DIGEST).hexdigest().encode("ascii")
+
+    def serialize(self, value: Any) -> bytes:
+        """
+        Encode a value, signing it when a key is configured.
+
+        Produces ``engine:payload``, or ``engine:mac:payload`` when signed.
+        """
+        engine_bytes = self._engine.value.encode(self.encoding)
+        payload = self._dumps(value)
+
+        if self._key is None:
+            return engine_bytes + DELIMITER + payload
+
+        mac = self._compute_mac(engine_bytes, payload)
+        return engine_bytes + DELIMITER + mac + DELIMITER + payload
+
+    def deserialize(self, value: bytes) -> Any:
+        """
+        Decode a payload produced by ``serialize``.
+
+        The engine named in the payload must match this serializer's, so the
+        receiver decides how bytes are decoded. A signed serializer verifies the
+        HMAC before decoding anything.
+        """
+        engine_bytes, _, remainder = value.partition(DELIMITER)
+        if not remainder:
+            raise ValueError("Malformed payload: expected engine:payload")
+
+        try:
+            engine = SerializerEngine.from_bytes(engine_bytes)
+        except ValueError as exc:
+            raise ValueError(f"Unknown serializer engine {engine_bytes!r}") from exc
+
+        # The receiver's configuration decides the decoder. Honouring the
+        # payload's choice would let a caller select pickle and execute code.
+        if engine is not self._engine:
+            raise SignatureError(
+                f"Payload was serialized with {engine.value}, but this serializer uses {self._engine.value}. "
+                f"Construct a Serializer for that engine explicitly if the source is trusted."
+            )
+
+        if self._key is None:
+            if engine in EXECUTING_ENGINES:
+                raise UnsafeEngineError(f"Refusing to load an unsigned {engine.value} payload.")
+            return self.engine.loads(remainder)
+
+        mac, _, payload = remainder.partition(DELIMITER)
+        if not payload:
+            raise SignatureError("Payload is unsigned, but this serializer requires a signature.")
+
+        if not hmac.compare_digest(mac, self._compute_mac(engine_bytes, payload)):
+            raise SignatureError("Payload signature does not verify; refusing to deserialize.")
+
+        return self.engine.loads(payload)

corekit/utils/__init__.py

@@ -0,0 +1,5 @@
+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

corekit/utils/ids.py

@@ -0,0 +1,5 @@
+import uuid
+
+
+def generate_uuid() -> str:
+    return str(uuid.uuid4())