python-corekit 0.1.0__py3-none-any.whl

corekit/api/__init__.py

@@ -0,0 +1,9 @@
+"""
+FastAPI building blocks: handlers, routers and responses.
+"""
+
+from corekit.api.handler import BaseHandler
+from corekit.api.responses import SSEResponse
+from corekit.api.routers import SimpleRouter, SmartRouter
+
+__all__ = ["BaseHandler", "SSEResponse", "SimpleRouter", "SmartRouter"]

corekit/api/handler.py

@@ -0,0 +1,76 @@
+"""
+Base class for business-logic handlers.
+"""
+
+from typing import Any
+
+from corekit.config import get_settings
+from corekit.observability.benchmarkable import Benchmarkable
+from corekit.registry import SmartRegistry
+
+__all__ = ["BaseHandler"]
+
+
+def _has_multiline_docstring(cls: type) -> bool:
+    """
+    Report whether a class carries a docstring spanning more than one line.
+    """
+    doc = cls.__doc__
+    return bool(doc) and "\n" in doc.strip()
+
+
+class BaseHandler(Benchmarkable):
+    """
+    Base class for all business logic handlers.
+
+    Every subclass registers itself into a shared registry, so handlers can be
+    discovered by name at runtime. Inherits logging from Loggable and split
+    timing from Benchmarkable.
+
+    Docstring enforcement is opt-in. Set ``require_handler_docstrings`` in your
+    corekit config (or ``COREKIT_REQUIRE_HANDLER_DOCSTRINGS=true``) to require a
+    multiline docstring on every handler; set ``__require_doc__`` on a subclass
+    to override the configured value for that branch of the hierarchy.
+    """
+
+    __registry__: SmartRegistry = SmartRegistry()
+
+    # None means "defer to configuration". A subclass may set True or False to
+    # opt in or out regardless of what the configuration says.
+    __require_doc__: bool | None = None
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        """
+        Validate and register every subclass at class-definition time.
+        """
+        super().__init_subclass__(**kwargs)
+
+        # Read from cls, not from BaseHandler, so subclasses can genuinely
+        # override this. Reading the base class attribute silently ignored
+        # every per-subclass opt-out.
+        require_doc = cls.__require_doc__
+        if require_doc is None:
+            require_doc = get_settings().standards.require_handler_docstrings
+
+        if require_doc and not _has_multiline_docstring(cls):
+            raise TypeError(
+                f"Handler '{cls.__name__}' must have a descriptive multiline docstring. "
+                f"Set __require_doc__ = False on the class, or disable "
+                f"require_handler_docstrings in your corekit config, to opt out."
+            )
+
+        BaseHandler.__registry__[cls.__name__] = cls
+
+    @classmethod
+    def get_handler_types(cls) -> SmartRegistry:
+        """
+        Return the registry of all known BaseHandler subclasses.
+        """
+        return cls.__registry__
+
+    @classmethod
+    def get_handler_by_name(cls, name: str) -> type["BaseHandler"] | None:
+        """
+        Retrieve a handler class by name, using the registry's key normalization.
+        """
+        return cls.__registry__.get(name)

corekit/api/responses.py

@@ -0,0 +1,40 @@
+"""
+Response types.
+"""
+
+from types import MappingProxyType
+from typing import Any, AsyncGenerator
+
+from fastapi.responses import StreamingResponse
+
+__all__ = ["SSEResponse"]
+
+# no-cache stops the browser reusing a stream; X-Accel-Buffering stops nginx
+# holding frames back until its buffer fills, which makes a live stream arrive
+# in batches or not at all.
+DEFAULT_HEADERS = MappingProxyType({"Cache-Control": "no-cache", "X-Accel-Buffering": "no"})
+
+
+class SSEResponse(StreamingResponse):
+    """
+    A StreamingResponse configured for Server-Sent Events.
+
+        @router.get("/events")
+        async def events(channel: str) -> SSEResponse:
+            return SSEResponse(event_stream(channel))
+
+    Pass ``keep_alive=True`` for long-lived streams behind a proxy that closes
+    idle connections.
+    """
+
+    def __init__(
+        self,
+        content: AsyncGenerator[str, None],
+        headers: dict[str, str] | None = None,
+        keep_alive: bool = False,
+        **kwargs: Any,
+    ) -> None:
+        headers = dict(DEFAULT_HEADERS) if headers is None else dict(headers)
+        if keep_alive:
+            headers["Connection"] = "keep-alive"
+        super().__init__(content=content, media_type="text/event-stream", headers=headers, **kwargs)

corekit/api/routers.py

@@ -0,0 +1,115 @@
+"""
+Routers that carry their own handler.
+
+``SimpleRouter`` is a FastAPI ``APIRouter`` that can log, time itself and add
+itself to a parent. ``SmartRouter`` additionally binds a handler class through
+the subscript syntax::
+
+    router = SmartRouter[AdminHandler](route_prefix="/admin", tags=["Admin"])
+
+    @router.get("/users")
+    async def list_users() -> UserResponse:
+        return await router.handler.list_users()
+"""
+
+from typing import Any, Generic, Type, TypeVar, cast
+
+from fastapi import APIRouter, FastAPI
+
+from corekit.api.handler import BaseHandler
+from corekit.observability.benchmarkable import Benchmarkable
+
+__all__ = ["SimpleRouter", "SmartRouter"]
+
+H = TypeVar("H", bound=BaseHandler)
+
+
+class SimpleRouter(APIRouter, Benchmarkable):
+    """
+    An APIRouter that can log, time itself, and mount itself onto a parent.
+    """
+
+    def __init__(self, route_prefix: str | None = None, **kwargs: Any) -> None:
+        """
+        Accepts every APIRouter keyword, plus ``route_prefix`` as an alias for ``prefix``.
+        """
+        if route_prefix and "prefix" not in kwargs:
+            kwargs["prefix"] = route_prefix
+
+        APIRouter.__init__(self, **kwargs)
+        Benchmarkable.__init__(self)
+
+    def include(self, parent: APIRouter | FastAPI, *args: Any, **kwargs: Any) -> None:
+        """
+        Add this router to a parent router or application.
+
+        The inverse of ``parent.include_router(self)``, so a module can hand
+        itself over: ``admin_router.include(app)``.
+        """
+        parent.include_router(self, *args, **kwargs)
+
+
+class SmartRouter(SimpleRouter, Generic[H]):
+    """
+    A router bound to a handler class.
+
+    ``SmartRouter[MyHandler]`` mints a subclass carrying ``MyHandler``. The
+    handler is constructed on first access rather than at import time, so tests
+    can substitute one by assigning to ``router.handler`` without the real
+    handler ever being built.
+    """
+
+    _handler_class: Type[H] | None = None
+
+    # Subscripting the same handler twice returns the same class, so
+    # SmartRouter[X] is SmartRouter[X] holds and repeated subscripts do not
+    # mint throwaway types.
+    __bound_cache__: dict[Any, type] = {}
+
+    def __class_getitem__(cls, item: Type[H]) -> Any:
+        """
+        Bind a handler class, returning a cached dynamic subclass.
+        """
+        cache_key = (cls, item)
+        cached = SmartRouter.__bound_cache__.get(cache_key)
+        if cached is not None:
+            return cached
+
+        new_cls = type(f"{cls.__name__}_{item.__name__}", (cls,), {"_handler_class": item})
+        SmartRouter.__bound_cache__[cache_key] = new_cls
+        return new_cls
+
+    def __init__(self, handler: H | None = None, **kwargs: Any) -> None:
+        """
+        Build the router, optionally with an explicit handler instance.
+
+        Without one, the class bound via ``SmartRouter[MyHandler]`` is
+        instantiated lazily on first use of ``handler``.
+        """
+        SimpleRouter.__init__(self, **kwargs)
+
+        if handler is None and self._handler_class is None:
+            raise ValueError(
+                f"{type(self).__name__} has no handler. Use a concrete type -- "
+                f"SmartRouter[MyHandler](...) -- or pass handler=..."
+            )
+
+        self._handler: H | None = handler
+
+    @property
+    def handler(self) -> H:
+        """
+        Return the handler, constructing it on first access.
+        """
+        if self._handler is None:
+            handler_class = cast(Type[H], self._handler_class)
+            self.info(f"Assembling {handler_class.__name__} for {type(self).__name__}")
+            self._handler = handler_class()
+        return self._handler
+
+    @handler.setter
+    def handler(self, handler: H) -> None:
+        """
+        Replace the handler. Assigning a double is the supported way to test a router.
+        """
+        self._handler = handler

corekit/concurrency/__init__.py

@@ -0,0 +1,9 @@
+"""
+Concurrency primitives: per-thread storage, workers, and parallel mapping.
+"""
+
+from corekit.concurrency.decorators import parallelize
+from corekit.concurrency.thread_local import ThreadLocalRegistry
+from corekit.concurrency.worker import ThreadWorker
+
+__all__ = ["ThreadLocalRegistry", "ThreadWorker", "parallelize"]

corekit/concurrency/decorators.py

@@ -0,0 +1,72 @@
+"""
+Running a function over many inputs at once.
+
+``@parallelize`` turns a single-item function into one that takes an iterable
+and yields results as they finish::
+
+    @parallelize()
+    def fetch(url: str) -> Response:
+        return client.get(url)
+
+    for response in fetch(urls):
+        ...
+
+The thread count comes from configuration unless the caller names one, and is
+capped either way -- see ``ConcurrencySettings``. A pool is cheap to ask for and
+expensive to get wrong, and the failure mode of getting it wrong is a hung
+machine rather than an error message.
+
+Results arrive out of order, because they arrive as they complete. Pass
+``ordered=True`` to get them in the order the inputs were given.
+"""
+
+import functools
+from concurrent.futures import Future, ThreadPoolExecutor, as_completed
+from typing import Any, Callable, Iterable, Iterator
+
+from corekit.config import get_settings
+from corekit.observability import Loggable
+
+__all__ = ["parallelize"]
+
+_logger = Loggable()
+_logger.logger = _logger.logger.getChild("parallelize")
+
+
+def parallelize(
+    num_threads: int | None = None,
+    ordered: bool = False,
+    raise_on_error: bool = True,
+) -> Callable[[Callable[..., Any]], Callable[..., Iterator[Any]]]:
+    """
+    Run a function over an iterable of inputs across a thread pool.
+
+    :param num_threads: workers to use. Defaults to the configured
+        ``concurrency.default_threads``, and is clamped to ``max_threads``.
+    :param ordered: yield results in input order rather than completion order.
+    :param raise_on_error: propagate the first failure. When False, failures are
+        logged and skipped -- which loses results silently, so it is opt-in.
+    """
+
+    def decorator(func: Callable[..., Any]) -> Callable[..., Iterator[Any]]:
+        @functools.wraps(func)
+        def wrapper(items: Iterable[Any], *args: Any, **kwargs: Any) -> Iterator[Any]:
+            """
+            Submit every item and yield the results.
+            """
+            workers = get_settings().concurrency.resolve(num_threads)
+            with ThreadPoolExecutor(max_workers=workers) as executor:
+                futures: list[Future] = [executor.submit(func, item, *args, **kwargs) for item in items]
+
+                pending = futures if ordered else as_completed(futures)
+                for future in pending:
+                    try:
+                        yield future.result()
+                    except Exception as exc:
+                        if raise_on_error:
+                            raise
+                        _logger.warning(f"{func.__name__} failed for one item: {exc}")
+
+        return wrapper
+
+    return decorator

corekit/concurrency/thread_local.py

@@ -0,0 +1,99 @@
+"""
+Per-thread storage.
+
+``ThreadLocalRegistry`` is a key/value store whose contents are private to the
+thread that wrote them::
+
+    store = ThreadLocalRegistry()
+    store.set("request_id", "abc-123")
+    store.get("request_id")             # "abc-123" on this thread, None on any other
+
+Keys may be strings or classes; a class is reduced to a readable attribute name,
+so a store can be addressed by type without the caller inventing a name for it.
+
+Subclass it to manage what it holds -- see ``ConnectionRegistry``, which opens
+and closes the connections it stores.
+"""
+
+import threading
+from typing import Any
+
+from corekit.observability.loggable import Loggable
+from corekit.registry import SmartRegistry
+
+__all__ = ["ThreadLocalRegistry"]
+
+
+class ThreadLocalRegistry(threading.local, Loggable):
+    """
+    A key/value store with per-thread contents.
+
+    Subclassing ``threading.local`` means one shared object serves every thread
+    with its own values, so what one thread stores is never visible to another.
+    ``__init__`` therefore runs once per thread, which gives each its own logger.
+    """
+
+    # Attributes belonging to the object rather than to what it stores. They
+    # share __dict__ with stored values, so they are excluded from anything
+    # that reports on contents.
+    _RESERVED = frozenset({"logger"})
+
+    def __init__(self) -> None:
+        super().__init__()
+
+    @property
+    def _stored(self) -> dict[str, Any]:
+        """
+        This thread's stored values, without the object's own attributes.
+        """
+        return {key: value for key, value in self.__dict__.items() if key not in self._RESERVED}
+
+    @staticmethod
+    def _key(key: Any) -> str:
+        """
+        Normalize a key to an attribute name.
+
+        A class is keyed by its name, so callers can address a slot by type.
+        Normalization goes through SmartRegistry so word boundaries are found
+        the same way everywhere, including inside acronyms: a naive rule would
+        turn SQLConnection into "sqlconnection" rather than "sql_connection".
+        """
+        name = key.__name__ if isinstance(key, type) else str(key)
+        return SmartRegistry.__normalize_key__(name).replace("-", "_")
+
+    def get(self, key: Any, fallback: Any = None) -> Any:
+        """
+        This thread's value for ``key``, or ``fallback``.
+        """
+        return self.__dict__.get(self._key(key), fallback)
+
+    def set(self, key: Any, value: Any) -> None:
+        """
+        Store a value for this thread.
+        """
+        self.__dict__[self._key(key)] = value
+
+    def clear(self, key: Any) -> None:
+        """
+        Forget this thread's value for ``key``.
+        """
+        self.__dict__.pop(self._key(key), None)
+
+    def clear_all(self) -> None:
+        """
+        Forget everything this thread has stored.
+        """
+        for key in self._stored:
+            del self.__dict__[key]
+
+    def keys(self) -> tuple[str, ...]:
+        """
+        The keys this thread has stored.
+        """
+        return tuple(self._stored)
+
+    def __contains__(self, key: Any) -> bool:
+        return self._key(key) in self._stored
+
+    def __len__(self) -> int:
+        return len(self._stored)

corekit/concurrency/worker.py

@@ -0,0 +1,65 @@
+import asyncio
+import logging
+import threading
+import time
+
+
+class ThreadWorker(threading.Thread):
+    def __init__(
+        self,
+        can_start: threading.Event,
+        loop: asyncio.AbstractEventLoop | None = None,
+        timeout: int = 3,
+        delay: float = 1.0,
+    ) -> None:
+        super().__init__(daemon=True)
+        self.loop = loop
+        self.timeout = timeout
+        self.delay = delay
+        self.running = True  # Control flag for stopping the thread
+        self.can_start: threading.Event = can_start
+        self.logger = logging.getLogger(self.__class__.__name__)
+        self._logging_prefix = f"[{self.__class__.__name__}]"
+
+    @property
+    def logging_prefix(self) -> str:
+        return self._logging_prefix
+
+    def info(self, message: str) -> None:
+        self.logger.info(f"{self.logging_prefix}: {message}")
+
+    def warning(self, message: str) -> None:
+        self.logger.warning(f"{self.logging_prefix}: {message}")
+
+    def error(self, message: str) -> None:
+        self.logger.error(f"{self.logging_prefix}: {message}")
+
+    def set_loop(self, loop: asyncio.AbstractEventLoop) -> None:
+        self.logger.info("Updating event loop")
+        self.loop = loop
+
+    def stop(self) -> None:
+        """
+        Stops the worker gracefully
+        """
+        self.running = False
+        self.info("Stopping ThreadWorker")
+
+    def run(self) -> None:
+        self.info("ThreadWorker started")
+        try:
+            self.info("ThreadWorker waiting until able to start")
+            self.can_start.wait()
+
+            self.info("can_start flag set. Starting ThreadWorker")
+            self.process()
+
+        except Exception as exc:
+            self.error(f"Error in ThreadWorker: {exc}")
+            time.sleep(self.delay)
+
+        finally:
+            self.info("ThreadWorker ending")
+
+    def process(self) -> None:
+        raise NotImplementedError()

corekit/config/__init__.py

@@ -0,0 +1,47 @@
+"""
+Layered configuration for corekit.
+
+Configuration is optional: corekit always looks for it, and never requires it.
+
+    from corekit.config import get_settings
+
+    get_settings().concurrency.max_threads
+
+Precedence, highest first: an explicit argument, then ``COREKIT_``-prefixed
+environment variables, then a config file, then the defaults.
+
+Config files, first hit wins::
+
+    ./corekit.toml
+    ./pyproject.toml            ([tool.corekit] table)
+    ~/.config/corekit/config.toml
+
+Nothing is read at import time. Settings resolve on first use, so importing
+corekit can never fail because a variable is missing or a file has a typo.
+"""
+
+from corekit.config.loader import SettingsLoader, get_settings, loader, reset_settings, set_settings
+from corekit.config.settings import (
+    ConcurrencySettings,
+    CorekitSettings,
+    CryptoSettings,
+    DatabaseSettings,
+    RedisSettings,
+    SerializationSettings,
+    StandardsSettings,
+)
+
+__all__ = [
+    "ConcurrencySettings",
+    "CryptoSettings",
+    "DatabaseSettings",
+    "CorekitSettings",
+    "RedisSettings",
+    "SerializationSettings",
+    "SettingsLoader",
+    "StandardsSettings",
+    "get_settings",
+    "loader",
+    "reset_settings",
+    "set_settings",
+]

corekit/config/loader.py

@@ -0,0 +1,153 @@
+"""
+Assembling settings from their sources.
+
+The layering -- explicit argument, then environment, then config file, then
+defaults -- lives here, so a source knows only how to produce values and the
+settings know only their own shape.
+"""
+
+from pathlib import Path
+from typing import Any
+
+from corekit.config.settings import ENV_PREFIX, CorekitSettings
+from corekit.config.sources import ConfigFileSource, ConfigSource, EnvironmentSource, PyprojectSource
+from corekit.observability import Loggable
+
+__all__ = ["SettingsLoader", "get_settings", "reset_settings", "set_settings"]
+
+CONFIG_FILENAME = "corekit.toml"
+USER_CONFIG_PATH = Path.home() / ".config" / "corekit" / "config.toml"
+
+
+class SettingsLoader(Loggable):
+    """
+    Builds a ``CorekitSettings`` from the available sources.
+
+    Holds the resolved settings for the process. Resolution is deferred until
+    first use, so importing corekit never reads the environment or touches the
+    filesystem -- and so can never fail because a variable is missing.
+    """
+
+    def __init__(self, start: Path | None = None) -> None:
+        super().__init__()
+        self.start = start
+        self._settings: CorekitSettings | None = None
+
+    def file_sources(self) -> list[ConfigFileSource]:
+        """
+        The config files to consider, in priority order.
+        """
+        base = self.start or Path.cwd()
+        sources: list[ConfigFileSource] = [
+            ConfigFileSource(base / CONFIG_FILENAME),
+            PyprojectSource(base / "pyproject.toml"),
+            ConfigFileSource(USER_CONFIG_PATH),
+        ]
+        return sources
+
+    def active_file_source(self) -> ConfigFileSource | None:
+        """
+        The first config file that exists, or None.
+        """
+        return next((source for source in self.file_sources() if source.exists()), None)
+
+    def sources(self) -> list[ConfigSource]:
+        """
+        Every source to read, lowest priority first.
+
+        The environment is read explicitly rather than left to BaseSettings.
+        Values passed to its constructor outrank the environment in pydantic's
+        own precedence, so handing it the file contents that way would let a
+        config file override an environment variable -- the reverse of what is
+        documented.
+        """
+        found: list[ConfigSource] = []
+        file_source = self.active_file_source()
+        if file_source is not None:
+            found.append(file_source)
+        found.append(EnvironmentSource(ENV_PREFIX))
+        return found
+
+    def build(self) -> CorekitSettings:
+        """
+        Read every source and construct the settings.
+
+        Invalid configuration falls back to defaults rather than raising:
+        corekit has to remain importable, and a library that refuses to load
+        because of a stray value in a file is worse than one that logs the
+        problem and carries on. The log line is the difference between this and
+        silently ignoring it.
+        """
+        values: dict[str, Any] = {}
+        for source in self.sources():
+            values = self._merge(values, source.load())
+
+        try:
+            return CorekitSettings(**values)
+        except Exception as exc:
+            self.error(f"Invalid corekit configuration, falling back to defaults: {exc}")
+            return CorekitSettings()
+
+    @staticmethod
+    def _merge(base: dict[str, Any], incoming: dict[str, Any]) -> dict[str, Any]:
+        """
+        Overlay one mapping on another, section by section.
+
+        A plain update would let a source that sets one field in a section
+        discard every other field the sections below it had set.
+        """
+        merged = dict(base)
+        for key, value in incoming.items():
+            existing = merged.get(key)
+            if isinstance(existing, dict) and isinstance(value, dict):
+                merged[key] = SettingsLoader._merge(existing, value)
+            else:
+                merged[key] = value
+        return merged
+
+    @property
+    def settings(self) -> CorekitSettings:
+        """
+        The settings for this process, built on first access.
+        """
+        if self._settings is None:
+            self._settings = self.build()
+        return self._settings
+
+    @settings.setter
+    def settings(self, settings: CorekitSettings) -> None:
+        """
+        Install explicit settings, overriding every source.
+        """
+        self._settings = settings
+
+    def reset(self) -> None:
+        """
+        Discard the cached settings so the next access re-resolves them.
+        """
+        self._settings = None
+
+
+#: The loader every caller shares.
+loader = SettingsLoader()
+
+
+def get_settings() -> CorekitSettings:
+    """
+    The settings for this process.
+    """
+    return loader.settings
+
+
+def set_settings(settings: CorekitSettings) -> None:
+    """
+    Install explicit settings, overriding every source.
+    """
+    loader.settings = settings
+
+
+def reset_settings() -> None:
+    """
+    Discard the cached settings. Intended for tests.
+    """
+    loader.reset()