xtr-cli 4.0.2__py3-none-any.whl

xtr_cli/templates/webapp/files/pyproject.toml.tmpl

@@ -0,0 +1,60 @@
+[project]
+name = "${name}"
+version = "0.1.0"
+description = "A web application on the xtr packages."
+readme = "README.md"
+requires-python = ">=${python}"
+dependencies = []
+
+[project.scripts]
+${name} = "${app}.__main__:main"
+${name}-web = "${app}.web.__main__:main"
+
+[dependency-groups]
+dev = []
+
+[build-system]
+requires = ["uv_build>=0.9.18,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.basedpyright]
+typeCheckingMode = "all"
+pythonVersion = "${python}"
+include = ["src", "tests"]
+exclude = ["**/__pycache__", "**/.venv", "var"]
+reportUnusedCallResult = "warning"
+
+[tool.ruff]
+target-version = "py3${minor}"
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    # Formatter conflicts.
+    "COM812",
+    "ISC001",
+    # Mutually exclusive docstring conventions; keep the modern one.
+    "D203",
+    "D213",
+    "CPY001",
+    # The container and the console read annotations at runtime: an import used only in
+    # an annotation is still needed at runtime, so none may move under TYPE_CHECKING.
+    "TC001",
+    "TC002",
+    "TC003",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["S101", "D"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ty.src]
+include = ["src", "tests"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = ["-ra", "--strict-config", "--strict-markers"]

xtr_cli/templates/webapp/files/python-version.tmpl

@@ -0,0 +1 @@
+${python}

xtr_cli/templates/webapp/files/tests/test_kernel.py.tmpl

@@ -0,0 +1,9 @@
+"""The application's kernel builds, with every listed bundle."""
+
+from __future__ import annotations
+
+from ${app}.kernel import kernel
+
+
+def test_the_kernel_builds_in_the_test_environment() -> None:
+    _ = kernel.with_env("test").build()

xtr_cli/templates/webapp/files/tests/test_web.py.tmpl

@@ -0,0 +1,28 @@
+"""The web application answers, served from its kernel."""
+
+from __future__ import annotations
+
+from http import HTTPStatus
+
+import httpx
+import pytest
+
+from ${app}.web.app import app
+
+pytestmark = pytest.mark.anyio
+
+
+@pytest.fixture
+def anyio_backend() -> str:
+    return "asyncio"
+
+
+async def test_the_home_page_answers() -> None:
+    # The lifespan is what builds and boots the kernel the requests are served from.
+    async with app.router.lifespan_context(app):
+        transport = httpx.ASGITransport(app=app)
+        async with httpx.AsyncClient(transport=transport, base_url="http://test") as client:
+            response = await client.get("/")
+
+    assert response.status_code == HTTPStatus.OK
+    assert response.json() == {"status": "ok"}

xtr_cli/templates/webapp/template.toml

@@ -0,0 +1,45 @@
+# A web application: the cli template, plus a FastAPI application served from the
+# same kernel through the http-kernel request lifecycle.
+summary = "A web application: FastAPI served from the kernel, with the console beside it."
+
+[dependencies]
+packages = [
+    "xtr-dependency-injection[fastapi]",
+    "xtr-console[di]",
+    "xtr-dotenv[di,console]",
+    "xtr-logging[di]",
+    "xtr-http-kernel[logging,console]",
+    "fastapi",
+    "uvicorn",
+]
+dev = ["xtr-recipes", "pytest", "httpx", "ruff", "basedpyright", "ty"]
+
+# Only what no package's recipe writes. The bundle list, .env and the ignore
+# blocks are the recipes' to write, once the packages are installed.
+[files]
+"pyproject.toml" = "files/pyproject.toml.tmpl"
+".python-version" = "files/python-version.tmpl"
+".gitignore" = "files/gitignore.tmpl"
+"README.md" = "files/README.md.tmpl"
+"src/${app}/__init__.py" = "files/app/__init__.py.tmpl"
+"src/${app}/__main__.py" = "files/app/__main__.py.tmpl"
+"src/${app}/kernel.py" = "files/app/kernel.py.tmpl"
+"src/${app}/py.typed" = "files/app/py.typed.tmpl"
+"src/${app}/command/__init__.py" = "files/app/command/__init__.py.tmpl"
+"src/${app}/command/hello_command.py" = "files/app/command/hello_command.py.tmpl"
+"src/${app}/config/__init__.py" = "files/app/config/__init__.py.tmpl"
+"src/${app}/config/http_kernel.py" = "files/app/config/http_kernel.py.tmpl"
+"src/${app}/web/__init__.py" = "files/app/web/__init__.py.tmpl"
+"src/${app}/web/__main__.py" = "files/app/web/__main__.py.tmpl"
+"src/${app}/web/app.py" = "files/app/web/app.py.tmpl"
+"src/${app}/web/routes.py" = "files/app/web/routes.py.tmpl"
+"tests/__init__.py" = "files/tests/__init__.py.tmpl"
+"tests/test_kernel.py" = "files/tests/test_kernel.py.tmpl"
+"tests/test_web.py" = "files/tests/test_web.py.tmpl"
+
+[notes]
+next = [
+    "uv run ${name}-web",
+    "uv run ${name} debug:router",
+    "uv run pytest",
+]

xtr_cli/web_entry_point.py

@@ -0,0 +1,76 @@
+"""WebEntryPoint: what serves an application, and the command that starts it."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Final, Literal, final
+
+__all__ = ["DEFAULT_HOST", "DEFAULT_PORT", "WebEntryPoint"]
+
+DEFAULT_HOST: Final = "127.0.0.1"
+"""Where an application found as an ASGI object is served when no host is given."""
+
+DEFAULT_PORT: Final = 8000
+"""The port an application found as an ASGI object is served on when none is given."""
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class WebEntryPoint:
+    """One way to serve an application: a console script, or an ASGI object.
+
+    A **script** is the application's own web entry point, run as it is —
+    whatever it does before serving, loading its ``.env`` files among it, still
+    happens. It is told the host, the port and whether to reload through
+    ``WEB_HOST``, ``WEB_PORT`` and ``WEB_RELOAD``, the variables the ``webapp``
+    template's entry point reads; a script that reads none of them serves where
+    it always does.
+
+    An **ASGI object** — a module-level ``FastAPI()``, ``Starlette()`` or
+    ``Litestar()`` — is handed to ``uvicorn`` directly, which then has to be
+    installed in the project. Nothing runs before it is imported, so the
+    application's own environment loading does not either.
+
+    Attributes:
+        kind: ``"script"`` or ``"asgi"``.
+        target: The script's name, or the ASGI object as ``module:attribute``.
+    """
+
+    kind: Literal["script", "asgi"]
+    target: str
+
+    @property
+    def label(self) -> str:
+        """The entry point as ``--entrypoint`` takes it."""
+        return self.target
+
+    def command(
+        self, host: str | None, port: int | None, *, reload: bool
+    ) -> tuple[tuple[str, ...], dict[str, str]]:
+        """Return the command serving this entry point, and the variables set for it.
+
+        Args:
+            host: Where to listen, or ``None`` for the entry point's default.
+            port: The port to listen on, or ``None`` for the entry point's default.
+            reload: Whether to restart the server when a source file changes.
+        """
+        if self.kind == "script":
+            environment: dict[str, str] = {}
+            if host is not None:
+                environment["WEB_HOST"] = host
+            if port is not None:
+                environment["WEB_PORT"] = str(port)
+            if reload:
+                environment["WEB_RELOAD"] = "1"
+            return ("uv", "run", self.target), environment
+        argv = (
+            "uv",
+            "run",
+            "uvicorn",
+            self.target,
+            "--host",
+            host if host is not None else DEFAULT_HOST,
+            "--port",
+            str(port if port is not None else DEFAULT_PORT),
+        )
+        return ((*argv, "--reload") if reload else argv), {}

xtr_cli/web_entry_point_finder.py

@@ -0,0 +1,194 @@
+"""WebEntryPointFinder: the project around a directory, and what in it serves the web."""
+
+from __future__ import annotations
+
+import ast
+import tomllib
+from pathlib import Path
+from typing import TYPE_CHECKING, final
+
+from .exception import ProjectNotFoundError, WebEntryPointNotFoundError
+from .web_entry_point import WebEntryPoint
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+__all__ = ["WebEntryPointFinder"]
+
+_PYPROJECT = "pyproject.toml"
+# A script importing one of these starts a server itself.
+_SERVERS = frozenset({"uvicorn", "hypercorn", "granian"})
+# A script named like this is the web entry point by convention.
+_WEB_SUFFIXES = ("-web", "_web", "-server", "_server")
+# The classes whose module-level instance is an ASGI application.
+_ASGI_CLASSES = frozenset({"FastAPI", "Starlette", "Litestar"})
+# Directories that hold no application code, at whatever depth they appear.
+_SKIPPED = frozenset(
+    {"__pycache__", "node_modules", "build", "dist", "tests", "test", "migrations", "var"}
+)
+
+
+@final
+class WebEntryPointFinder:
+    """Finds what serves a project, reading its files and running nothing.
+
+    A web console script comes first: it is the application's own way of
+    serving, environment loading included. A script counts when its module
+    imports a server — ``uvicorn``, ``hypercorn`` or ``granian`` — or its name
+    ends in ``-web`` or ``-server``. Only a project with no such script is
+    searched for a module-level ASGI object instead. Every module is read with
+    :mod:`ast`, never imported.
+    """
+
+    __slots__ = ()
+
+    @staticmethod
+    def project_dir(start: Path | None = None) -> Path:
+        """Return the nearest directory at or above ``start`` holding a ``pyproject.toml``.
+
+        Raises:
+            ProjectNotFoundError: When there is none.
+        """
+        origin = (start if start is not None else Path.cwd()).expanduser().resolve()
+        for directory in (origin, *origin.parents):
+            if (directory / _PYPROJECT).is_file():
+                return directory
+        raise ProjectNotFoundError(origin)
+
+    def find(self, project_dir: Path) -> tuple[WebEntryPoint, ...]:
+        """Return every web entry point of the project, the scripts first and alone if any."""
+        scripts = tuple(
+            WebEntryPoint("script", name)
+            for name, target in _scripts(project_dir).items()
+            if name.endswith(_WEB_SUFFIXES) or _imports_a_server(project_dir, target)
+        )
+        if scripts:
+            return scripts
+        return tuple(WebEntryPoint("asgi", target) for target in _asgi_objects(project_dir))
+
+    @staticmethod
+    def resolve(project_dir: Path, given: str) -> WebEntryPoint:
+        """Return the entry point ``--entrypoint`` names: a script, or ``module:attribute``.
+
+        Raises:
+            WebEntryPointNotFoundError: When ``given`` is neither one of the
+                project's scripts nor a ``module:attribute``.
+        """
+        module, separator, attribute = given.partition(":")
+        if separator:
+            if all(part.isidentifier() for part in module.split(".")) and attribute.isidentifier():
+                return WebEntryPoint("asgi", given)
+            raise WebEntryPointNotFoundError(project_dir, f"{given!r} is not a module:attribute")
+        if given in _scripts(project_dir):
+            return WebEntryPoint("script", given)
+        raise WebEntryPointNotFoundError(
+            project_dir,
+            f"no script {given!r} in [project.scripts]; give a script name or a module:attribute",
+        )
+
+
+def _scripts(project_dir: Path) -> dict[str, str]:
+    """Return ``[project.scripts]``, each name mapped to its ``module:function``."""
+    try:
+        with (project_dir / _PYPROJECT).open("rb") as handle:
+            data: dict[str, object] = tomllib.load(handle)
+    except (OSError, tomllib.TOMLDecodeError):
+        # A manifest that cannot be read has no scripts to offer; the ASGI search still runs.
+        return {}
+    project = data.get("project")
+    scripts = project.get("scripts") if isinstance(project, dict) else None
+    if not isinstance(scripts, dict):
+        return {}
+    return {str(name): str(target) for name, target in scripts.items() if isinstance(target, str)}
+
+
+def _roots(project_dir: Path) -> tuple[Path, ...]:
+    """Return where the project's modules live: ``src/`` when present, and the project itself."""
+    source = project_dir / "src"
+    return (source, project_dir) if source.is_dir() else (project_dir,)
+
+
+def _module_file(project_dir: Path, module: str) -> Path | None:
+    """Return the file defining ``module``, looked for where the project keeps its code."""
+    parts = module.split(".")
+    for root in _roots(project_dir):
+        for candidate in (
+            root.joinpath(*parts).with_suffix(".py"),
+            root.joinpath(*parts, "__init__.py"),
+        ):
+            if candidate.is_file():
+                return candidate
+    return None
+
+
+def _parse(file: Path) -> ast.Module | None:
+    """Parse ``file``, or return ``None`` for one that cannot be read as Python."""
+    try:
+        return ast.parse(file.read_text(encoding="utf-8"), str(file))
+    except (OSError, UnicodeDecodeError, SyntaxError, ValueError):
+        # Not this tool's to report: a broken module is simply not an entry point.
+        return None
+
+
+def _imports_a_server(project_dir: Path, target: str) -> bool:
+    """Report whether the module a script runs imports a server."""
+    file = _module_file(project_dir, target.partition(":")[0].strip())
+    tree = _parse(file) if file is not None else None
+    if tree is None:
+        return False
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            names = [alias.name for alias in node.names]
+        elif isinstance(node, ast.ImportFrom) and node.level == 0 and node.module:
+            names = [node.module]
+        else:
+            continue
+        if any(name.partition(".")[0] in _SERVERS for name in names):
+            return True
+    return False
+
+
+def _asgi_objects(project_dir: Path) -> list[str]:
+    """Return every module-level ASGI application, as ``module:attribute``, sorted."""
+    found: set[str] = set()
+    for root in _roots(project_dir):
+        for file in _modules(root, project_dir):
+            parts = list(file.relative_to(root).with_suffix("").parts)
+            if parts[-1] == "__init__":
+                parts = parts[:-1]
+            if not parts or parts[-1] == "__main__" or not all(p.isidentifier() for p in parts):
+                continue
+            tree = _parse(file)
+            if tree is not None:
+                found.update(f"{'.'.join(parts)}:{name}" for name in _asgi_names(tree))
+    return sorted(found)
+
+
+def _modules(root: Path, project_dir: Path) -> Iterator[Path]:
+    """Yield the Python files under ``root``, leaving out tooling, tests and other roots."""
+    for path in sorted(root.iterdir()):
+        if path.name.startswith(".") or path.name in _SKIPPED:
+            continue
+        if path.is_dir():
+            if path == project_dir / "src" or (path / "pyvenv.cfg").exists():
+                continue
+            yield from _modules(path, project_dir)
+        elif path.suffix == ".py":
+            yield path
+
+
+def _asgi_names(tree: ast.Module) -> Iterator[str]:
+    """Yield the module-level names bound to a new ASGI application."""
+    for node in tree.body:
+        if isinstance(node, ast.Assign) and len(node.targets) == 1:
+            target, value = node.targets[0], node.value
+        elif isinstance(node, ast.AnnAssign) and node.value is not None:
+            target, value = node.target, node.value
+        else:
+            continue
+        if not isinstance(target, ast.Name) or not isinstance(value, ast.Call):
+            continue
+        called = value.func
+        name = called.id if isinstance(called, ast.Name) else getattr(called, "attr", None)
+        if name in _ASGI_CLASSES:
+            yield target.id