python-corekit 0.1.0__py3-none-any.whl → 0.2.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/worker.py

@@ -1,65 +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()
+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/settings.py

@@ -89,9 +89,9 @@ 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`` has no default on purpose. A salt shipped with a library is shared
+    by every install, which defeats the point of salting, so hashing raises
+    until one is supplied.
     """
 
     salt: str | None = None

corekit/connections/sql/__init__.py

@@ -1,10 +1,38 @@
 """
-SQL building blocks: a Connectable session, a query builder and a base table.
+SQL building blocks: a Connectable session, statement primitives and a base table.
 """
 
 from corekit.connections.sql.connection import PaginatedResult, SQLConnection
 from corekit.connections.sql.fields import JSONBField, PydanticJSON
+from corekit.connections.sql.operations import (
+    Conditional,
+    DdlOperation,
+    Delete,
+    DmlOperation,
+    DqlOperation,
+    Insert,
+    Operation,
+    Select,
+    Update,
+)
 from corekit.connections.sql.query import Query
-from corekit.connections.sql.table import NamedTable
+from corekit.connections.sql.table import NamedTable, TableExportItem
 
-__all__ = ["JSONBField", "NamedTable", "PaginatedResult", "PydanticJSON", "Query", "SQLConnection"]
+__all__ = [
+    "Conditional",
+    "DdlOperation",
+    "Delete",
+    "DmlOperation",
+    "DqlOperation",
+    "Insert",
+    "JSONBField",
+    "NamedTable",
+    "Operation",
+    "PaginatedResult",
+    "PydanticJSON",
+    "Query",
+    "Select",
+    "SQLConnection",
+    "TableExportItem",
+    "Update",
+]

corekit/connections/sql/connection.py

@@ -24,6 +24,7 @@ from sqlmodel import Session, SQLModel, create_engine, select
 
 from corekit.config import get_settings
 from corekit.connections import Connectable
+from corekit.connections.sql.operations import DmlOperation, DqlOperation, Operation
 from corekit.connections.sql.query import Query
 from corekit.connections.sql.table import NamedTable
 
@@ -320,6 +321,24 @@ class SQLConnection(Connectable):
         """
         return list(self._exec(query.build()))
 
+    def execute(self, operation: Operation) -> Any:
+        """
+        Run an operation, committing if it writes.
+
+        A read returns its rows; a write returns the result, whose
+        ``rowcount`` reports how many rows it touched.
+        """
+        result = self._exec(operation.build())
+        if isinstance(operation, DmlOperation):
+            self.session.commit()
+        return result
+
+    def fetch(self, operation: DqlOperation) -> list[NamedTable]:
+        """
+        Every row an operation selects.
+        """
+        return list(self.execute(operation))
+
     def fetch_one_by_query(self, query: Query) -> NamedTable | None:
         """
         The first row matching a Query.

corekit/connections/sql/migration/__init__.py

@@ -8,7 +8,7 @@ Define a migration by subclassing ``Migration`` and listing its operations::
         name = "user_is_active"
         description = "Adds the is_active flag to users."
 
-        def operations(self) -> list[Operation]:
+        def operations(self) -> list[MigrationOperation]:
             return [AddColumn(table="user", column="is_active", dtype="BOOLEAN", default="true")]
 
 Collect them from a package and run them::
@@ -25,12 +25,12 @@ from corekit.connections.sql.migration.operations import (
     AddColumn,
     AlterColumnType,
     CreateIndex,
-    DataOperation,
+    DataMigrationOperation,
     DropColumn,
     DropColumnDefault,
     DropIndex,
     DropTable,
-    Operation,
+    MigrationOperation,
     RenameColumn,
     RenameTable,
     SetColumnDefault,
@@ -42,7 +42,7 @@ __all__ = [
     "AddColumn",
     "AlterColumnType",
     "CreateIndex",
-    "DataOperation",
+    "DataMigrationOperation",
     "DropColumn",
     "DropColumnDefault",
     "DropIndex",
@@ -50,7 +50,7 @@ __all__ = [
     "Migration",
     "MigrationChecksumError",
     "MigrationRegistry",
-    "Operation",
+    "MigrationOperation",
     "RenameColumn",
     "RenameTable",
     "SchemaMigration",

corekit/connections/sql/migration/base.py

@@ -5,7 +5,7 @@ A Migration is defined by:
   - version:     unique positive integer, determines execution order
   - name:        short human-readable label (used in logs and the DB table)
   - description: longer explanation of what and why
-  - operations:  ordered list of Operation instances to execute
+  - operations:  ordered list of MigrationOperation instances to execute
 
 The checksum is computed at class definition time from the canonical
 representations of all operations. It is stored in the schema_migration
@@ -17,7 +17,7 @@ and will cause a hard crash.
 import hashlib
 from abc import ABC, abstractmethod
 
-from corekit.connections.sql.migration.operations import Operation
+from corekit.connections.sql.migration.operations import MigrationOperation
 
 
 class Migration(ABC):
@@ -26,7 +26,7 @@ class Migration(ABC):
     description: str
 
     @abstractmethod
-    def operations(self) -> list[Operation]:
+    def operations(self) -> list[MigrationOperation]:
         raise NotImplementedError
 
     @property