Contrib integrations

Mount citry_instance's routes into a FastAPI/Starlette app at prefix, and record the prefix on the instance.

Mount citry_instance's routes into a Flask app at prefix, and record the prefix on the instance.

Citry.urls as Django URL patterns, for include()-ing.

Pass prefix (where you include the patterns, e.g. "/citry") to also record it on the instance, so URL building (fragment manifests, the runtime src) points at the right place; leaving it None means you call set_mounted_prefix yourself.

The generated views are synchronous, so every route handler must be a plain function; an async def handler raises TypeError here, pointing at the ASGI adapter as the fix.

Reload changed component files in development, using Django's autoreloader.

Connects a receiver to Django's file_changed autoreload signal. When a watched file changes, the receiver clears the caches of the components that loaded it (Citry.invalidate_file). With mode="hot" (the default) the change is handled in place and the server keeps running; with mode="restart" the process restart is left to Django (the same thing Django does for a Python edit). Files that back no loaded component fall through to Django's normal handling either way.

Call once at startup, e.g. from your AppConfig.ready(). Django watches its template and static directories, so this needs no watcher of its own. Returns the connected receiver (disconnect it via file_changed.disconnect if you ever need to).

Django's SECRET_KEY, for passing as Citry(secret=...).

Citry signs values with the engine-level secret setting. In a Django project the natural signing key is the one the project already manages, so pass it through::

from citry import Citry
from citry.contrib.django import secret

app = Citry(secret=secret())

The key is read when this is called, so Django settings must be configured by then (in a normal Django startup they already are).

Returns

str: The ``SECRET_KEY`` of the active Django settings.

Raises

• RuntimeError - When Django settings are not configured; the message names the fix.
• django.core.exceptions.ImproperlyConfigured - When settings are configured but the ``SECRET_KEY`` itself is unusable (for example empty); Django's own message explains the problem.

Adapt a Django cache (django.core.cache.caches[...]) to citry's CitryCache protocol, so citry's stored scripts live in whatever cache backend the Django project already runs (Redis, Memcached, database, ...).

get(key: str) -> str | None

set(key: str, value: str, ttl: float | None = None) -> None

delete(key: str) -> None

has(key: str) -> bool

Build the ASGI application serving citry_instance.urls.

The returned app handles lifespan events (so it also works served standalone), routes each http request to the matched citry handler (preferring a route's handler_async twin when it carries one), translates the scope into a RouteRequest (_build_request), dispatches it (call_maybe_sync: async handlers are awaited, sync ones run in a worker thread), and translates the returned RouteResponse into ASGI messages (_send_response).

A Starlette/FastAPI lifespan that hot-reloads component files while the app runs.

Compose it into the app's root lifespan::

from contextlib import asynccontextmanager
from citry.contrib.asgi import reload_lifespan

watch_lifespan = reload_lifespan(citry_instance)

@asynccontextmanager
async def lifespan(app):
    citry_instance.initialize()
    async with watch_lifespan(app):
        yield

app = FastAPI(lifespan=lifespan)   # or Starlette(...)

It starts the :mod:citry.reload watcher on startup and stops it on shutdown, so editing a component's template/JS/CSS shows up on the next render without restarting. It manages only the watcher and does not call Citry.initialize(); the root lifespan owns initialization. For development; in production simply do not add it. If you already have a lifespan, nest this one inside yours. The keyword arguments mirror :func:citry.reload.watch.

Build the WSGI application serving citry_instance.urls.

The returned app routes each request to the matched citry handler, translates the environ into a RouteRequest (_build_request), calls the handler, and translates the returned RouteResponse back into the WSGI shape (respond). Async handlers are rejected with a pointed error up front: WSGI is synchronous.

Adapt a Redis client (redis.Redis or compatible) to citry's CitryCache protocol. Values are stored as UTF-8 strings; ttl becomes the key's expiry (ex).

prefix is prepended to every key, for sharing a Redis database with other uses. (Citry's own keys already start with citry:.)

get(key: str) -> str | None

set(key: str, value: str, ttl: float | None = None) -> None

delete(key: str) -> None

has(key: str) -> bool

Adapt a diskcache.Cache (or compatible) to citry's CitryCache protocol. The store is a directory on disk, shared by every worker process on the host.

get(key: str) -> str | None

set(key: str, value: str, ttl: float | None = None) -> None

delete(key: str) -> None

has(key: str) -> bool