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

corekit/api/routers.py

@@ -12,18 +12,45 @@ the subscript syntax::
         return await router.handler.list_users()
 """
 
+import inspect
 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
+from corekit.registry import OrderedRegistry
 
-__all__ = ["SimpleRouter", "SmartRouter"]
+__all__ = ["CatchAllRouter", "SimpleRouter", "SmartRouter", "router_registry"]
 
 H = TypeVar("H", bound=BaseHandler)
 
 
+class _RouterRegistry(OrderedRegistry["SimpleRouter"]):
+    """
+    Every ``SimpleRouter`` built in this process, in construction order.
+
+    ``Application.discover_routers`` imports a package to populate this, then
+    mounts what is left unclaimed. A router that has been included into another
+    router claims itself, so only top-level routers are mounted.
+    """
+
+    @property
+    def unclaimed(self) -> list["SimpleRouter"]:
+        """
+        Top-level routers, with any catch-all last.
+
+        Sorting is stable, so everything else keeps construction order.
+        """
+        return sorted(
+            self.where(lambda router: not router.claimed),
+            key=lambda router: isinstance(router, CatchAllRouter),
+        )
+
+
+router_registry = _RouterRegistry()
+
+
 class SimpleRouter(APIRouter, Benchmarkable):
     """
     An APIRouter that can log, time itself, and mount itself onto a parent.
@@ -39,13 +66,54 @@ class SimpleRouter(APIRouter, Benchmarkable):
         APIRouter.__init__(self, **kwargs)
         Benchmarkable.__init__(self)
 
+        # Discovery needs to see every router that was built, and to tell a
+        # top-level one from a sub-router. Both facts are recorded here rather
+        # than inferred later, when the import that created them is long done.
+        self._claimed = False
+        self._origin_module = self._caller_module()
+        router_registry.register(self)
+
+    @property
+    def claimed(self) -> bool:
+        """Whether a parent router has taken ownership of this one."""
+        return self._claimed
+
+    def claim(self) -> None:
+        """
+        Mark this router as owned by a parent, so discovery skips it.
+
+        Called by ``include`` rather than by hand: a router that a parent has
+        already mounted must not also be mounted at the application root.
+        """
+        self._claimed = True
+
+    @staticmethod
+    def _caller_module() -> str:
+        """
+        The module that constructed this router.
+
+        ``type(self).__module__`` names where the class is defined, which is
+        always corekit; discovery logs need where the instance was built. Walk
+        out of corekit's own frames to find it.
+        """
+        for frame in inspect.stack()[1:]:
+            module = frame.frame.f_globals.get("__name__", "")
+            if not module.startswith("corekit."):
+                return module
+        return "<unknown>"
+
     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)``.
+
+        Including into another router claims this one, so ``discover_routers``
+        will not mount it a second time at the application root.
         """
+        if isinstance(parent, APIRouter):
+            self.claim()
         parent.include_router(self, *args, **kwargs)
 
 
@@ -113,3 +181,43 @@ class SmartRouter(SimpleRouter, Generic[H]):
         Replace the handler. Assigning a double is the supported way to test a router.
         """
         self._handler = handler
+
+
+class CatchAllRouter(SmartRouter[H]):
+    """
+    The router of last resort, mounted after every other route.
+
+    A single-page app needs one of these: a ``/{path:path}`` route that serves
+    ``index.html`` so the client-side router can take over. Mounted in the wrong
+    order it shadows the entire API, because it matches everything.
+
+    Being a distinct type rather than an ordering flag means that position is a
+    property of what the router *is*. ``discover_routers`` always mounts it last,
+    and a second instance is refused -- two catch-alls means one of them silently
+    never matches, which is not a state worth allowing.
+    """
+
+    _instance: "CatchAllRouter[Any] | None" = None
+
+    def __init__(self, handler: H | None = None, **kwargs: Any) -> None:
+        """
+        Build the catch-all. Raises if one already exists in this process.
+        """
+        existing = CatchAllRouter._instance
+        if existing is not None:
+            raise RuntimeError(
+                f"A CatchAllRouter already exists ({existing._origin_module}). "
+                f"Only one may exist: it matches every unmatched path, so a second "
+                f"could never receive a request. Delete one, or make it a SmartRouter "
+                f"with an explicit prefix."
+            )
+
+        super().__init__(handler=handler, **kwargs)
+        CatchAllRouter._instance = self
+
+    @classmethod
+    def reset(cls) -> None:
+        """
+        Forget the registered instance. For tests that build more than one app.
+        """
+        cls._instance = None

corekit/concurrency/__init__.py

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

corekit/concurrency/decorators.py

@@ -18,19 +18,26 @@ 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.
+
+``allow_sync`` wraps an async function so a script can call it directly, while
+an already-running event loop still gets a coroutine to await.
 """
 
+import asyncio
 import functools
+import logging
+from collections.abc import Awaitable, Callable
 from concurrent.futures import Future, ThreadPoolExecutor, as_completed
-from typing import Any, Callable, Iterable, Iterator
+from typing import Any, Iterable, Iterator, ParamSpec, TypeVar
 
 from corekit.config import get_settings
-from corekit.observability import Loggable
 
-__all__ = ["parallelize"]
+__all__ = ["parallelize", "allow_sync"]
+
+_logger = logging.getLogger("parallelize")
 
-_logger = Loggable()
-_logger.logger = _logger.logger.getChild("parallelize")
+P = ParamSpec("P")
+R = TypeVar("R")
 
 
 def parallelize(
@@ -70,3 +77,23 @@ def parallelize(
         return wrapper
 
     return decorator
+
+
+def allow_sync(async_func: Callable[P, Awaitable[R]]) -> Callable[P, R | Awaitable[R]]:
+    """
+    Call an async function from sync code, or return its coroutine if a loop is running.
+
+    A script gets the result back immediately. Inside an async app the wrapper
+    returns the coroutine, so the caller must await it — calling the wrapper
+    and ignoring the result will not run the function.
+    """
+
+    @functools.wraps(async_func)
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R | Awaitable[R]:
+        try:
+            asyncio.get_running_loop()
+        except RuntimeError:
+            return asyncio.run(async_func(*args, **kwargs))
+        return async_func(*args, **kwargs)
+
+    return wrapper

corekit/concurrency/thread_local.py

@@ -19,7 +19,7 @@ import threading
 from typing import Any
 
 from corekit.observability.loggable import Loggable
-from corekit.registry import SmartRegistry
+from corekit.registry import normalize_key
 
 __all__ = ["ThreadLocalRegistry"]
 
@@ -59,7 +59,7 @@ class ThreadLocalRegistry(threading.local, Loggable):
         turn SQLConnection into "sqlconnection" rather than "sql_connection".
         """
         name = key.__name__ if isinstance(key, type) else str(key)
-        return SmartRegistry.__normalize_key__(name).replace("-", "_")
+        return normalize_key(name).replace("-", "_")
 
     def get(self, key: Any, fallback: Any = None) -> Any:
         """

corekit/concurrency/worker.py

@@ -1,65 +1,74 @@
-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()
+import asyncio
+import logging
+import threading
+import time
+
+
+class ThreadWorker(threading.Thread):
+    """
+    A daemon thread that waits for ``can_start``, then calls ``process`` once.
+
+    ``timeout`` and ``loop`` are stored for a subclass that wants them.
+    ``run`` does not enforce ``timeout`` and does not drive ``loop``.
+    ``stop`` sets ``running`` so a subclass of ``process`` can notice it; it
+    does not interrupt a thread already inside ``process``.
+    """
+
+    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/loader.py

@@ -9,6 +9,8 @@ settings know only their own shape.
 from pathlib import Path
 from typing import Any
 
+from pydantic import ValidationError
+
 from corekit.config.settings import ENV_PREFIX, CorekitSettings
 from corekit.config.sources import ConfigFileSource, ConfigSource, EnvironmentSource, PyprojectSource
 from corekit.observability import Loggable
@@ -72,11 +74,12 @@ class SettingsLoader(Loggable):
         """
         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.
+        Invalid configuration drops the bad section and keeps the rest.
+        A bad thread count must not discard a valid salt or serialization
+        key that arrived from another section or the environment. If what
+        remains still will not validate, the last resort is defaults --
+        corekit has to remain importable. The log line is the difference
+        between this and silently ignoring it.
         """
         values: dict[str, Any] = {}
         for source in self.sources():
@@ -84,10 +87,44 @@ class SettingsLoader(Loggable):
 
         try:
             return CorekitSettings(**values)
+        except ValidationError as exc:
+            cleaned, dropped = self._without_invalid_sections(values, exc)
+            if dropped:
+                self.error(
+                    f"Invalid corekit configuration in {', '.join(dropped)}; "
+                    f"those sections fall back to defaults: {exc}"
+                )
+                try:
+                    return CorekitSettings(**cleaned)
+                except ValidationError as retry_exc:
+                    self.error(f"Invalid corekit configuration, falling back to defaults: {retry_exc}")
+                    return CorekitSettings()
+            self.error(f"Invalid corekit configuration, falling back to defaults: {exc}")
+            return CorekitSettings()
         except Exception as exc:
             self.error(f"Invalid corekit configuration, falling back to defaults: {exc}")
             return CorekitSettings()
 
+    @staticmethod
+    def _without_invalid_sections(values: dict[str, Any], exc: ValidationError) -> tuple[dict[str, Any], list[str]]:
+        """
+        Drop each section named in a validation error, leaving the others.
+
+        A section is the first element of the error location. A failure that
+        names no section cannot be isolated, so nothing is dropped and the
+        caller falls back to defaults.
+        """
+        dropped: list[str] = []
+        for error in exc.errors():
+            loc = error.get("loc") or ()
+            if not loc:
+                continue
+            section = str(loc[0])
+            if section not in dropped:
+                dropped.append(section)
+        cleaned = {key: value for key, value in values.items() if key not in dropped}
+        return cleaned, dropped
+
     @staticmethod
     def _merge(base: dict[str, Any], incoming: dict[str, Any]) -> dict[str, Any]:
         """

corekit/config/settings.py

@@ -35,6 +35,10 @@ class StandardsSettings(BaseModel):
 
     Off by default. These are conventions, not library invariants, and crashing
     a consumer's application over a missing docstring would be hostile.
+
+    ``strict_mode`` makes a ``SmartRegistry`` refuse a second write to a
+    normalized key instead of warning and replacing. It does not imply
+    ``require_handler_docstrings``; that check stays its own flag.
     """
 
     require_handler_docstrings: bool = False
@@ -80,7 +84,13 @@ class ConcurrencySettings(BaseModel):
     @staticmethod
     def cpu_default() -> int:
         """
-        A reasonable thread count for this machine, for callers that want one.
+        A machine-sized thread count, for a caller that asks for one.
+
+        Not what ``resolve`` or ``parallelize`` use when the caller is silent.
+        Those use ``default_threads``. Pass this in when the work should
+        scale with the machine::
+
+            parallelize(num_threads=ConcurrencySettings.cpu_default())
         """
         return min(32, (os.cpu_count() or 1) * 5)
 

corekit/connections/__init__.py

@@ -17,7 +17,12 @@ 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.connectable import (
+    Connectable,
+    ConnectableType,
+    ConnectionPreference,
+    ReadOnlyConnectionError,
+)
 from corekit.connections.decorators import connect
 from corekit.connections.registry import ConnectionRegistry, registry
 
@@ -26,6 +31,7 @@ __all__ = [
     "ConnectableType",
     "ConnectionPreference",
     "ConnectionRegistry",
+    "ReadOnlyConnectionError",
     "connect",
     "registry",
 ]

corekit/connections/connectable.py

@@ -21,22 +21,40 @@ class without importing it directly.
 from abc import ABC, abstractmethod
 from typing import Any
 
+from corekit.exceptions import InternalCoreException, Retryability
 from corekit.observability.loggable import Loggable
 from corekit.registry import SmartRegistry
 from corekit.schemas.enum import StringEnum
 
-__all__ = ["Connectable", "ConnectableType", "ConnectionPreference"]
+__all__ = ["Connectable", "ConnectableType", "ConnectionPreference", "ReadOnlyConnectionError"]
 
 
 class ConnectionPreference(StringEnum):
     """
-    Whether a connection should prefer its sync or async path when both exist.
+    A stored hint for which path a caller prefers.
+
+    The base class records this and does not consult it. ``connect`` and
+    ``async_connect`` follow the method the caller invoked, and ``@connect``
+    always opens with ``with``. A subclass may read the hint; nothing here
+    switches paths because of it.
     """
 
     ASYNC = "async"
     SYNC = "sync"
 
 
+class ReadOnlyConnectionError(InternalCoreException):
+    """
+    Raised when a write is attempted on a connection opened read-only.
+    """
+
+    def __init__(self, connection: str) -> None:
+        super().__init__(
+            message=f"{connection} is read-only",
+            retryable=Retryability.NON_RETRYABLE,
+        )
+
+
 class Connectable(Loggable, ABC):
     """
     Base class for anything with a connection lifecycle.
@@ -97,10 +115,20 @@ class Connectable(Loggable, ABC):
     @property
     def connection_preference(self) -> ConnectionPreference:
         """
-        Whether this connection prefers its sync or async path.
+        The path hint recorded at construction. Not used to open the connection.
         """
         return self._connection_preference
 
+    def require_writable(self) -> None:
+        """
+        Raise if this connection was opened for reading only.
+
+        Corekit's own write methods call this. The base class does not wrap
+        every method, so a subclass with its own writes should call it too.
+        """
+        if self._read_only:
+            raise ReadOnlyConnectionError(type(self).__name__)
+
     def __repr__(self) -> str:
         return f"{self.__class__.__name__}(connected={self.is_connected})"
 
@@ -190,11 +218,24 @@ class Connectable(Loggable, ABC):
         self.debug(f"Terminating {self.__class__.__name__} connection")
         self._disconnect()
 
+    def _async_is_open(self) -> bool:
+        """
+        Whether the async path is already up.
+
+        ``is_connected`` is the sync flag. Redis keeps a process-wide sync pool
+        and a separate async client, so a sync pool must not stand in for the
+        async client. Classes without ``is_async_connected`` use ``is_connected``.
+        """
+        for cls in type(self).mro():
+            if "is_async_connected" in cls.__dict__:
+                return bool(self.is_async_connected)
+        return self.is_connected
+
     async def async_connect(self, force_reconnect: bool = False) -> None:
         """
         Connect asynchronously if not already connected.
         """
-        if self.is_connected and not force_reconnect:
+        if self._async_is_open() and not force_reconnect:
             return
 
         self.debug(f"Establishing async {self.__class__.__name__} connection")