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

{python_corekit-0.1.0/python_corekit.egg-info → python_corekit-0.2.0}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: python-corekit
-Version: 0.1.0
-Summary: Shared foundations for Python projects: logging, benchmarking, registries, FastAPI routers/handlers, data stores, and ETL
+Version: 0.2.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
 Project-URL: Homepage, https://github.com/stevejaker/corekit
 Project-URL: Issues, https://github.com/stevejaker/corekit/issues
-Keywords: fastapi,etl,homelab,logging,benchmarking
+Keywords: fastapi,etl,logging,benchmarking,sqlmodel,migrations
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3.11
@@ -36,8 +36,8 @@ Dynamic: license-file
 # corekit
 
 Shared foundations for Python projects: structured logging, benchmarking,
-registries, FastAPI routers with built-in handlers, an in-memory record store,
-and ETL scaffolding.
+registries, a FastAPI application with routers and handlers, SQL statements and
+migrations, background tasks, an in-memory record store, and ETL scaffolding.
 
 Requires Python 3.11+.
 
@@ -47,17 +47,15 @@ Requires Python 3.11+.
 pip install python-corekit
 ```
 
-No credentials, no SSH key, no token — which means a project that depends on
-corekit can be cloned and built by anyone, including inside a Docker build.
+The distribution is `python-corekit`; the import is `corekit`.
 
 Every dependency corekit needs is installed with it. There are no optional
 extras to remember, and no import that fails because something was left out.
 
-The distribution is `python-corekit`; the import is `corekit`. Pin a compatible
-release rather than tracking whatever is newest:
+Pin a compatible release rather than tracking whatever is newest:
 
 ```
-python-corekit~=0.1.0
+python-corekit~=0.2.0
 ```
 
 Before 1.0, the minor version carries breaking changes.
@@ -90,6 +88,57 @@ class Report(Benchmarkable):
         self.timing("queried")   # logs the time since the previous split
 ```
 
+## Assembling an application
+
+`Application` is a plain `FastAPI` subclass — every constructor argument,
+including `lifespan`, passes straight through. What it adds is a short set of
+assembly steps, each of which logs what it did.
+
+```python
+from corekit.api import Application, Lifespan
+from app.backend import routers
+
+lifespan = Lifespan()
+lifespan.add("cache", startup=cache.connect, shutdown=cache.disconnect)
+
+app = Application(lifespan=lifespan)
+app.discover_routers(routers)
+```
+
+`discover_routers` imports every module under the package so each router can
+register itself. It raises if it finds none: passing a package is a statement
+that routers live there, and an app that silently serves nothing is worse than
+one that refuses to start.
+
+Lifespan steps start in the order added and shut down in reverse, the way
+nested `with` blocks unwind. If a step fails on the way up, the steps that
+already started are still torn down. A shutdown hook runs only if its own
+startup completed, so it may assume the state that startup builds — and a hook
+that raises cannot stop the unwind.
+
+### Middleware
+
+Middleware order is a security property: a host check that reads a client
+address before the proxy-header layer has rewritten it is checking the proxy,
+not the client. So middleware is never auto-discovered, and corekit installs
+none by default. A stack is declared in one place, outermost first — the order
+a request actually meets the layers.
+
+```python
+from corekit.api import MiddlewareStack
+
+stack = (
+    MiddlewareStack()
+    .add(ProxyHeadersMiddleware, trusted_hosts="*")
+    .add(TrustedHostMiddleware, allowed_hosts=HOSTS)
+    .add(CORSMiddleware, allow_origins=ORIGINS, allow_credentials=True)
+)
+app.add_middleware_stack(stack)
+```
+
+Reading top to bottom gives the order a request travels, which is the property
+you need when reviewing it.
+
 ## Routers and handlers
 
 A router and the handler holding its business logic travel together. Declare the
@@ -149,113 +198,67 @@ people.get_record("Ada").age            # O(1) lookup by id
 
 Stores pickle cleanly, including their dynamically generated record class.
 
-## Homelab pieces
+## SQL statements
 
-### Container control
+Select, insert, update and delete are objects you build and then execute, so a
+statement can be assembled in pieces and passed around before it runs.
 
 ```python
-from corekit.docker import Watchdog
+from corekit.connections.sql import SQLConnection, Select, Insert, Update, Delete
+from corekit.data import Field
 
-watchdog = Watchdog(enforce_label=True)
-watchdog.restart_container_by_name("minecraft")
-watchdog.find_and_stop(label="app", value="staging")
-```
+conn = SQLConnection("sqlite:///app.db")
 
-`enforce_label` limits the blast radius: with it on, only containers carrying
-the `watchdog=true` label can be started, stopped or paused, so a mistyped name
-cannot take down something unrelated. Leave it on unless the watchdog is meant
-to control everything on the host.
-
-### Reacting to logs
-
-Describe what to watch for and what to do about it:
-
-```yaml
-# config.yaml
-containers:
-  - name: "minecraft-.*"
-    rules:
-      - name: "out of memory"
-        pattern: "java.lang.OutOfMemoryError"
-        severity: critical
-        send_notification: true
-        actions:
-          - type: restart_container
-            max_restarts: 3
-            restart_window: 3600
-advanced:
-  ignore_patterns:
-    - "healthcheck"
-  rate_limits:
-    restart_container:
-      count: 5
-      period: hour
-```
+conn.execute(Insert(table=User, rows=[{"name": "Ada", "age": 36}]).add(name="Bob", age=17))
 
-```python
-from corekit.log_monitor import LogMonitor
+adults = conn.fetch(Select(table=User).where(User.age >= 18).order_by(User.name).limit(10))
 
-LogMonitor.run("config.yaml")
+conn.execute(Update(table=User).where(User.name == "Bob").set(age=18))
+conn.execute(Delete(table=User).where(User.age < 13))
 ```
 
-Restarts are capped per container, so a crash loop cannot become a restart loop.
-
-### Notifications
+`where` accepts a SQLAlchemy expression or a `corekit.data` one, so the same
+predicate language that filters a `Dataset` also filters a table:
 
 ```python
-from corekit.notifications import BaseNotificationService, Notification, NotificationType
-
-class DiscordNotifier(BaseNotificationService):
-    """
-    Sends notifications to a Discord channel.
-    """
-
-    def _send(self, message: str) -> None:
-        discord.post(message)
-
-notifier.notify(Notification(message="disk full", type=NotificationType.ERROR))
+Select(table=User).where(Field("age") >= 18)
 ```
 
-Override `_send`, not `send`. `notify()` formats the message and calls `_send`,
-so an override with any other name is silently ignored.
+Update and delete compile to a single statement rather than fetching rows and
+looping, which matters most over a network, where fetch-and-loop pays a round
+trip per row.
 
-### Real-time updates
+A `Delete` or `Update` with no condition raises rather than running:
 
-Publish from wherever the work happens:
-
-```python
-from corekit.events import EventPublisher
-
-publisher = EventPublisher.for_resource("minecraft", "server", "survival")
-publisher.publish("backup_finished", {"size": "4.2GB"})
+```
+Delete on User needs a condition; use truncate to empty a table
 ```
 
-Stream it to the browser:
+## Background tasks
 
-```python
-from corekit.api import SSEResponse
-from corekit.events import SSEStream
+Tasks describe work and register themselves by name. Nothing here imports a
+queue library, so the same task runs under RQ, Celery, a cron entry, or a test
+with no queue at all.
 
-@router.get("/events")
-async def events(channel: str) -> SSEResponse:
-    return SSEResponse(SSEStream(channel, keepalive_interval=15))
-```
+```python
+from corekit.jobs import Task, run_task
+from corekit.utils import encode_payload
 
-The browser side is three lines, and reconnects on its own:
+class SendDigest(Task):
+    def task_function(self, user: str) -> None:
+        ...
 
-```javascript
-const source = new EventSource("/events?channel=minecraft:server:survival");
-source.addEventListener("backup_finished", e => console.log(JSON.parse(e.data)));
+# a worker, holding only a name and a JSON string
+run_task("SendDigest", encode_payload(["ada"]))
 ```
 
-`SSEStream` sends a `connected` frame on subscribe, an optional `initial_state`
-so a client arriving late renders immediately, and a comment frame every
-`keepalive_interval` seconds so proxies do not close an idle connection. For
-WebSockets, `WebSocketBridge` relays the same channel and stops on a terminal
-status.
+Arguments cross the queue as JSON, never as a serialized object. `pickle` and
+`dill` execute code while loading, so a queue holding objects turns write
+access to the queue into code execution in a worker. `encode_payload` and
+`decode_payload` live in `corekit.utils`, since crossing a process boundary as
+data is not specific to queues.
 
-Publishing never raises: an event that cannot be delivered should not take down
-the operation that produced it. `publish` returns whether it worked.
+`ScheduledTask` adds an `interval` for tasks a scheduler should repeat.
 
 ## Parallel work
 
@@ -371,23 +374,25 @@ Imports go downward only.
 
 ```
 corekit/
-  config.py  constants.py
+  config/                          settings, sources, loader
+  constants.py
 
   exceptions/                      error types
 
   observability/                   Loggable, Benchmarkable, Timer
-  registry/  schemas/  utils/      SmartRegistry, enums and fields, helpers
+  registry/  schemas/  utils/      registries, enums and fields, helpers
   data/                            Dataset and its filter expressions
+  jobs/                            queue-independent background tasks
   crypto/  files/  serialization/
   concurrency/                     ThreadLocalRegistry, ThreadWorker
   decorators/
 
   connections/                     the Connectable lifecycle and @connect
-    sql/                           SQLConnection, queries, migrations
+    sql/                           SQLConnection, statements, migrations
     redis/                         RedisConnection
   http/                            BaseApiClient, retries, responses
 
-  api/                             handlers, routers, responses
+  api/                             Application, lifespan, middleware, routers
   docker/  notifications/  etl/
 
   events/  log_monitor/            built on the capabilities above
@@ -404,13 +409,13 @@ layering deliberately.
 ## Development
 
 ```bash
-pip install -e ".[dev,all]"
+pip install -e ".[dev]"
 pytest
 ruff format . && ruff check --fix .
 ```
 
-`tests/test_imports.py` imports every module in the package. Keep it passing:
-several modules were broken for months because nothing ever imported them.
+`tests/test_imports.py` imports every module in the package, so a module that
+nothing else happens to import still has to be importable.
 
 ## Licence
 

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

@@ -1,8 +1,8 @@
 # corekit
 
 Shared foundations for Python projects: structured logging, benchmarking,
-registries, FastAPI routers with built-in handlers, an in-memory record store,
-and ETL scaffolding.
+registries, a FastAPI application with routers and handlers, SQL statements and
+migrations, background tasks, an in-memory record store, and ETL scaffolding.
 
 Requires Python 3.11+.
 
@@ -12,17 +12,15 @@ Requires Python 3.11+.
 pip install python-corekit
 ```
 
-No credentials, no SSH key, no token — which means a project that depends on
-corekit can be cloned and built by anyone, including inside a Docker build.
+The distribution is `python-corekit`; the import is `corekit`.
 
 Every dependency corekit needs is installed with it. There are no optional
 extras to remember, and no import that fails because something was left out.
 
-The distribution is `python-corekit`; the import is `corekit`. Pin a compatible
-release rather than tracking whatever is newest:
+Pin a compatible release rather than tracking whatever is newest:
 
 ```
-python-corekit~=0.1.0
+python-corekit~=0.2.0
 ```
 
 Before 1.0, the minor version carries breaking changes.
@@ -55,6 +53,57 @@ class Report(Benchmarkable):
         self.timing("queried")   # logs the time since the previous split
 ```
 
+## Assembling an application
+
+`Application` is a plain `FastAPI` subclass — every constructor argument,
+including `lifespan`, passes straight through. What it adds is a short set of
+assembly steps, each of which logs what it did.
+
+```python
+from corekit.api import Application, Lifespan
+from app.backend import routers
+
+lifespan = Lifespan()
+lifespan.add("cache", startup=cache.connect, shutdown=cache.disconnect)
+
+app = Application(lifespan=lifespan)
+app.discover_routers(routers)
+```
+
+`discover_routers` imports every module under the package so each router can
+register itself. It raises if it finds none: passing a package is a statement
+that routers live there, and an app that silently serves nothing is worse than
+one that refuses to start.
+
+Lifespan steps start in the order added and shut down in reverse, the way
+nested `with` blocks unwind. If a step fails on the way up, the steps that
+already started are still torn down. A shutdown hook runs only if its own
+startup completed, so it may assume the state that startup builds — and a hook
+that raises cannot stop the unwind.
+
+### Middleware
+
+Middleware order is a security property: a host check that reads a client
+address before the proxy-header layer has rewritten it is checking the proxy,
+not the client. So middleware is never auto-discovered, and corekit installs
+none by default. A stack is declared in one place, outermost first — the order
+a request actually meets the layers.
+
+```python
+from corekit.api import MiddlewareStack
+
+stack = (
+    MiddlewareStack()
+    .add(ProxyHeadersMiddleware, trusted_hosts="*")
+    .add(TrustedHostMiddleware, allowed_hosts=HOSTS)
+    .add(CORSMiddleware, allow_origins=ORIGINS, allow_credentials=True)
+)
+app.add_middleware_stack(stack)
+```
+
+Reading top to bottom gives the order a request travels, which is the property
+you need when reviewing it.
+
 ## Routers and handlers
 
 A router and the handler holding its business logic travel together. Declare the
@@ -114,113 +163,67 @@ people.get_record("Ada").age            # O(1) lookup by id
 
 Stores pickle cleanly, including their dynamically generated record class.
 
-## Homelab pieces
+## SQL statements
 
-### Container control
+Select, insert, update and delete are objects you build and then execute, so a
+statement can be assembled in pieces and passed around before it runs.
 
 ```python
-from corekit.docker import Watchdog
+from corekit.connections.sql import SQLConnection, Select, Insert, Update, Delete
+from corekit.data import Field
 
-watchdog = Watchdog(enforce_label=True)
-watchdog.restart_container_by_name("minecraft")
-watchdog.find_and_stop(label="app", value="staging")
-```
+conn = SQLConnection("sqlite:///app.db")
 
-`enforce_label` limits the blast radius: with it on, only containers carrying
-the `watchdog=true` label can be started, stopped or paused, so a mistyped name
-cannot take down something unrelated. Leave it on unless the watchdog is meant
-to control everything on the host.
-
-### Reacting to logs
-
-Describe what to watch for and what to do about it:
-
-```yaml
-# config.yaml
-containers:
-  - name: "minecraft-.*"
-    rules:
-      - name: "out of memory"
-        pattern: "java.lang.OutOfMemoryError"
-        severity: critical
-        send_notification: true
-        actions:
-          - type: restart_container
-            max_restarts: 3
-            restart_window: 3600
-advanced:
-  ignore_patterns:
-    - "healthcheck"
-  rate_limits:
-    restart_container:
-      count: 5
-      period: hour
-```
+conn.execute(Insert(table=User, rows=[{"name": "Ada", "age": 36}]).add(name="Bob", age=17))
 
-```python
-from corekit.log_monitor import LogMonitor
+adults = conn.fetch(Select(table=User).where(User.age >= 18).order_by(User.name).limit(10))
 
-LogMonitor.run("config.yaml")
+conn.execute(Update(table=User).where(User.name == "Bob").set(age=18))
+conn.execute(Delete(table=User).where(User.age < 13))
 ```
 
-Restarts are capped per container, so a crash loop cannot become a restart loop.
-
-### Notifications
+`where` accepts a SQLAlchemy expression or a `corekit.data` one, so the same
+predicate language that filters a `Dataset` also filters a table:
 
 ```python
-from corekit.notifications import BaseNotificationService, Notification, NotificationType
-
-class DiscordNotifier(BaseNotificationService):
-    """
-    Sends notifications to a Discord channel.
-    """
-
-    def _send(self, message: str) -> None:
-        discord.post(message)
-
-notifier.notify(Notification(message="disk full", type=NotificationType.ERROR))
+Select(table=User).where(Field("age") >= 18)
 ```
 
-Override `_send`, not `send`. `notify()` formats the message and calls `_send`,
-so an override with any other name is silently ignored.
+Update and delete compile to a single statement rather than fetching rows and
+looping, which matters most over a network, where fetch-and-loop pays a round
+trip per row.
 
-### Real-time updates
+A `Delete` or `Update` with no condition raises rather than running:
 
-Publish from wherever the work happens:
-
-```python
-from corekit.events import EventPublisher
-
-publisher = EventPublisher.for_resource("minecraft", "server", "survival")
-publisher.publish("backup_finished", {"size": "4.2GB"})
+```
+Delete on User needs a condition; use truncate to empty a table
 ```
 
-Stream it to the browser:
+## Background tasks
 
-```python
-from corekit.api import SSEResponse
-from corekit.events import SSEStream
+Tasks describe work and register themselves by name. Nothing here imports a
+queue library, so the same task runs under RQ, Celery, a cron entry, or a test
+with no queue at all.
 
-@router.get("/events")
-async def events(channel: str) -> SSEResponse:
-    return SSEResponse(SSEStream(channel, keepalive_interval=15))
-```
+```python
+from corekit.jobs import Task, run_task
+from corekit.utils import encode_payload
 
-The browser side is three lines, and reconnects on its own:
+class SendDigest(Task):
+    def task_function(self, user: str) -> None:
+        ...
 
-```javascript
-const source = new EventSource("/events?channel=minecraft:server:survival");
-source.addEventListener("backup_finished", e => console.log(JSON.parse(e.data)));
+# a worker, holding only a name and a JSON string
+run_task("SendDigest", encode_payload(["ada"]))
 ```
 
-`SSEStream` sends a `connected` frame on subscribe, an optional `initial_state`
-so a client arriving late renders immediately, and a comment frame every
-`keepalive_interval` seconds so proxies do not close an idle connection. For
-WebSockets, `WebSocketBridge` relays the same channel and stops on a terminal
-status.
+Arguments cross the queue as JSON, never as a serialized object. `pickle` and
+`dill` execute code while loading, so a queue holding objects turns write
+access to the queue into code execution in a worker. `encode_payload` and
+`decode_payload` live in `corekit.utils`, since crossing a process boundary as
+data is not specific to queues.
 
-Publishing never raises: an event that cannot be delivered should not take down
-the operation that produced it. `publish` returns whether it worked.
+`ScheduledTask` adds an `interval` for tasks a scheduler should repeat.
 
 ## Parallel work
 
@@ -336,23 +339,25 @@ Imports go downward only.
 
 ```
 corekit/
-  config.py  constants.py
+  config/                          settings, sources, loader
+  constants.py
 
   exceptions/                      error types
 
   observability/                   Loggable, Benchmarkable, Timer
-  registry/  schemas/  utils/      SmartRegistry, enums and fields, helpers
+  registry/  schemas/  utils/      registries, enums and fields, helpers
   data/                            Dataset and its filter expressions
+  jobs/                            queue-independent background tasks
   crypto/  files/  serialization/
   concurrency/                     ThreadLocalRegistry, ThreadWorker
   decorators/
 
   connections/                     the Connectable lifecycle and @connect
-    sql/                           SQLConnection, queries, migrations
+    sql/                           SQLConnection, statements, migrations
     redis/                         RedisConnection
   http/                            BaseApiClient, retries, responses
 
-  api/                             handlers, routers, responses
+  api/                             Application, lifespan, middleware, routers
   docker/  notifications/  etl/
 
   events/  log_monitor/            built on the capabilities above
@@ -369,13 +374,13 @@ layering deliberately.
 ## Development
 
 ```bash
-pip install -e ".[dev,all]"
+pip install -e ".[dev]"
 pytest
 ruff format . && ruff check --fix .
 ```
 
-`tests/test_imports.py` imports every module in the package. Keep it passing:
-several modules were broken for months because nothing ever imported them.
+`tests/test_imports.py` imports every module in the package, so a module that
+nothing else happens to import still has to be importable.
 
 ## Licence
 

python_corekit-0.2.0/corekit/api/__init__.py

@@ -0,0 +1,24 @@
+"""
+FastAPI building blocks: an application, its lifespan, handlers, routers and responses.
+"""
+
+from corekit.api.application import Application
+from corekit.api.handler import BaseHandler
+from corekit.api.lifespan import Lifespan, LifespanStep
+from corekit.api.middleware import MiddlewareLayer, MiddlewareStack
+from corekit.api.responses import SSEResponse
+from corekit.api.routers import CatchAllRouter, SimpleRouter, SmartRouter, router_registry
+
+__all__ = [
+    "Application",
+    "BaseHandler",
+    "CatchAllRouter",
+    "Lifespan",
+    "LifespanStep",
+    "MiddlewareLayer",
+    "MiddlewareStack",
+    "SSEResponse",
+    "SimpleRouter",
+    "SmartRouter",
+    "router_registry",
+]