python-corekit 0.2.0__tar.gz → 0.3.0__tar.gz

{python_corekit-0.2.0 → python_corekit-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-corekit
-Version: 0.2.0
+Version: 0.3.0
 Summary: Shared foundations for Python projects: logging, benchmarking, registries, FastAPI application and routers, SQL statements and migrations, background tasks, and ETL
 Author: Steven Jacobsen
 License-Expression: MIT
@@ -55,7 +55,7 @@ extras to remember, and no import that fails because something was left out.
 Pin a compatible release rather than tracking whatever is newest:
 
 ```
-python-corekit~=0.2.0
+python-corekit~=0.3.0
 ```
 
 Before 1.0, the minor version carries breaking changes.
@@ -284,7 +284,7 @@ instead, which loses results silently and so is opt-in.
 ## HTTP clients
 
 ```python
-from corekit.http.client import BaseApiClient
+from corekit.http import BaseApiClient
 
 class GithubClient(BaseApiClient):
     """
@@ -301,7 +301,8 @@ response.data["login"]
 
 Retries 429 and 5xx with exponential backoff. Every response is a
 `BaseApiResponse`, so a non-JSON error page leaves `data` empty rather than
-raising. `async_get`, `async_post` and friends do the same without blocking.
+raising. The same methods are awaitable inside a running event loop:
+`await client.get(...)`.
 
 ## Serialization
 
@@ -351,7 +352,7 @@ Settings are grouped by concern, so `get_settings().concurrency.max_threads`
 says where a value belongs. Environment variables use a double underscore for
 the section: `COREKIT_CONCURRENCY__MAX_THREADS=16`.
 
-Environment variables use a `COREKIT_` prefix (`COREKIT_CRYPTO_SALT`). Empty
+Environment variables use a `COREKIT_` prefix (`COREKIT_CRYPTO__SALT`). Empty
 values are treated as unset, because container runtimes routinely pass `FOO=`
 for a variable that was never set.
 
@@ -375,7 +376,6 @@ Imports go downward only.
 ```
 corekit/
   config/                          settings, sources, loader
-  constants.py
 
   exceptions/                      error types
 
@@ -390,7 +390,7 @@ corekit/
   connections/                     the Connectable lifecycle and @connect
     sql/                           SQLConnection, statements, migrations
     redis/                         RedisConnection
-  http/                            BaseApiClient, retries, responses
+  http/                            BaseHttpClient, BaseApiClient, retries, responses
 
   api/                             Application, lifespan, middleware, routers
   docker/  notifications/  etl/

{python_corekit-0.2.0 → python_corekit-0.3.0}/README.md

@@ -20,7 +20,7 @@ extras to remember, and no import that fails because something was left out.
 Pin a compatible release rather than tracking whatever is newest:
 
 ```
-python-corekit~=0.2.0
+python-corekit~=0.3.0
 ```
 
 Before 1.0, the minor version carries breaking changes.
@@ -249,7 +249,7 @@ instead, which loses results silently and so is opt-in.
 ## HTTP clients
 
 ```python
-from corekit.http.client import BaseApiClient
+from corekit.http import BaseApiClient
 
 class GithubClient(BaseApiClient):
     """
@@ -266,7 +266,8 @@ response.data["login"]
 
 Retries 429 and 5xx with exponential backoff. Every response is a
 `BaseApiResponse`, so a non-JSON error page leaves `data` empty rather than
-raising. `async_get`, `async_post` and friends do the same without blocking.
+raising. The same methods are awaitable inside a running event loop:
+`await client.get(...)`.
 
 ## Serialization
 
@@ -316,7 +317,7 @@ Settings are grouped by concern, so `get_settings().concurrency.max_threads`
 says where a value belongs. Environment variables use a double underscore for
 the section: `COREKIT_CONCURRENCY__MAX_THREADS=16`.
 
-Environment variables use a `COREKIT_` prefix (`COREKIT_CRYPTO_SALT`). Empty
+Environment variables use a `COREKIT_` prefix (`COREKIT_CRYPTO__SALT`). Empty
 values are treated as unset, because container runtimes routinely pass `FOO=`
 for a variable that was never set.
 
@@ -340,7 +341,6 @@ Imports go downward only.
 ```
 corekit/
   config/                          settings, sources, loader
-  constants.py
 
   exceptions/                      error types
 
@@ -355,7 +355,7 @@ corekit/
   connections/                     the Connectable lifecycle and @connect
     sql/                           SQLConnection, statements, migrations
     redis/                         RedisConnection
-  http/                            BaseApiClient, retries, responses
+  http/                            BaseHttpClient, BaseApiClient, retries, responses
 
   api/                             Application, lifespan, middleware, routers
   docker/  notifications/  etl/

{python_corekit-0.2.0 → python_corekit-0.3.0}/corekit/api/application.py

@@ -26,16 +26,34 @@ from typing import Any, Sequence
 
 from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
 from fastapi.staticfiles import StaticFiles
 from starlette.middleware.trustedhost import TrustedHostMiddleware
 
 from corekit.api.middleware import MiddlewareStack
 from corekit.api.routers import CatchAllRouter, SimpleRouter, router_registry
+from corekit.exceptions import CoreHTTPException
 from corekit.observability.loggable import Loggable
 
 __all__ = ["Application"]
 
 
+def _origin_in_package(router: SimpleRouter, package_name: str) -> bool:
+    """
+    Whether this router was constructed by ``package_name`` or a submodule.
+    """
+    origin = router._origin_module
+    return origin == package_name or origin.startswith(f"{package_name}.")
+
+
+async def _core_http_exception_handler(request: Any, exc: CoreHTTPException) -> JSONResponse:
+    """
+    The same body FastAPI returns for ``HTTPException``.
+    """
+    headers = getattr(exc, "headers", None)
+    return JSONResponse(status_code=exc.status_code, content={"detail": exc.detail}, headers=headers)
+
+
 class Application(FastAPI, Loggable):
     """
     ``FastAPI`` plus router discovery, middleware helpers and static mounting.
@@ -47,6 +65,7 @@ class Application(FastAPI, Loggable):
         """
         FastAPI.__init__(self, *args, **kwargs)
         Loggable.__init__(self)
+        self._register_http_exception_handler()
 
     # ─── Routers ──────────────────────────────────────────────────────────
 
@@ -55,9 +74,12 @@ class Application(FastAPI, Loggable):
         Import every module under ``package`` and mount the routers it defines.
 
         Importing a module is what constructs its routers, so discovery is a
-        walk over ``package`` that lets each one register itself. A router that
-        was included into another router during that walk is skipped -- its
-        parent already owns it -- and any ``CatchAllRouter`` is mounted last.
+        walk over ``package`` that lets each one register itself. Only routers
+        constructed inside that package are mounted: the registry is
+        process-wide, and an unclaimed router from some other import must not
+        ride along. A router that was included into another router is skipped
+        -- its parent already owns it -- and any ``CatchAllRouter`` is mounted
+        last.
 
         Args:
             package: The imported package to search, e.g. ``app.backend.routers``.
@@ -78,11 +100,12 @@ class Application(FastAPI, Loggable):
 
         self._warn_on_unimportable_dirs(package)
 
-        before = len(router_registry)
         scanned = self._import_submodules(package)
-        discovered = len(router_registry) - before
-
-        mountable = router_registry.unclaimed
+        # unclaimed is every top-level router in the process. Mounting that
+        # list would include routers built by some other package that happens
+        # to be imported. Origin is where the instance was constructed, which
+        # is the scanned package for a router that belongs here.
+        mountable = [router for router in router_registry.unclaimed if _origin_in_package(router, name)]
         if not mountable:
             raise ValueError(
                 f"No routers found in '{name}' (scanned {scanned} modules). "
@@ -90,8 +113,9 @@ class Application(FastAPI, Loggable):
                 f"a SimpleRouter or SmartRouter at import time."
             )
 
-        claimed = discovered - len(mountable)
-        self.info(f"  scanned {scanned} modules, found {discovered} routers")
+        in_package = [router for router in router_registry if _origin_in_package(router, name)]
+        claimed = len(in_package) - len(mountable)
+        self.info(f"  scanned {scanned} modules, found {len(in_package)} routers")
         if claimed > 0:
             plural = "s" if claimed != 1 else ""
             self.info(f"  skipped {claimed} sub-router{plural} (already included by a parent)")
@@ -235,3 +259,17 @@ class Application(FastAPI, Loggable):
         self.mount(url_path, StaticFiles(directory=str(path), **kwargs), name=name or url_path.strip("/"))
         self.info(f"  + static {url_path:<24} -> {path}")
         return True
+
+    def _register_http_exception_handler(self) -> None:
+        """
+        Handle the library's HTTP exceptions the same way FastAPI handles its own.
+
+        ``CoreHTTPException`` is already an ``HTTPException``, so Starlette
+        would answer it. Registering the type explicitly keeps that response
+        -- ``{"detail": ...}`` only, never ``message`` or ``error`` -- even
+        if a later change in lookup order would otherwise miss the subclass.
+        A handler the caller already installed is left in place.
+        """
+        if CoreHTTPException in self.exception_handlers:
+            return
+        self.add_exception_handler(CoreHTTPException, _core_http_exception_handler)

{python_corekit-0.2.0 → python_corekit-0.3.0}/corekit/api/lifespan.py

@@ -108,7 +108,9 @@ class Lifespan(Loggable):
             startup: Called on the way up, in the order steps were added.
             shutdown: Called on the way down, in reverse order. Called only if
                 ``startup`` completed, so it can assume what ``startup`` builds.
-            tags: Free-form labels, for callers that group or filter steps.
+            tags: Labels used by ``for_tags``. Untagged steps always run; a
+                tagged step runs only when one of its tags is selected. With
+                no filter, every step runs.
             always_shutdown: Call ``shutdown`` even when ``startup`` raised.
                 For a startup that acquires something before it can fail -- a
                 connection opened, then a handshake that throws. The hook then
@@ -136,6 +138,25 @@ class Lifespan(Loggable):
         """The registered steps, in the order they will start."""
         return list(self._steps)
 
+    def for_tags(self, *tags: str) -> "Lifespan":
+        """
+        A lifespan that runs the steps matching ``tags``, plus untagged ones.
+
+        An untagged step is ordinary startup and always runs. A tagged step
+        runs only when the caller asked for one of its tags, so a label is a
+        filter rather than decoration. No tags means every step, which is
+        what ``__call__`` does.
+        """
+        if not tags:
+            return self
+
+        wanted = set(tags)
+        selected = Lifespan()
+        for step in self._steps:
+            if not step.tags or wanted.intersection(step.tags):
+                selected._steps.append(step)
+        return selected
+
     @asynccontextmanager
     async def __call__(self, app: Any = None) -> AsyncIterator[None]:
         """
@@ -166,7 +187,8 @@ class Lifespan(Loggable):
         stack.push_async_callback(self._run_shutdown, step)
 
         if step.startup is not None:
-            self.info(f"  ^ {step.name}")
+            label = step.name if not step.tags else f"{step.name} [{', '.join(step.tags)}]"
+            self.info(f"  ^ {label}")
             try:
                 await self._maybe_await(step.startup)
             except Exception:
@@ -192,7 +214,8 @@ class Lifespan(Loggable):
                 self.warning(f"  - {step.name} (skipped: startup did not complete)")
             return
 
-        self.info(f"  v {step.name}")
+        label = step.name if not step.tags else f"{step.name} [{', '.join(step.tags)}]"
+        self.info(f"  v {label}")
         try:
             await self._maybe_await(step.shutdown)
         except Exception:

{python_corekit-0.2.0 → python_corekit-0.3.0}/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"]

{python_corekit-0.2.0 → python_corekit-0.3.0}/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

{python_corekit-0.2.0 → python_corekit-0.3.0}/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:
         """

{python_corekit-0.2.0 → python_corekit-0.3.0}/corekit/concurrency/worker.py

@@ -5,6 +5,15 @@ 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,

{python_corekit-0.2.0 → python_corekit-0.3.0}/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]:
         """

{python_corekit-0.2.0 → python_corekit-0.3.0}/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)
 

{python_corekit-0.2.0 → python_corekit-0.3.0}/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",
 ]

{python_corekit-0.2.0 → python_corekit-0.3.0}/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")