gramlot-py-server

For an existing gallery, follow the update procedure: update the active environment, restart and verify. Source checkouts require a separate browser build.

Gramlot describes web interfaces in Python or JavaScript and keeps them bound to application state in the browser. See The Gramlot family for the core and the other repositories.

What this repository is

gramlot-py-server serves Gramlot pages written in Python from a Python web server. One package holds one adapter per framework; each comes with its extra:

Every adapter serves one folder of Page modules through the core GramlotFileServer: it sends the bootstrap document, passes the envelopes of POST /gramlot/rpc to GramlotServer.call (the page main, fragments and @endpoint methods), serves the page companions (.css and .js), the themes of the core, an optional map of assets and the browser runtime, with a mount prefix and a Content Security Policy of your choice. It does not serve JavaScript pages (gramlot-js-server does) and it does not talk to a database.

What an adapter answers over HTTP is the server protocol of the core, Part B. The five adapters share one base, gramlot_py_server.base, which writes those rules once (methods and Allow, Cache-Control, the owner cookie, status codes, shutdown); each adapter adds only its routing and the translation between its framework and the base.

Declare Source fragments with @source and mount them with remote; use dataRpc for endpoint values and dataRemote for lazy Data. See Calling the server and Remote content and lazy Data.

The Kajenn adapter announces the auth capability: it evaluates an auth rule with genro_toolbox.tags_match against the tags of the request's Kajenn avatar, as the genro-routes AuthPlugin does for route entries. Registering the endpoints as genro-routes RouterNodes with the other plugins belongs to genro-kajenn. The other adapters announce no capability: an endpoint with an auth rule answers not_authenticated.

The current release is 0.3.16, on PyPI as gramlot-py-server.

Quick start

Python 3.11 or later. Install the package with the extra of your framework, then create a project with gramlot <framework> new <folder>:

python -m pip install "gramlot-py-server[uvicorn]"
gramlot uvicorn new hello
cd hello
uvicorn app:application

Open http://127.0.0.1:8000/. The page shows a field with Ada and the text Hello, Ada. Typing Grace in the field changes the text to Hello, Grace at every keystroke.

The command writes the same page for every framework, pages/index.py:

from gramlot import Page as BasePage


class Page(BasePage):
    title = "Hello"

    def main(self, root):
        pane = root.div(datapath="person")
        pane.html_label("Name", for_="name")
        pane.input(id="name", value="^.name", live=True)
        pane.p("^.greeting")
        pane.dataFormula(".greeting", func="greeting", name="^.name", _init=True)
        pane.dataSetter(".name", "Ada")

and its page module pages/index.js. The formula names its method with func="greeting"; the method is in the Logic export and runs in the browser:

export class Logic {
    greeting(kwargs) { return 'Hello, ' + kwargs.name; }
}

The page has no inline code, so every project sends the strict Content Security Policy profile. Beside pages/ the command writes requirements.txt, with the extra of the framework, and the files of the framework below. The docstring of each file gives the command that starts it, which gramlot also prints.

Uvicorn, gramlot uvicorn new, app.py:

"""Serve the pages with Uvicorn: ``uvicorn app:application``."""
from pathlib import Path

from gramlot_py_server.uvicorn import create_application

PAGES = Path(__file__).resolve().parent / "pages"

application = create_application(
    PAGES,
    content_security_policy="script-src 'nonce-{nonce}'; object-src 'none'; base-uri 'none'",
)

Django, gramlot django new, settings.py and urls.py:

"""Django settings: ``django-admin runserver --settings=settings --pythonpath=.``."""

SECRET_KEY = "development-only-change-me"
DEBUG = True
ALLOWED_HOSTS = ["127.0.0.1", "localhost", "testserver"]
ROOT_URLCONF = "urls"
INSTALLED_APPS: list[str] = []
MIDDLEWARE = ["django.middleware.csrf.CsrfViewMiddleware"]

"""URLconf: the Gramlot pages at the site root."""
from pathlib import Path

from gramlot_py_server.django import Pages

PAGES = Path(__file__).resolve().parent / "pages"

pages = Pages(
    PAGES,
    content_security_policy="script-src 'nonce-{nonce}'; object-src 'none'; base-uri 'none'",
)

urlpatterns = [*pages.urlpatterns]

Flask, gramlot flask new, app.py:

"""Serve the pages inside a Flask app: ``flask --app app run --port 8000``."""
from pathlib import Path

from flask import Flask

from gramlot_py_server.flask import mount_pages

PAGES = Path(__file__).resolve().parent / "pages"

app = Flask(__name__)
mount_pages(
    app,
    PAGES,
    content_security_policy="script-src 'nonce-{nonce}'; object-src 'none'; base-uri 'none'",
)

FastAPI, gramlot fastapi new, app.py; requirements.txt installs FastAPI with Uvicorn:

"""Serve the pages inside a FastAPI app: ``uvicorn app:app``."""
from pathlib import Path

from fastapi import FastAPI

from gramlot_py_server.fastapi import mount_pages

PAGES = Path(__file__).resolve().parent / "pages"

app = FastAPI()
mount_pages(
    app,
    PAGES,
    content_security_policy="script-src 'nonce-{nonce}'; object-src 'none'; base-uri 'none'",
)

Kajenn, gramlot kajenn new, config.py; the page opens at http://127.0.0.1:8000/pages/:

"""Kajenn site: ``kajenn serve config.py --port 8000``, pages under ``/pages/``."""
from pathlib import Path

from kajenn.config.templates import DefaultConfiguration

from gramlot_py_server.kajenn import Application

PAGES = Path(__file__).resolve().parent / "pages"


class Site(DefaultConfiguration):
    def applications_section(self, cfg):
        cfg.applications().application(
            code="pages",
            mount="pages",
            app_class=Application,
            pages=PAGES,
            content_security_policy=(
                "script-src 'nonce-{nonce}'; object-src 'none'; base-uri 'none'"
            ),
        ).request(body="raw")

The tests tests/<framework>/test_<framework>_project.py create each project with gramlot <framework> new and serve it, and tests/test_readme.py checks that this README shows the same files. A project that already exists, such as a Django site, needs no new: the guide of its framework shows how to add the pages to it.

Next steps

• Examples and learning sequence: the shared lessons, Python/JavaScript source and gallery guide.

• The guides on Read the Docs, sources in docs/ and the paired view in docs_llm/:

  • common: Introduction, Writing pages for these hosts, Troubleshooting, The gramlot command: new and gallery;
  • Uvicorn: Tutorial, Configuration, Deployment, Reference;
  • Django, Flask, FastAPI, Kajenn.

• The core: The Gramlot family, Classes, repository and server adapters (mount prefix, companions, CSP profiles), Server protocol (what every server answers), Writing pages, Data binding and controllers, Calling the server and Remote content and lazy Data.

Compatibility

Tests and contributing

python -m pip install -e ".[uvicorn,django,flask,fastapi,kajenn,gallery,test]"
python -m pytest -q                      # every adapter
python -m pytest -q tests/flask          # one adapter, with its extra only
python scripts/check_docs.py             # paired guides and Sphinx build

The browser checks need Node.js and Playwright; PLAYWRIGHT_ENTRY is the path of playwright/index.mjs:

node scripts/verify_browser.mjs "$(command -v python)" "$PLAYWRIGHT_ENTRY" chromium
node scripts/verify_gallery_browser.mjs "$(command -v python)" "$PLAYWRIGHT_ENTRY" chromium
python scripts/verify_install.py flask dist/gramlot_py_server-*.whl "$PLAYWRIGHT_ENTRY"

CI runs each adapter with its own extra against the released core and, as an informational job, every adapter against the core's main checkout; it runs the browser checks in Chromium and a clean install of each environment from the built wheel, and builds the documentation; coverage goes to Codecov with one flag per framework. See CONTRIBUTING.md and AGENTS.md; the internal notes are in docs/internal/.

Apache License 2.0. Copyright 2026 Softwell S.r.l. See LICENSE and NOTICE.

Hosted gallery updates

After a successful Publish release, the separate Update hosted galleries workflow updates both public galleries and their serverless ZIP. It can also be run manually on main to retry a failed deployment. See the deployment runbook for credentials, verification and rollback.