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

corekit/jobs/runner.py

@@ -0,0 +1,69 @@
+"""
+The worker entrypoint.
+
+``run_task`` is what a queue calls. It takes a name and a JSON payload, builds
+the task from the worker's own registry and runs it -- so a queue entry selects
+among the tasks this worker already has, and cannot introduce code.
+
+Point the queue at this function rather than at a bound method::
+
+    queue.enqueue(run_task, "NightlyBackup", task.payload("db"))
+
+Enqueueing a bound method makes the queue serialize the instance, which is the
+thing worth avoiding.
+"""
+
+import logging
+from typing import Any
+
+from corekit.jobs.registry import task_registry
+from corekit.utils.payload import decode_payload
+
+__all__ = ["run_task"]
+
+logger = logging.getLogger(__name__)
+
+
+def run_task(task_name: str, payload: str | bytes | None = None) -> Any:
+    """
+    Build the named task and run it.
+
+    ``success`` runs after ``task_function`` returns; ``failure`` runs if it
+    raises, and the original exception is re-raised so the queue records the
+    job as failed. A hook that raises does not mask the original error.
+
+    Args:
+        task_name: The registered name of the task to run.
+        payload: JSON arguments from ``Task.payload``. Empty means no arguments.
+
+    Returns:
+        Whatever ``task_function`` returns.
+
+    Raises:
+        TaskNotRegisteredError: If no task is registered under that name.
+        ValueError: If the payload is not the expected JSON object.
+    """
+    args, kwargs = decode_payload(payload)
+    task = task_registry.build(task_name)
+
+    try:
+        result = task.task_function(*args, **kwargs)
+    except Exception:
+        _run_hook(task, "failure", args, kwargs)
+        raise
+
+    _run_hook(task, "success", args, kwargs)
+    return result
+
+
+def _run_hook(task: Any, hook_name: str, args: list[Any], kwargs: dict[str, Any]) -> None:
+    """
+    Run a success or failure hook without letting it replace the real outcome.
+
+    A raising ``failure`` hook would otherwise mask the exception that caused
+    it, leaving the job recorded under the wrong error.
+    """
+    try:
+        getattr(task, hook_name)(*args, **kwargs)
+    except Exception:
+        logger.exception(f"Task {task.name} '{hook_name}' hook raised; the task's own outcome stands")

corekit/jobs/task.py

@@ -0,0 +1,152 @@
+"""
+Background tasks, independent of any queue.
+
+``Task`` describes work and how to name it; nothing here imports a queue
+library, so the same task runs under RQ, Celery, a cron entry or a test with no
+queue at all. An adapter binds it to whichever backend an application uses --
+see ``corekit.jobs.runner``.
+
+A task is identified by name and constructed by the worker from its own code::
+
+    class NightlyBackup(ScheduledTask):
+        interval = 86400
+
+        def task_function(self, target: str) -> None:
+            ...
+
+The queue carries ``("NightlyBackup", '{"args": ["db"], "kwargs": {}}')`` and
+never a serialized object, so writing to the queue cannot run arbitrary code in
+a worker.
+"""
+
+import abc
+import logging
+from datetime import datetime, timedelta
+from typing import Any
+
+from corekit.jobs.registry import task_registry
+from corekit.utils.payload import encode_payload
+
+__all__ = ["ScheduledTask", "Task"]
+
+DEFAULT_TASK_TIMEOUT = 180
+
+
+def _declared_abstract_methods(cls: type) -> tuple[str, ...]:
+    """
+    Names marked abstract anywhere in the class's ancestry.
+
+    Needed because ABCMeta has not yet populated ``__abstractmethods__`` when
+    ``__init_subclass__`` runs on the class being defined.
+    """
+    names = set()
+    for klass in cls.__mro__:
+        for name, value in vars(klass).items():
+            if getattr(value, "__isabstractmethod__", False):
+                names.add(name)
+    return tuple(names)
+
+
+class Task(abc.ABC):
+    """
+    A unit of background work.
+
+    Subclasses implement ``task_function`` and are registered by class name when
+    the class is defined, so a worker can rebuild one from a queued name.
+    """
+
+    #: Overrides the class name as the registered identity.
+    task_name: str | None = None
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        """
+        Register every concrete subclass under its name.
+
+        Abstract subclasses are skipped -- an intermediate base with methods
+        still unimplemented is a shared parent, not a task a worker can run.
+        ``__abstractmethods__`` is set by ABCMeta *after* this hook runs, so the
+        class's own namespace is inspected instead.
+        """
+        super().__init_subclass__(**kwargs)
+        if not cls._is_abstract():
+            task_registry.register(cls)
+
+    @classmethod
+    def _is_abstract(cls) -> bool:
+        """
+        Whether this class still leaves an abstract method unimplemented.
+        """
+        for name in getattr(cls, "__abstractmethods__", ()) or _declared_abstract_methods(cls):
+            attribute = getattr(cls, name, None)
+            if getattr(attribute, "__isabstractmethod__", False):
+                return True
+        return False
+
+    def __init__(self, name: str | None = None) -> None:
+        """
+        Build the task. ``name`` overrides the registered identity for logging.
+        """
+        self.name = name or self.task_name or type(self).__name__
+        self.logger = logging.getLogger(type(self).__module__)
+
+    @abc.abstractmethod
+    def task_function(self, *args: Any, **kwargs: Any) -> None:
+        """
+        The work to perform. Arguments arrive as JSON-decoded data.
+        """
+        raise NotImplementedError
+
+    def success(self, *args: Any, **kwargs: Any) -> None:
+        """
+        Called after ``task_function`` returns. Override to add behaviour.
+        """
+        self.logger.info(f"Task {self.name} completed successfully")
+
+    def failure(self, *args: Any, **kwargs: Any) -> None:
+        """
+        Called when ``task_function`` raises. Override to add behaviour.
+        """
+        self.logger.error(f"Task {self.name} failed")
+
+    def payload(self, *args: Any, **kwargs: Any) -> str:
+        """
+        Encode arguments for the queue, raising now if they cannot cross it.
+        """
+        return encode_payload(args, kwargs)
+
+
+class ScheduledTask(Task):
+    """
+    A task that runs on a schedule.
+
+    The timing attributes are read by whichever adapter schedules the task;
+    nothing here talks to a scheduler itself.
+    """
+
+    interval: int | None = None
+    repeat: int | None = None
+    timeout: int = DEFAULT_TASK_TIMEOUT
+    schedule_delay: dict[str, int] = {"hours": 1}
+    start_time: datetime | None = None
+
+    #: Default arguments, encoded into the payload when the task is scheduled.
+    args: list[Any] | None = None
+    kwargs: dict[str, Any] | None = None
+
+    def get_start_time(self) -> datetime:
+        """
+        When the first run should happen.
+
+        ``start_time`` if set, otherwise ``schedule_delay`` from now. Timezone
+        handling is the scheduler's business, so this returns local time to
+        match what schedulers expect.
+        """
+        if self.start_time is not None:
+            return self.start_time
+        return datetime.now() + timedelta(**self.schedule_delay)
+
+    def scheduled_payload(self) -> str:
+        """
+        The encoded arguments this task is scheduled with.
+        """
+        return encode_payload(self.args or [], self.kwargs or {})

corekit/observability/__init__.py

@@ -2,8 +2,9 @@
 Logging and performance measurement.
 
 ``Loggable`` gives a class a logger named after itself; ``Benchmarkable`` adds
-split timing on top. They live together because they are the same concern --
-knowing what a running system is doing.
+split timing on top. ``BaseRequestContext`` carries per-request metadata so a
+log line can say which request it belongs to. They live together because they
+are the same concern -- knowing what a running system is doing.
 
     class Importer(Benchmarkable):
         def run(self) -> None:
@@ -15,7 +16,8 @@ knowing what a running system is doing.
 
 from corekit.observability.benchmarkable import Benchmarkable
 from corekit.observability.loggable import Loggable
+from corekit.observability.request_context import BaseRequestContext
 from corekit.observability.timing.split import Split
 from corekit.observability.timing.timer import Timer
 
-__all__ = ["Benchmarkable", "Loggable", "Split", "Timer"]
+__all__ = ["BaseRequestContext", "Benchmarkable", "Loggable", "Split", "Timer"]

corekit/observability/request_context.py

@@ -0,0 +1,135 @@
+"""
+Request-scoped metadata.
+
+Small values that belong to one request -- which surface initiated it, a request
+id, a correlation id -- carried in a ``ContextVar`` so they follow the work
+rather than being threaded through every call signature.
+
+A ``ContextVar`` rather than ``threading.local``: coroutines that ``await``
+may resume on a different thread, and several tasks may share one, so
+thread-local state either leaks between requests or vanishes mid-request.
+Context variables follow the logical task instead.
+
+This is not for connections or anything that must be closed. It holds
+immutable-per-request facts; see ``ThreadLocalRegistry`` for resources with a
+lifecycle.
+
+Subclass it with the fields an application actually wants::
+
+    class RequestContext(BaseRequestContext):
+        surface: Surface
+        request_id: str | None = None
+
+    with RequestContext(surface=Surface.API).active():
+        ...                                  # RequestContext.current() sees it
+
+Each subclass gets its own storage, so one application's context cannot be read
+through another's class.
+"""
+
+from contextlib import contextmanager
+from contextvars import ContextVar, Token
+from typing import Any, Iterator, Self
+
+from pydantic import BaseModel
+
+__all__ = ["BaseRequestContext"]
+
+
+class BaseRequestContext(BaseModel):
+    """
+    Base for request-scoped metadata carried in a ``ContextVar``.
+
+    Prefer ``active()`` or ``active_if_absent()`` over the manual
+    ``activate``/``deactivate`` pair: an early return or a raised exception
+    between them leaks the context into whatever runs next on that task.
+    """
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        """
+        Give every subclass its own ContextVar.
+        """
+        super().__init_subclass__(**kwargs)
+        cls._context_var = ContextVar(f"{cls.__module__}.{cls.__name__}", default=None)
+
+    @classmethod
+    def _var(cls) -> ContextVar[Any]:
+        """
+        This class's context variable.
+
+        Raises:
+            TypeError: If called on ``BaseRequestContext`` itself, which holds
+                no storage -- subclass it with the fields you need.
+        """
+        # Set by __init_subclass__, so each subclass reads and writes its own
+        # variable rather than sharing one with its siblings.
+        var = cls.__dict__.get("_context_var") or getattr(cls, "_context_var", None)
+        if not isinstance(var, ContextVar):
+            raise TypeError(
+                f"{cls.__name__} has no context storage. Subclass BaseRequestContext "
+                f"with the fields your application needs rather than using it directly."
+            )
+        return var
+
+    @classmethod
+    def current(cls) -> Self | None:
+        """
+        The active context, or ``None`` if nothing is active.
+        """
+        return cls._var().get()
+
+    def activate(self) -> Token:
+        """
+        Make this the active context, returning a token for ``deactivate``.
+
+        Prefer ``active()``, which cannot leak.
+        """
+        return self._var().set(self)
+
+    def activate_if_absent(self) -> Token | None:
+        """
+        Activate only if nothing is active yet, else return ``None``.
+
+        Lets an inner call establish a default without overriding the surface an
+        outer caller already set. The result, ``None`` included, goes to
+        ``deactivate``.
+        """
+        if self._var().get() is not None:
+            return None
+        return self._var().set(self)
+
+    @classmethod
+    def deactivate(cls, token: Token | None) -> None:
+        """
+        Restore whatever was active before. ``None`` is a no-op.
+        """
+        if token is not None:
+            cls._var().reset(token)
+
+    @contextmanager
+    def active(self) -> Iterator[Self]:
+        """
+        Activate for the duration of the block, restoring on the way out.
+
+        Restores even when the block raises, which the manual pair does not do
+        unless every caller remembers the ``finally``.
+        """
+        token = self.activate()
+        try:
+            yield self
+        finally:
+            type(self).deactivate(token)
+
+    @contextmanager
+    def active_if_absent(self) -> Iterator[Self | None]:
+        """
+        Activate for the block only if nothing is active yet.
+
+        Yields the context that ends up active -- this one, or the one that was
+        already there -- so a caller can read it either way.
+        """
+        token = self.activate_if_absent()
+        try:
+            yield type(self).current()
+        finally:
+            type(self).deactivate(token)

corekit/registry/__init__.py

@@ -1,12 +1,17 @@
 """
-Key-normalizing registry.
+Registries.
 
-``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.
+``SmartRegistry`` is keyed and forgiving: it 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 matters wherever a human -- or a language model -- supplies
+the key.
+
+``OrderedRegistry`` is unkeyed: it preserves registration order and allows
+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
 
-__all__ = ["SmartRegistry"]
+__all__ = ["OrderedRegistry", "SmartRegistry"]

corekit/registry/ordered.py

@@ -0,0 +1,86 @@
+"""
+Insertion-ordered registry.
+
+Where ``SmartRegistry`` is a dict keyed by a forgiving name, ``OrderedRegistry``
+is a list: it keeps what was registered, in the order it was registered, and
+lets callers filter it. Use it when order is the point and names are not --
+mount order, execution order, pipeline stages -- and when two entries may
+legitimately share a name.
+"""
+
+from typing import Callable, Generic, Iterator, TypeVar
+
+__all__ = ["OrderedRegistry"]
+
+T = TypeVar("T")
+
+
+class OrderedRegistry(Generic[T]):
+    """
+    Everything registered in this process, in construction order.
+
+    Deliberately not keyed. A keyed registry silently evicts a collision, which
+    for order-sensitive collections means an entry vanishing with no error --
+    so duplicates are kept, and callers select with ``where`` instead.
+    """
+
+    __slots__ = ("_entries",)
+
+    def __init__(self) -> None:
+        """
+        Initialize an empty registry.
+        """
+        self._entries: list[T] = []
+
+    def register(self, entry: T) -> T:
+        """
+        Append an entry, returning it so this can be used inline.
+        """
+        self._entries.append(entry)
+        return entry
+
+    def where(self, predicate: Callable[[T], bool]) -> list[T]:
+        """
+        Return the entries matching ``predicate``, in registration order.
+        """
+        return [entry for entry in self._entries if predicate(entry)]
+
+    def clear(self) -> None:
+        """
+        Forget every entry. For tests that build more than one of whatever this holds.
+        """
+        self._entries.clear()
+
+    @property
+    def entries(self) -> list[T]:
+        """
+        A copy of the entries, in registration order.
+
+        A copy, so a caller iterating the result cannot be tripped up by
+        something registering mid-loop.
+        """
+        return list(self._entries)
+
+    def __len__(self) -> int:
+        """
+        Return the number of registered entries.
+        """
+        return len(self._entries)
+
+    def __iter__(self) -> Iterator[T]:
+        """
+        Iterate the entries in registration order.
+        """
+        return iter(self._entries)
+
+    def __contains__(self, entry: object) -> bool:
+        """
+        Check whether an entry has been registered, by identity or equality.
+        """
+        return entry in self._entries
+
+    def __repr__(self) -> str:
+        """
+        Return a formal representation of the registry.
+        """
+        return f"{type(self).__name__}({self._entries!r})"

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

@@ -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