bazaar-contrib-server 0.3.0rc1__py3-none-any.whl

bazaar_contrib_server/__init__.py

@@ -0,0 +1,112 @@
+"""The server itself: the shell modules put their pages in, its registrations,
+the themes, and the two themes it comes with."""
+
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+lazy import asyncio
+lazy import tomllib
+lazy from collections.abc import AsyncIterator
+lazy from importlib.resources import files
+
+from bazaar_contrib_http import HTTP
+from bazaar_contrib_server_database import SERVER_DB, SERVER_SCHEMA
+from bazaar_contrib_server_migrations import SERVER_MIGRATIONS
+from bazaar_core import Context, Contrib
+lazy from starlette.exceptions import HTTPException
+lazy from starlette.requests import HTTPConnection
+
+from .contracts import (
+    SERVER,
+    THEME,
+    Account,
+    Login,
+    OverviewItem,
+    PermissionItem,
+    Server,
+    SettingsItem,
+    SidebarItem,
+    Theme,
+    Themes,
+    Tokens,
+)
+lazy from .i18n import LANGUAGES, Translator
+lazy from .pages import Pages
+lazy from .refs import Refs
+lazy from .schema import MODULE
+lazy from .shell import Shell
+
+__all__ = [
+    "LANGUAGES",
+    "SERVER",
+    "THEME",
+    "Account",
+    "Login",
+    "OverviewItem",
+    "Pages",
+    "PermissionItem",
+    "Refs",
+    "Server",
+    "SettingsItem",
+    "SidebarItem",
+    "Theme",
+    "Themes",
+    "Tokens",
+    "Translator",
+    "account",
+    "day",
+    "night",
+    "permitted",
+    "server",
+]
+
+
+def account(connection: HTTPConnection) -> Account:
+    """The account a request or a WebSocket behind the login is from; a
+    FastAPI dependency."""
+    return connection.state.account
+
+
+def permitted(point: str):
+    """A FastAPI dependency refusing accounts without the permission point."""
+
+    def check(connection: HTTPConnection) -> None:
+        if not account(connection).allows(point):
+            raise HTTPException(status_code=403)
+
+    return check
+
+
+@asynccontextmanager
+async def _server(ctx: Context) -> AsyncIterator[None]:
+    async with ctx.accept(SERVER_SCHEMA).register(MODULE):
+        shell = await Shell.open(ctx.accept(HTTP), ctx.accept(SERVER_DB))
+        async with shell.serving():
+            ctx.offer(SERVER, shell)
+            ctx.offer(THEME, shell.themes)
+            yield
+
+
+def _theme(name: str) -> Contrib:
+    """A theme plugin for the theme in resources/themes/<name>.toml."""
+
+    @asynccontextmanager
+    async def lifespan(ctx: Context) -> AsyncIterator[None]:
+        path = files(__name__) / "resources" / "themes" / f"{name}.toml"
+        theme = Theme.model_validate(
+            tomllib.loads(await asyncio.to_thread(path.read_text, encoding="utf-8"))
+        )
+        async with ctx.accept(THEME).register(theme):
+            yield
+
+    return Contrib(accepts=[THEME], lifespan=lifespan)
+
+
+server = Contrib(
+    accepts=[HTTP, SERVER_DB, SERVER_SCHEMA, SERVER_MIGRATIONS],
+    offers=[SERVER, THEME],
+    lifespan=_server,
+)
+# the night market and the morning market of the approved design
+night = _theme("night")
+day = _theme("day")

bazaar_contrib_server/clock.py

@@ -0,0 +1,40 @@
+"""The server's clock, and moments as the viewer reads them."""
+
+from __future__ import annotations
+
+lazy from datetime import datetime, tzinfo
+lazy from time import time_ns
+lazy from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+
+def now_ms() -> int:
+    return time_ns() // 1_000_000
+
+
+def zone(name: str | None) -> tzinfo | None:
+    """The viewer's zone by IANA name; nothing when there is none, so each
+    moment is read on the server's own clock, daylight time as it was then."""
+    if name:
+        try:
+            return ZoneInfo(name)
+        except ZoneInfoNotFoundError, ValueError:
+            pass
+    return None
+
+
+def clock_text(at_ms: int, tz: tzinfo | None) -> str:
+    """A moment on the viewer's clock: the time of day, with the date before
+    it when the day is not today's."""
+    today = datetime.now(tz).replace(hour=0, minute=0, second=0, microsecond=0)
+    form = "%H:%M:%S" if at_ms >= today.timestamp() * 1000 else "%Y-%m-%d %H:%M:%S"
+    return datetime.fromtimestamp(at_ms / 1000, tz).strftime(form)
+
+
+def day_text(at_ms: int, tz: tzinfo | None) -> str:
+    """The day a moment falls on, on the viewer's calendar."""
+    return datetime.fromtimestamp(at_ms / 1000, tz).strftime("%Y-%m-%d")
+
+
+def time_text(at_ms: int, tz: tzinfo | None) -> str:
+    """The time of day of a moment, whatever the day."""
+    return datetime.fromtimestamp(at_ms / 1000, tz).strftime("%H:%M:%S")

bazaar_contrib_server/contracts.py

@@ -0,0 +1,196 @@
+"""What modules, login modules and theme plugins hold the server to."""
+
+from __future__ import annotations
+
+from typing import Literal, Protocol
+lazy from collections.abc import Sequence
+lazy from contextlib import AbstractAsyncContextManager
+lazy from pathlib import Path
+
+from bazaar_core import ServiceKey
+from pydantic import BaseModel, ConfigDict, Field
+lazy from starlette.requests import HTTPConnection
+lazy from starlette.responses import Response
+lazy from starlette.types import ASGIApp
+
+lazy from .i18n import Translator
+lazy from .pages import Pages
+lazy from .refs import Refs
+
+# one segment of an address, and a name a stylesheet can select on
+NAME = r"^[a-z][a-z0-9-]*$"
+# the addresses the server and the modules behind them answer themselves
+RESERVED = frozenset({"ui", "api", "static", "login", "starlink"})
+
+
+class _Item(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+
+class SidebarItem(_Item):
+    """A link in the sidebar, for the accounts holding its permission point."""
+
+    text: str
+    # an SVG icon stroked in currentColor, as lucide's are
+    icon: str
+    path: str
+    permission: str | None = None
+    order: int = 0
+
+
+class OverviewItem(_Item):
+    """Content of the overview, loaded in an iframe."""
+
+    key: str = Field(pattern=NAME)
+    title: str
+    src: str
+    permission: str | None = None
+
+
+class SettingsItem(_Item):
+    """A part of the settings page, loaded in an iframe."""
+
+    key: str = Field(pattern=NAME)
+    title: str
+    src: str
+    permission: str | None = None
+    admin: bool = False
+
+
+class PermissionItem(_Item):
+    """A permission point, written module.action; it is also its text key."""
+
+    point: str = Field(pattern=r"^[a-z][a-z0-9-]*\.[a-z][a-z0-9-]*$")
+    description: str
+
+
+class Tokens(_Item):
+    """Every value a theme sets, named as in the approved tokens.css."""
+
+    bg: str
+    bg_glow: str
+    side_bg: str
+    surface: str
+    surface_2: str
+    raised: str
+    sunken: str
+    line: str
+    line_soft: str
+    line_strong: str
+    text: str
+    text_2: str
+    muted: str
+    faint: str
+    saffron: str
+    saffron_ink: str
+    saffron_soft: str
+    saffron_line: str
+    ember: str
+    jade: str
+    jade_soft: str
+    crimson: str
+    crimson_soft: str
+    indigo: str
+    indigo_soft: str
+    plum: str
+    plum_soft: str
+    shadow: str
+    codex: str
+
+
+class Theme(_Item):
+    """A look; its styles apply only while it is the page's theme."""
+
+    name: str = Field(pattern=NAME)
+    # what the theme is called, by language
+    labels: dict[str, str] = Field(min_length=1)
+    scheme: Literal["light", "dark"]
+    tokens: Tokens
+    styles: str = ""
+
+
+class Account(Protocol):
+    """Who a request is from, as the login module says."""
+
+    @property
+    def id(self) -> str: ...
+
+    @property
+    def name(self) -> str: ...
+
+    @property
+    def theme(self) -> str | None: ...
+
+    @property
+    def language(self) -> str | None: ...
+
+    @property
+    def admin(self) -> bool: ...
+
+    def allows(self, point: str) -> bool: ...
+
+
+class Login(Protocol):
+    """The module that says who a request is from; one at a time."""
+
+    @property
+    def app(self) -> ASGIApp:
+        """Served at /login to anyone; signing out is a POST to /login/logout."""
+        ...
+
+    async def account(self, connection: HTTPConnection) -> Account | Response:
+        """The account a request or a WebSocket is from, or the answer it
+        gets instead."""
+        ...
+
+
+class Themes(Protocol):
+    def register(self, theme: Theme) -> AbstractAsyncContextManager[None]:
+        """Offer the theme while open."""
+        ...
+
+
+class Server(Protocol):
+    """Where modules put their pages, links and permission points; each
+    registration holds while its context is open."""
+
+    @property
+    def refs(self) -> Refs: ...
+
+    @property
+    def permissions(self) -> Sequence[PermissionItem]: ...
+
+    def module(
+        self,
+        name: str,
+        *,
+        ui: ASGIApp | None = None,
+        api: ASGIApp | None = None,
+        static: Path | None = None,
+        locales: Path | None = None,
+    ) -> AbstractAsyncContextManager[None]:
+        """Serve the module's interface at /ui/<name> inside the shell at
+        /<name>, its API at /api/<name> and its files at /static/<name>; its
+        locales directory holds en.toml and zh-CN.toml."""
+        ...
+
+    def sidebar(self, item: SidebarItem) -> AbstractAsyncContextManager[None]: ...
+
+    def overview(self, item: OverviewItem) -> AbstractAsyncContextManager[None]: ...
+
+    def settings(self, item: SettingsItem) -> AbstractAsyncContextManager[None]: ...
+
+    def permission(self, item: PermissionItem) -> AbstractAsyncContextManager[None]: ...
+
+    def login(self, login: Login) -> AbstractAsyncContextManager[None]: ...
+
+    async def pages(self, module: str, package: str) -> Pages:
+        """Jinja pages on the server's base template, from the package's
+        templates directory."""
+        ...
+
+    def translator(self, connection: HTTPConnection) -> Translator: ...
+
+
+SERVER = ServiceKey[Server]("server")
+THEME = ServiceKey[Themes]("server.theme")

bazaar_contrib_server/i18n.py

@@ -0,0 +1,84 @@
+"""Every module's words, in the language of whoever is looking."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+lazy import tomllib
+lazy from collections.abc import Mapping
+lazy from pathlib import Path
+
+from jinja2 import Environment, StrictUndefined, Template
+
+ENGLISH = "en"
+SIMPLIFIED_CHINESE = "zh-CN"
+LANGUAGES = (ENGLISH, SIMPLIFIED_CHINESE)
+
+_environment = Environment(undefined=StrictUndefined, autoescape=False)
+
+
+def catalogs(directory: Path) -> dict[str, dict[str, Template]]:
+    """The languages a locales directory has, every entry a template."""
+    return {
+        language: {
+            key: _environment.from_string(source)
+            for key, source in tomllib.loads(path.read_text(encoding="utf-8")).items()
+        }
+        for language in LANGUAGES
+        if (path := directory / f"{language}.toml").is_file()
+    }
+
+
+def language(chosen: str | None, accept_language: str | None) -> str:
+    """The account's language, else the first one the browser asks for that
+    the pages speak, else English."""
+    if chosen in LANGUAGES:
+        return chosen
+    for part in (accept_language or "").split(","):
+        tag = part.split(";")[0].strip().lower()
+        if tag.startswith("zh"):
+            return SIMPLIFIED_CHINESE
+        if tag.startswith("en"):
+            return ENGLISH
+    return ENGLISH
+
+
+@dataclass(frozen=True, slots=True)
+class Translator:
+    language: str
+    _messages: Mapping[str, Template] = field(repr=False)
+
+    def text(self, key: str, arguments: Mapping[str, object] | None = None) -> str:
+        template = self._messages.get(key)
+        if template is None:
+            return key
+        return template.render(**(arguments or {}))
+
+    def has(self, key: str) -> bool:
+        return key in self._messages
+
+
+class Catalogs:
+    """The registered modules' catalogs, merged per language."""
+
+    def __init__(self) -> None:
+        self._modules: dict[str, dict[str, dict[str, Template]]] = {}
+        self._translators: dict[str, Translator] = {}
+
+    def add(self, module: str, languages: dict[str, dict[str, Template]]) -> None:
+        self._modules[module] = languages
+        self._translators.clear()
+
+    def remove(self, module: str) -> None:
+        del self._modules[module]
+        self._translators.clear()
+
+    def translator(self, language: str) -> Translator:
+        if language not in self._translators:
+            messages: dict[str, Template] = {}
+            for languages in self._modules.values():
+                # a module that speaks one language is read in it
+                messages |= languages.get(language) or next(
+                    iter(languages.values()), {}
+                )
+            self._translators[language] = Translator(language, messages)
+        return self._translators[language]

bazaar_contrib_server/markdown.py

@@ -0,0 +1,83 @@
+"""What was written, as it was meant to be read: Markdown, and code within
+it coloured by what it is."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping, Sequence
+from typing import Any
+
+from markdown_it import MarkdownIt
+from markdown_it.renderer import RendererHTML
+from markdown_it.token import Token
+from markdown_it.utils import EnvType, OptionsDict
+from markupsafe import Markup
+from pygments import highlight
+from pygments.formatters import HtmlFormatter
+from pygments.lexers import get_lexer_by_name
+from pygments.lexers.special import TextLexer
+from pygments.util import ClassNotFound
+
+# tokens by class only, prefixed so they meet none of the page's own; the
+# colours are the page's, in its stylesheet
+_FORMATTER = HtmlFormatter(nowrap=True, classprefix="tok-")
+
+
+def _fence(
+    renderer: Any,
+    tokens: Sequence[Token],
+    index: int,
+    options: Mapping[str, Any],
+    env: Mapping[str, Any],
+) -> str:
+    del renderer, options
+    token = tokens[index]
+    language = token.info.strip().split(" ", 1)[0] if token.info else ""
+    try:
+        lexer = get_lexer_by_name(language) if language else TextLexer()
+    except ClassNotFound:
+        lexer = TextLexer()
+    return env["code"](Markup(highlight(token.content, lexer, _FORMATTER))) + "\n"
+
+
+def _image(
+    renderer: Any,
+    tokens: Sequence[Token],
+    index: int,
+    options: Mapping[str, Any],
+    env: Mapping[str, Any],
+) -> str:
+    token = tokens[index]
+    return env["image"](
+        src=token.attrGet("src") or "",
+        alt=renderer.renderInlineAsText(token.children or [], options, env),
+    )
+
+
+class _ContentRenderer(RendererHTML):
+    def renderInline(
+        self, tokens: Sequence[Token], options: OptionsDict, env: EnvType
+    ) -> str:
+        # Prose stays outside Alpine; the trusted code-block copy control is
+        # a separate component, beside its own ignored code content.
+        return (
+            "<span x-ignore>" + super().renderInline(tokens, options, env) + "</span>"
+        )
+
+
+# html off: what the agent wrote is text, however it looks; a link is only a
+# link on a scheme markdown-it lets through
+_MARKDOWN = MarkdownIt(
+    "commonmark", {"html": False}, renderer_cls=_ContentRenderer
+).enable(["table", "strikethrough"])
+_MARKDOWN.add_render_rule("fence", _fence)
+_MARKDOWN.add_render_rule("image", _image)
+
+
+def render(
+    text: str, *, code: Callable[[Markup], str], image: Callable[..., str]
+) -> Markup:
+    """The text as HTML; each code block drawn by `code`, given its
+    highlighted content, and each image by `image`, given its `src` and
+    `alt`, so both are the page's own."""
+
+    return Markup(_MARKDOWN.render(text, {"code": code, "image": image}))