python-corekit 0.1.0__py3-none-any.whl

corekit/config/settings.py

@@ -0,0 +1,161 @@
+"""
+The settings themselves.
+
+Grouped by concern rather than held in one flat namespace, so
+``settings.concurrency.max_threads`` says where a value belongs and a new
+section does not widen an already-wide class.
+"""
+
+import os
+from typing import Any
+
+from pydantic import BaseModel, Field, model_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+__all__ = [
+    "ConcurrencySettings",
+    "CryptoSettings",
+    "DatabaseSettings",
+    "CorekitSettings",
+    "RedisSettings",
+    "SerializationSettings",
+    "StandardsSettings",
+]
+
+ENV_PREFIX = "COREKIT_"
+
+# A ceiling for max_threads. Thread pools are cheap to ask for and expensive to
+# get wrong; this stops a typo in a config file from trying to start thousands.
+ABSOLUTE_THREAD_LIMIT = 256
+
+
+class StandardsSettings(BaseModel):
+    """
+    Enforcement of house rules.
+
+    Off by default. These are conventions, not library invariants, and crashing
+    a consumer's application over a missing docstring would be hostile.
+    """
+
+    require_handler_docstrings: bool = False
+    strict_mode: bool = False
+
+
+class ConcurrencySettings(BaseModel):
+    """
+    Limits on how many threads corekit will start on a caller's behalf.
+
+    ``default_threads`` is what a helper uses when the caller does not say, and
+    ``max_threads`` is the ceiling it will not exceed however it is asked. The
+    ceiling exists because a thread count is easy to get wrong by an order of
+    magnitude in a config file, and the failure is a hung machine rather than an
+    error message.
+    """
+
+    default_threads: int = Field(default=4, ge=1, le=ABSOLUTE_THREAD_LIMIT)
+    max_threads: int = Field(default=32, ge=1, le=ABSOLUTE_THREAD_LIMIT)
+
+    @model_validator(mode="after")
+    def _default_within_ceiling(self) -> "ConcurrencySettings":
+        """
+        Keep the default at or below the ceiling.
+
+        Configuring a default above the maximum is a contradiction, and silently
+        honouring one of the two would hide the mistake.
+        """
+        if self.default_threads > self.max_threads:
+            raise ValueError(f"default_threads ({self.default_threads}) exceeds max_threads ({self.max_threads})")
+        return self
+
+    def resolve(self, requested: int | None = None) -> int:
+        """
+        The thread count to actually use.
+
+        Falls back to the default, and never returns more than the ceiling, so a
+        caller asking for a thousand threads gets the maximum rather than a
+        thousand threads or an exception.
+        """
+        return min(self.default_threads if requested is None else max(1, requested), self.max_threads)
+
+    @staticmethod
+    def cpu_default() -> int:
+        """
+        A reasonable thread count for this machine, for callers that want one.
+        """
+        return min(32, (os.cpu_count() or 1) * 5)
+
+
+class CryptoSettings(BaseModel):
+    """
+    Hashing configuration.
+
+    ``salt`` has no default on purpose: the value that used to be hardcoded is
+    in git history and must be treated as compromised, so hashing raises until
+    one is supplied.
+    """
+
+    salt: str | None = None
+
+
+class DatabaseSettings(BaseModel):
+    """
+    Database connection details. ``None`` means the caller supplies a URL.
+    """
+
+    url: str | None = None
+
+
+class RedisSettings(BaseModel):
+    """
+    Redis connection details.
+    """
+
+    url: str | None = None
+
+
+class SerializationSettings(BaseModel):
+    """
+    Payload authentication.
+
+    ``key`` gates pickle and dill, both of which execute code while loading.
+    """
+
+    key: str | None = None
+
+
+class CorekitSettings(BaseSettings):
+    """
+    Runtime configuration for corekit.
+
+    Every field has a safe default, so an application that configures nothing
+    still gets working behaviour.
+
+    Nested sections are addressed with a double underscore in the environment::
+
+        COREKIT_CONCURRENCY__MAX_THREADS=16
+
+    and as tables in a config file::
+
+        [concurrency]
+        max_threads = 16
+    """
+
+    model_config = SettingsConfigDict(
+        env_prefix=ENV_PREFIX,
+        env_nested_delimiter="__",
+        env_ignore_empty=True,
+        extra="ignore",
+    )
+
+    standards: StandardsSettings = Field(default_factory=StandardsSettings)
+    concurrency: ConcurrencySettings = Field(default_factory=ConcurrencySettings)
+    crypto: CryptoSettings = Field(default_factory=CryptoSettings)
+    database: DatabaseSettings = Field(default_factory=DatabaseSettings)
+    redis: RedisSettings = Field(default_factory=RedisSettings)
+    serialization: SerializationSettings = Field(default_factory=SerializationSettings)
+
+    def merged_with(self, **overrides: Any) -> "CorekitSettings":
+        """
+        A copy with the given sections replaced. Useful in tests.
+        """
+        return self.model_copy(update=overrides)

corekit/config/sources.py

@@ -0,0 +1,125 @@
+"""
+Where configuration values come from.
+
+Each source knows how to produce a mapping and nothing else, so adding one -- a
+different format, a secrets store -- means adding a class rather than editing a
+function that already handles three cases.
+"""
+
+import os
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Any, ClassVar
+
+from corekit.files import TomlFileManager
+from corekit.observability import Loggable
+
+__all__ = ["ConfigFileSource", "ConfigSource", "EnvironmentSource", "PyprojectSource"]
+
+
+class ConfigSource(Loggable, ABC):
+    """
+    A place configuration values can be read from.
+
+    Sources never raise: an unreadable or malformed source contributes nothing
+    and says so in the log. Configuration is optional, and a library that
+    refuses to import because a stray file has a typo in it is worse than one
+    that falls back to its defaults.
+    """
+
+    @abstractmethod
+    def load(self) -> dict[str, Any]:
+        """
+        Return this source's values, or an empty mapping if it has none.
+        """
+        raise NotImplementedError
+
+
+class EnvironmentSource(ConfigSource):
+    """
+    Values from prefixed environment variables.
+    """
+
+    #: Separates a section from a field: COREKIT_CONCURRENCY__MAX_THREADS.
+    NESTED_DELIMITER: ClassVar[str] = "__"
+
+    def __init__(self, prefix: str) -> None:
+        super().__init__()
+        self.prefix = prefix
+
+    def load(self) -> dict[str, Any]:
+        """
+        Collect prefixed variables, treating empty values as unset.
+
+        Container runtimes routinely pass ``FOO=`` for a variable that was never
+        set, which would otherwise override a default with an empty string.
+        """
+        values: dict[str, Any] = {}
+        for key, value in os.environ.items():
+            if not key.startswith(self.prefix) or value == "":
+                continue
+            name = key[len(self.prefix) :].lower()
+            section, delimiter, field = name.partition(self.NESTED_DELIMITER)
+            if delimiter:
+                values.setdefault(section, {})[field] = value
+            else:
+                values[name] = value
+        return values
+
+
+class ConfigFileSource(ConfigSource):
+    """
+    Values from the top level of a TOML file.
+
+    Reads through ``TomlFileManager`` rather than calling ``tomllib`` directly,
+    so file handling stays in one place and this class is only responsible for
+    deciding what part of the parsed document to keep.
+    """
+
+    def __init__(self, path: Path) -> None:
+        super().__init__()
+        self.path = path
+
+    def exists(self) -> bool:
+        """
+        Whether this file is present and readable.
+        """
+        try:
+            return self.path.is_file()
+        except OSError:
+            return False
+
+    def _read(self) -> dict[str, Any]:
+        """
+        Parse the file, returning an empty mapping if it cannot be read.
+        """
+        try:
+            with TomlFileManager(str(self.path)) as file:
+                parsed = file.read()
+        except Exception as exc:
+            self.warning(f"Ignoring unreadable config file {self.path}: {exc}")
+            return {}
+        return parsed if isinstance(parsed, dict) else {}
+
+    def load(self) -> dict[str, Any]:
+        return self._read()
+
+
+class PyprojectSource(ConfigFileSource):
+    """
+    Values from a ``pyproject.toml``'s ``[tool.corekit]`` table.
+    """
+
+    #: The table this source reads, outermost key first.
+    TABLE_PATH: ClassVar[list[str]] = ["tool", "corekit"]
+
+    def load(self) -> dict[str, Any]:
+        """
+        Return the tool table, or nothing if the file does not declare one.
+        """
+        section: Any = self._read()
+        for key in self.TABLE_PATH:
+            if not isinstance(section, dict):
+                return {}
+            section = section.get(key, {})
+        return section if isinstance(section, dict) else {}

corekit/connections/__init__.py

@@ -0,0 +1,31 @@
+"""
+Connections: the abstraction, the concrete backends, and injection.
+
+``Connectable`` defines the lifecycle -- connect, disconnect, and both context
+manager protocols -- and ``sql`` and ``redis`` implement it. ``@connect`` opens
+one and hands it to a function, reusing whatever an outer call already opened.
+
+    from corekit.connections import connect
+    from corekit.connections.sql import SQLConnection
+
+    @connect(SQLConnection)
+    def get_user(conn, user_id: str) -> User:
+        return conn.fetch_one_by_id(User, user_id)
+
+The backends live here rather than at the top level because they are
+implementations of the abstraction directly above them, and there is no useful
+way to think about one without the other.
+"""
+
+from corekit.connections.connectable import Connectable, ConnectableType, ConnectionPreference
+from corekit.connections.decorators import connect
+from corekit.connections.registry import ConnectionRegistry, registry
+
+__all__ = [
+    "Connectable",
+    "ConnectableType",
+    "ConnectionPreference",
+    "ConnectionRegistry",
+    "connect",
+    "registry",
+]

corekit/connections/connectable.py

@@ -0,0 +1,212 @@
+"""
+A uniform way to connect to anything.
+
+``Connectable`` is a template-method base: a subclass implements four private
+hooks plus ``is_connected``, and inherits idempotent public ``connect`` /
+``disconnect``, both context manager protocols, and logging.
+
+    class MyDatabase(Connectable):
+        ...
+
+    with MyDatabase() as db:
+        rows = db.query(...)
+
+    async with MyDatabase() as db:
+        rows = await db.async_query(...)
+
+Subclasses register themselves by name, so tooling can resolve a connection
+class without importing it directly.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from corekit.observability.loggable import Loggable
+from corekit.registry import SmartRegistry
+from corekit.schemas.enum import StringEnum
+
+__all__ = ["Connectable", "ConnectableType", "ConnectionPreference"]
+
+
+class ConnectionPreference(StringEnum):
+    """
+    Whether a connection should prefer its sync or async path when both exist.
+    """
+
+    ASYNC = "async"
+    SYNC = "sync"
+
+
+class Connectable(Loggable, ABC):
+    """
+    Base class for anything with a connection lifecycle.
+
+    Implement ``is_connected``, ``_connect``, ``_disconnect``,
+    ``_async_connect`` and ``_async_disconnect``. The public methods are
+    provided and should not be overridden: they make connecting idempotent and
+    keep logging consistent across every connection type.
+    """
+
+    __registry__: SmartRegistry = SmartRegistry()
+
+    def __init__(
+        self,
+        *args: Any,
+        connection_preference: ConnectionPreference = ConnectionPreference.ASYNC,
+        read_only: bool = False,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__()
+        self._read_only = read_only
+        self._connection_preference = connection_preference
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        """
+        Register every concrete subclass under its class name.
+
+        This is what lets a connection registry stay open. Enumerating known
+        connection types in a fixed list means the enumerating module has to
+        import each concrete class, which inverts the dependency and limits
+        callers to the types that list happens to mention.
+        """
+        super().__init_subclass__(**kwargs)
+        if not getattr(cls, "__abstractmethods__", None):
+            Connectable.__registry__[cls.__name__] = cls
+
+    @classmethod
+    def get_connection_types(cls) -> SmartRegistry:
+        """
+        Return the registry of concrete Connectable subclasses.
+        """
+        return cls.__registry__
+
+    @classmethod
+    def get_connection_by_name(cls, name: str) -> type["Connectable"] | None:
+        """
+        Look up a connection class by name, using the registry's normalization.
+        """
+        return cls.__registry__.get(name)
+
+    @property
+    def read_only(self) -> bool:
+        """
+        Whether this connection was opened for reading only.
+        """
+        return self._read_only
+
+    @property
+    def connection_preference(self) -> ConnectionPreference:
+        """
+        Whether this connection prefers its sync or async path.
+        """
+        return self._connection_preference
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(connected={self.is_connected})"
+
+    def __str__(self) -> str:
+        return self.__repr__()
+
+    def __bool__(self) -> bool:
+        return self.is_connected
+
+    # ========================================
+    # =           Context Managers           =
+    # ========================================
+    def __enter__(self) -> "Connectable":
+        self.connect()
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        self.disconnect()
+
+    async def __aenter__(self) -> "Connectable":
+        await self.async_connect()
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        await self.async_disconnect()
+
+    @property
+    @abstractmethod
+    def is_connected(self) -> bool:
+        """
+        Whether the connection is currently established.
+        """
+        raise NotImplementedError
+
+    # ========================================
+    # =      Private Connection Methods      =
+    # ========================================
+    @abstractmethod
+    def _disconnect(self) -> None:
+        """
+        Tear the connection down. Must be safe to call when not connected.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def _connect(self) -> None:
+        """
+        Establish the connection.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    async def _async_disconnect(self) -> None:
+        """
+        Tear the connection down asynchronously. Must be safe when not connected.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    async def _async_connect(self) -> None:
+        """
+        Establish the connection asynchronously.
+        """
+        raise NotImplementedError
+
+    # ========================================
+    # =      Public Connection Methods       =
+    # ========================================
+    # Provided for the caller; subclasses implement the private hooks above so
+    # that lifecycle handling stays identical across every connection type.
+    def connect(self, force_reconnect: bool = False) -> None:
+        """
+        Connect if not already connected. Pass ``force_reconnect`` to rebuild
+        an existing connection.
+        """
+        if self.is_connected and not force_reconnect:
+            return
+
+        self.debug(f"Establishing {self.__class__.__name__} connection")
+        self._disconnect()
+        self._connect()
+
+    def disconnect(self) -> None:
+        """
+        Close the connection.
+        """
+        self.debug(f"Terminating {self.__class__.__name__} connection")
+        self._disconnect()
+
+    async def async_connect(self, force_reconnect: bool = False) -> None:
+        """
+        Connect asynchronously if not already connected.
+        """
+        if self.is_connected and not force_reconnect:
+            return
+
+        self.debug(f"Establishing async {self.__class__.__name__} connection")
+        await self._async_disconnect()
+        await self._async_connect()
+
+    async def async_disconnect(self) -> None:
+        """
+        Close the connection asynchronously.
+        """
+        self.debug(f"Terminating async {self.__class__.__name__} connection")
+        await self._async_disconnect()
+
+
+ConnectableType = type[Connectable]

corekit/connections/decorators.py

@@ -0,0 +1,92 @@
+"""
+Connection injection.
+
+``@connect`` opens a connection, hands it to the function as ``conn``, and
+closes it afterwards. Nested calls reuse the connection the outer one opened,
+so a whole call tree shares a single session::
+
+    @connect(SQLConnection)
+    def get_user(conn, user_id: str) -> User:
+        return conn.fetch_one_by_id(User, user_id)
+
+    @connect(SQLConnection)
+    def get_team(conn, team_id: str) -> Team:
+        # get_user reuses this connection rather than opening another
+        return Team(members=[get_user(uid) for uid in ...])
+
+``conn`` is stripped from the wrapped function's signature, so frameworks that
+introspect signatures -- FastAPI's dependency injection in particular -- never
+see it. That is what lets the same decorator work on HTTP routes, background
+jobs, websocket handlers and plain functions alike.
+"""
+
+import functools
+import inspect
+from typing import Any
+
+from corekit.connections.connectable import ConnectableType
+from corekit.connections.registry import registry
+
+__all__ = ["connect"]
+
+
+def connect(connector: ConnectableType, *connector_args: Any, **connector_kwargs: Any) -> Any:
+    """
+    Inject a managed connection as the ``conn`` parameter.
+
+    :param connector: the Connectable subclass to open.
+    :param connector_args: positional arguments for its constructor.
+    :param connector_kwargs: keyword arguments for its constructor.
+    """
+
+    def decorator(func: Any) -> Any:
+        params = list(inspect.signature(func).parameters)
+        conn_index = 1 if params and params[0] == "self" else 0
+
+        # inspect.unwrap sees through other decorators, so an async function
+        # wrapped in something else is still detected as async.
+        unwrapped = inspect.unwrap(func)
+        is_async = inspect.iscoroutinefunction(unwrapped) or inspect.isasyncgenfunction(unwrapped)
+
+        def _call(connection: Any, args: tuple, kwargs: dict) -> Any:
+            injected = args[:conn_index] + (connection,) + args[conn_index:]
+            return func(*injected, **kwargs)
+
+        @functools.wraps(func)
+        async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+            existing = registry.get(connector)
+            if existing is not None:
+                result = _call(existing, args, kwargs)
+                return await result if inspect.isawaitable(result) else result
+
+            with connector(*connector_args, **connector_kwargs) as connection:
+                registry.set(connector, connection)
+                try:
+                    result = _call(connection, args, kwargs)
+                    return await result if inspect.isawaitable(result) else result
+                finally:
+                    registry.clear(connector)
+
+        @functools.wraps(func)
+        def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+            existing = registry.get(connector)
+            if existing is not None:
+                return _call(existing, args, kwargs)
+
+            with connector(*connector_args, **connector_kwargs) as connection:
+                registry.set(connector, connection)
+                try:
+                    return _call(connection, args, kwargs)
+                finally:
+                    registry.clear(connector)
+
+        wrapper = async_wrapper if is_async else sync_wrapper
+
+        # Hide `conn` from anything that introspects the signature.
+        original = inspect.signature(func)
+        wrapper.__signature__ = original.replace(
+            parameters=[p for name, p in original.parameters.items() if name != "conn"]
+        )
+        return wrapper
+
+    return decorator

corekit/connections/redis/__init__.py

@@ -0,0 +1,7 @@
+"""
+Redis connections.
+"""
+
+from corekit.connections.redis.connection import RedisConnection, RedisNotConnectedError
+
+__all__ = ["RedisConnection", "RedisNotConnectedError"]