python-corekit 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

corekit/utils/text.py

@@ -0,0 +1,56 @@
+"""
+String assembly helpers.
+
+Small formatters for turning collections into text a human will read -- log
+lines, notification bodies, error messages -- plus filename sanitization.
+"""
+
+import re
+from typing import Any, Literal
+
+__all__ = ["join_lines", "list_to_english", "sanitize_filename"]
+
+FALLBACK_FILENAME = "unnamed"
+_UNSAFE_CHARS = re.compile(r"[^a-z0-9\-]")
+_REPEATED_HYPHENS = re.compile(r"-{2,}")
+
+
+def join_lines(*items: Any, prefix: str = "") -> str:
+    """
+    Join items with newlines, optionally prefixing each one.
+    """
+    return "\n".join(f"{prefix}{item}" for item in items)
+
+
+def list_to_english(items: list[str], ending: Literal["and", "or"] | None = None) -> str:
+    """
+    Join items into a readable list: ``"a, b, and c"``.
+
+    Without ``ending`` the final item is joined with a plain comma, which suits
+    a bare enumeration; pass ``"and"`` or ``"or"`` for prose.
+    """
+    if not items:
+        return ""
+
+    if len(items) == 1:
+        return items[0]
+
+    buffer = ", ".join(items[:-1])
+    last = items[-1]
+
+    if ending is None:
+        return f"{buffer}, {last}"
+    return f"{buffer}, {ending} {last}"
+
+
+def sanitize_filename(raw: str, fallback: str = FALLBACK_FILENAME) -> str:
+    """
+    Reduce a string to lowercase kebab-case safe for use as a filename stem.
+
+    Everything outside ``a-z0-9-`` becomes a hyphen, runs collapse, and the
+    result is trimmed. A string with nothing usable in it returns ``fallback``
+    rather than the empty string, which would produce a nameless file.
+    """
+    cleaned = _UNSAFE_CHARS.sub("-", raw.strip().lower())
+    cleaned = _REPEATED_HYPHENS.sub("-", cleaned).strip("-")
+    return cleaned or fallback

corekit/utils/time.py

@@ -1,21 +1,74 @@
-from datetime import UTC, datetime, timedelta
-
-
-def time_now() -> datetime:
-    """
-    Helper for getting the current UTC time
-    """
-    return datetime.now(UTC)
-
-
-def timedelta_now(delta_seconds: int | None = None, add_time: bool = False, **kwargs) -> datetime:
-    """
-    Helper for getting a quick timedelta
-    """
-    if delta_seconds is not None:
-        kwargs = {"seconds": delta_seconds}
-
-    delta = timedelta(**kwargs)
-    if add_time:
-        return time_now() + delta
-    return time_now() - delta
+"""
+Timezone-aware time helpers.
+
+Every function returns UTC. Naive datetimes are the usual source of "works on
+my machine" time bugs, so nothing here produces one.
+"""
+
+import re
+from datetime import UTC, datetime, timedelta
+from typing import Any
+
+__all__ = ["isoformat_now", "parse_docker_timestamp", "time_now", "timedelta_now", "timestamp_now"]
+
+# Docker reports nanosecond precision; fromisoformat accepts at most microseconds.
+_DOCKER_TS_PATTERN = re.compile(r"(\.\d{6})\d*")
+
+# Docker's zero value for "this never happened".
+_DOCKER_ZERO_TIME = "0001-01-01"
+
+
+def time_now() -> datetime:
+    """
+    Return the current UTC time, timezone-aware.
+    """
+    return datetime.now(UTC)
+
+
+def isoformat_now() -> str:
+    """
+    Return the current UTC time as an ISO 8601 string.
+    """
+    return time_now().isoformat()
+
+
+def timestamp_now() -> float:
+    """
+    Return the current UTC time as a Unix timestamp.
+    """
+    return time_now().timestamp()
+
+
+def timedelta_now(delta_seconds: int | None = None, add_time: bool = False, **kwargs: Any) -> datetime:
+    """
+    Return a time offset from now, in the past by default.
+
+    Pass ``delta_seconds`` for the common case, or any ``timedelta`` keyword
+    (``days``, ``hours``, ...) for the rest. ``add_time`` moves forward instead
+    of back.
+    """
+    if delta_seconds is not None:
+        kwargs = {"seconds": delta_seconds}
+
+    delta = timedelta(**kwargs)
+    if add_time:
+        return time_now() + delta
+    return time_now() - delta
+
+
+def parse_docker_timestamp(value: str | None) -> float | None:
+    """
+    Parse a docker API timestamp into a Unix timestamp, or ``None``.
+
+    Docker emits nanosecond-precision ISO 8601 (a container's ``State.StartedAt``,
+    for instance), which ``fromisoformat`` rejects. Returns ``None`` for empty
+    input, docker's zero timestamp, and anything unparseable, so a caller can
+    treat "no such time" and "bad time" the same way.
+    """
+    if not value or value.startswith(_DOCKER_ZERO_TIME):
+        return None
+    try:
+        trimmed = _DOCKER_TS_PATTERN.sub(r"\1", value.replace("Z", "+00:00"))
+        return datetime.fromisoformat(trimmed).timestamp()
+    except ValueError:
+        return None

corekit/utils/validators.py

@@ -1,15 +1,15 @@
-from typing import Any
-
-
-def true_validator(*args: Any, **kwargs: Any) -> bool:
-    """
-    Generic placeholder validator function that always returns True
-    """
-    return True
-
-
-def false_validator(*args: Any, **kwargs: Any) -> bool:
-    """
-    Generic placeholder validator function that always returns False
-    """
-    return False
+from typing import Any
+
+
+def true_validator(*args: Any, **kwargs: Any) -> bool:
+    """
+    Generic placeholder validator function that always returns True
+    """
+    return True
+
+
+def false_validator(*args: Any, **kwargs: Any) -> bool:
+    """
+    Generic placeholder validator function that always returns False
+    """
+    return False

corekit/utils/void.py

@@ -1,8 +1,8 @@
-from typing import Any
-
-
-def void(ex: Exception, *args: Any, **kwargs: Any) -> None:
-    """
-    Generic callback function that does nothing and returns nothing
-    """
-    pass
+from typing import Any
+
+
+def void(ex: Exception, *args: Any, **kwargs: Any) -> None:
+    """
+    Generic callback function that does nothing and returns nothing
+    """
+    pass

{python_corekit-0.1.0.dist-info → python_corekit-0.2.0.dist-info}/METADATA

@@ -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