xtr-maker 6.0.0__py3-none-any.whl

xtr_maker/.agents/skills/xtr-maker/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: xtr-maker
+description: Generate application code for the xtr libraries with the make:* console commands of xtr-maker - messages and handlers, schedule providers, webhook parsers and consumers, entities and repositories, console commands, event listeners and subscribers, and migration revisions. Use when scaffolding any of those by hand, when asking which folder a generated class belongs in, when scripting a maker non-interactively with -n, when a maker is missing from `list make`, when a run is refused with TargetExistsError or InvalidClassNameError, when deciding what make:entity's --field and --relation accept, or when adding MakerBundle to an application on xtr-dependency-injection.
+---
+
+# xtr-maker
+
+Dev-only console commands that write code: a class in the folder named after what it is, its
+imports, its decorator, and whatever belongs beside it. Nothing is overwritten, nothing is
+written outside the project, and no secret is ever generated.
+
+## Quick reference
+
+| Command | Writes | Needs this bundle active |
+| --- | --- | --- |
+| `make:message [name] [--transport T] [--wire-name N]` | `message/<snake>.py`, `message_handler/<snake>_handler.py` | `messenger` |
+| `make:schedule [name] [--schedule S] [--message M] [--stateful] [--lock]` | `scheduler/<snake>_schedule.py` | `scheduler` |
+| `make:webhook [name] [--matcher M]...` | `webhook/<snake>_request_parser.py`, `remote_event/<snake>_webhook_consumer.py`, `config/packages/webhook_<snake>.py` | `webhook` |
+| `make:entity [name] [--field F]... [--relation R]... [--id uuid\|uuid7\|bigint] [--no-audit]` | `entity/<snake>.py`, `repository/<snake>_repository.py` | `orm` |
+| `make:command [name] [--argument A]... [--option O]...` | `command/<snake>_command.py` | — |
+| `make:listener [name] [event]` | `event_listener/<snake>_listener.py` or `event_subscriber/<snake>_subscriber.py` | `event_dispatcher` |
+| `make:migration [--message M] [--connection C]` | a revision in the connection's migrations directory | `orm` |
+
+- Anything left off the command line is asked; `-n` asks nothing and takes the defaults, but the
+  name always has to be given.
+- A name may carry a subpackage: `ordering.PlaceOrder` lands in `message/ordering/place_order.py`.
+- A run renders every file before it writes any, so a refusal leaves the working tree untouched.
+- `list make` shows what the application has. A maker whose library's bundle is not active is not
+  registered.
+
+## A message and its handler
+
+```sh
+uv run app make:message PlaceOrder --transport async -n
+```
+
+Writes a frozen slotted dataclass under `@as_message(name="app.place_order.v1",
+transport="async")` and a handler class whose `async def __call__(self, message)` takes it. The
+transport is one of `MessageBusConfig.transports`; the wire name defaults to
+`<package>.<snake>.v1` and is pinned, so moving the class later changes nothing on the wire.
+
+## A schedule
+
+```sh
+uv run app make:schedule ReportSchedule --schedule reports --message RestockCheck -n
+```
+
+Writes an `@as_schedule("reports")` provider sending `RestockCheck()` every hour. `--stateful`
+needs the `cache` bundle active, `--lock` the `lock` bundle. A schedule another declared provider
+provides is refused. Then: `messenger:consume scheduler_reports`.
+
+## A webhook
+
+```sh
+uv run app make:webhook stripe --matcher Method --matcher IsJson -n
+```
+
+Writes the parser, the consumer and `config/packages/webhook_stripe.py` — a `@configure`
+transform adding `RouteConfig(parser=..., secret=env("STRIPE_WEBHOOK_SECRET"))`. Matchers are
+`Attributes`, `Callable`, `Header`, `Host`, `Ips`, `IsJson`, `Method`, `Path`, `Port`,
+`QueryParameter`, `Scheme`; several are chained. Set `STRIPE_WEBHOOK_SECRET` in `.env.local`
+yourself, and make sure `config/routes/webhook.py` exposes `resources["webhook"]`.
+
+## An entity
+
+```sh
+uv run app make:entity Book \
+  --field title:string:120 --field published_at:datetime? \
+  --relation author:many_to_one:Author,inverse=books -n
+```
+
+New: the entity on `UUIDAuditBase` (`--id uuid7|bigint`, `--no-audit` pick another base) in the
+plural of its name, plus its repository. Existing: only the new properties are added, every other
+line byte-identical, and no repository — `--id` and `--no-audit` are then refused. Field types:
+`string`, `text`, `integer`, `big_integer`, `small_integer`, `boolean`, `float`, `decimal`,
+`date`, `datetime`, `time`, `json`, `uuid`, `enum:<dotted class>`, `binary`; `?` makes a column
+nullable. Relation kinds: `many_to_one`, `one_to_many`, `many_to_many`, `one_to_one`;
+`inverse=none` adds nothing to the other entity. Then run `make:migration`.
+
+## A console command
+
+```sh
+uv run app make:command app:send-report --argument recipient --option dry-run -n
+```
+
+`app:send-report` becomes `SendReportCommand`. Argument types are `str`, `int`, `float`, `list`
+and a dotted enum class; options add `bool`, which is their default. A list argument must be last,
+a required argument may not follow an optional one, and `io` is reserved.
+
+## A listener or a subscriber
+
+```sh
+uv run app make:listener WorkerStatsSubscriber WorkerStartedEvent -n
+```
+
+A name ending in `Subscriber` writes an `EventSubscriberInterface` with
+`get_subscribed_events`; one ending in `Listener` writes a class whose `on_<event>` method carries
+`@as_event_listener`. The event is a class name, `module:Class` or a dotted path. With `-n` it has
+to resolve to a class: a plain dispatch name needs the confirmation question, so it is refused.
+
+## A migration
+
+```sh
+uv run app make:migration --message books -n
+```
+
+Compares the connection's database with its table definitions and lets its migrator write the
+revision, as `orm:migrations:diff` does. Every revision must be applied first, or the run fails
+with `Run orm:migrations:migrate -n first.` Nothing differing writes nothing and still succeeds.
+
+## Testing
+
+- Generated code is ordinary application code: test it the way the application tests the rest.
+  Nothing of xtr-maker is imported at runtime by what it writes.
+- To script a maker inside a test or a setup script, pass `-n` and every value as an option: with
+  no terminal nothing is asked, so the run never blocks.
+- Templates are rendered and then parsed, so a template that produces broken Python fails loudly
+  with `GeneratedSourceError` rather than writing a file.
+- Run the project's own gate over what was written; it is formatted (split statements keep a
+  trailing comma, so any line length from 88 up accepts them) with sorted imports, so it passes
+  unchanged. It assumes `TC001`/`TC002`/`TC003` are off: command parameters, constructor
+  parameters and entity columns are annotations read at runtime. A two-way relation's entities
+  carry `# pyright: reportImportCycles=false` above their `TYPE_CHECKING` imports of each other.
+
+## Use in an application
+
+1. **Install** — `uv run xtr-recipes recipes:add --dev xtr-maker` (or `uv add --dev xtr-maker`,
+   then `uv run xtr-recipes recipes:sync`). Add extras for libraries the application has not got
+   yet: `"xtr-maker[messenger,scheduler,webhook,orm,event-dispatcher]"`.
+2. **Recipe** — the recipe shipped here does step 3 and nothing else; it lists the bundle for
+   `dev`.
+3. **Activate** — `from xtr_maker.bundle import MakerBundle` at the top of
+   `<app>/config/bundles.py`, and `MakerBundle: {"dev": True}` in `BUNDLES`, which the recipe
+   writes. Production without the development dependencies still starts: the kernel stands in for
+   the bundle there, which is not active, and never needs its package.
+4. **Brings along** — the console bundle. The messenger, scheduler, webhook, orm and event
+   dispatcher bundles are read, never required: each decides which makers exist.
+5. **Configure** — nothing to configure: the code goes into `kernel.package`, found where the
+   import system loads it, and classes are `@final`. To change either, write the settings into
+   the `dev` environment folder — production does not install this package, and only a `dev`
+   build imports that folder:
+
+   ```python
+   # <app>/config/packages/dev/maker.py (beside an empty __init__.py)
+   from xtr_dependency_injection import configure
+   from xtr_maker.bundle import MakerConfig
+
+
+   @configure
+   def maker() -> MakerConfig:
+       return MakerConfig(final_classes=False)
+   ```
+
+6. **Environment** — nothing. A maker that needs a secret prints the variable to set.
+7. **Ignore** — nothing: what the makers write is code to commit.
+8. **Remove** — `uv run xtr-recipes recipes:remove xtr-maker`: `uv remove --dev xtr-maker`, then a
+   sync that drops the `BUNDLES` entry. Delete `<app>/config/packages/dev/maker.py` if you wrote
+   one. The generated code stays yours.
+9. **Check** — `debug:bundles` lists `maker` as active in `dev`; `list make` shows the makers.
+
+## Errors
+
+Every one derives from `MakerError`, in `xtr_maker.exception`:
+
+| Error | Raised when |
+| --- | --- |
+| `AppPackageNotFoundError` | The import system finds no package of that name; the message names `MakerConfig.root_package` |
+| `GeneratedSourceError` | A template rendered Python that does not parse; it names the template |
+| `InvalidArgumentError` | An argument, option or answer cannot be used — also a `ValueError` |
+| `InvalidClassNameError` | What was typed is no identifier, is a keyword, or would hide a builtin |
+| `TargetExistsError` | The file exists, or another file of the same run claimed it — also a `FileExistsError` |
+| `UnsafePathError` | A path leaves the project directory, or is a symbolic link |
+
+A maker reports them and returns an exit code rather than a traceback: `ExitCode.INVALID` for
+anything refused before the files are rendered, `ExitCode.FAILURE` for a target that exists or a
+revision that could not be written, `ExitCode.SUCCESS` otherwise — nothing to write included.
+
+## Do not
+
+- Do not install it as a runtime dependency, and do not list `MakerBundle` for `all`: the makers
+  belong in `dev`.
+- Do not put a `MakerConfig` in a module directly under `<app>/config/packages/`: every
+  environment imports those, and production, which does not install `xtr-maker`, fails to start.
+  Use `<app>/config/packages/dev/`.
+- Do not expect a maker to overwrite a file, or to edit configuration. `make:webhook` adds a
+  transform module; `make:entity` is the only maker that writes an existing file, and only to add
+  properties to it.
+- Do not wait for a maker to generate a secret or run a migration: it prints the step.
+- Do not hand-place a generated class elsewhere and expect the next maker to find it — the
+  folders in the table above are where the makers look.
+- Do not run a maker in `-n` mode and leave the name off; it is the one thing never defaulted.
+- Do not run `make:migration` on a database behind its revisions; apply them first.

xtr_maker/__init__.py

@@ -0,0 +1,60 @@
+"""Console commands that write application code for the xtr libraries.
+
+Every maker writes through the same pieces, usable on their own:
+
+* :class:`~xtr_maker.class_name.ClassName` — what a person typed, as the class,
+  module and file under the folder for its kind.
+* :class:`~xtr_maker.name_converter.NameConverter` — one name as a class, a
+  module, a console name or a table.
+* :class:`~xtr_maker.import_collector.ImportCollector` — the imports a module
+  needs, grouped and sorted.
+* :class:`~xtr_maker.template_renderer.TemplateRenderer` — a template rendered,
+  and refused when its Python does not parse.
+* :class:`~xtr_maker.file_manager.FileManager` — the application package on
+  disk, and writes kept inside the project.
+* :class:`~xtr_maker.generator.Generator` — the files of one run, queued, then
+  written together.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .class_name import ClassName
+from .exception import (
+    AppPackageNotFoundError,
+    GeneratedSourceError,
+    InvalidArgumentError,
+    InvalidClassNameError,
+    MakerError,
+    TargetExistsError,
+    UnsafePathError,
+)
+from .file_manager import FileManager
+from .generator import Generator
+from .import_collector import ImportCollector
+from .name_converter import NameConverter
+from .template_renderer import TemplateRenderer
+
+try:
+    __version__ = version("xtr-maker")
+except PackageNotFoundError:  # pragma: no cover
+    # Running from a source tree with no installed metadata to read.
+    __version__ = "0+unknown"
+
+__all__ = [
+    "AppPackageNotFoundError",
+    "ClassName",
+    "FileManager",
+    "GeneratedSourceError",
+    "Generator",
+    "ImportCollector",
+    "InvalidArgumentError",
+    "InvalidClassNameError",
+    "MakerError",
+    "NameConverter",
+    "TargetExistsError",
+    "TemplateRenderer",
+    "UnsafePathError",
+    "__version__",
+]

xtr_maker/bundle/__init__.py

@@ -0,0 +1,8 @@
+"""The xtr-dependency-injection bundle for xtr-maker."""
+
+from __future__ import annotations
+
+from .maker_bundle import MakerBundle
+from .maker_config import MakerConfig
+
+__all__ = ["MakerBundle", "MakerConfig"]

xtr_maker/bundle/maker_bundle.py

@@ -0,0 +1,112 @@
+"""The xtr-maker bundle: the generator the ``make:*`` commands share, and the commands.
+
+Each maker writes code for one library, so its command is registered only when
+that library's bundle is active: an application never sees a maker for a
+library it does not use. Those bundles are not required from here: making code
+for a library is no reason to switch its bundle on, so the maker only reads
+which bundles the application activated.
+
+Nothing touches the disk until a maker runs: the application package is
+looked for the first time a maker needs it.
+"""
+
+from __future__ import annotations
+
+from typing import Final, final
+
+from typing_extensions import override
+from xtr_console.bundle import ConsoleBundle
+from xtr_dependency_injection import (
+    Bundle,
+    ContainerBuilder,
+    # Imported at runtime: the container reads the factory annotations below.
+    KernelInterface,
+    ServiceConfigurator,
+    as_bundle,
+    bundle_active,
+    required_bundle,
+)
+
+from xtr_maker.file_manager import FileManager
+from xtr_maker.generator import Generator
+from xtr_maker.template_renderer import TemplateRenderer
+
+from .maker_config import MakerConfig
+
+__all__ = ["MakerBundle"]
+
+_MAKERS: Final[tuple[tuple[str, str | None], ...]] = (
+    ("xtr_maker.command.make_message_command", "messenger"),
+    ("xtr_maker.command.make_schedule_command", "scheduler"),
+    ("xtr_maker.command.make_webhook_command", "webhook"),
+    ("xtr_maker.command.make_entity_command", "orm"),
+    ("xtr_maker.command.make_command_command", None),
+    ("xtr_maker.command.make_listener_command", "event_dispatcher"),
+    ("xtr_maker.command.make_migration_command", "orm"),
+)
+"""Each maker's command module, and the bundle that must be active for it (``None``: none)."""
+
+
+@final
+@required_bundle(ConsoleBundle)
+@as_bundle("maker", config=MakerConfig)
+class MakerBundle(Bundle[MakerConfig]):
+    """Registers the generator, and the makers whose library's bundle is active."""
+
+    @override
+    def load_extension(
+        self,
+        config: MakerConfig,
+        services: ServiceConfigurator,
+        builder: ContainerBuilder,
+    ) -> None:
+        """Register the generator's services, then the command module of each maker in reach.
+
+        The generator is scoped: a maker run is one unit of work, which queues
+        its own files, and a run that fails leaves nothing queued for the next.
+        """
+        del config
+        _ = services.set(_template_renderer)
+        _ = services.set(_file_manager)
+        _ = services.set(_generator, lifetime="scoped")
+        if bundle_active(builder, "webhook"):
+            _set_routed_webhook_types(builder)
+        for module, peer in _MAKERS:
+            if peer is None or bundle_active(builder, peer):
+                services.load(module)
+
+
+def _set_routed_webhook_types(builder: ContainerBuilder) -> None:
+    """Give ``make:webhook`` the types the webhook configuration routes, read as it is built.
+
+    Read here rather than injected: the configuration a service is given has
+    every secret resolved, so an application whose secrets are not set yet
+    could not make its next webhook.
+    """
+    # Imported only now: xtr-webhook is optional, and only an active webhook bundle
+    # gets the maker's module loaded.
+    from xtr_webhook.bundle import WebhookConfig  # noqa: PLC0415 — optional, see above.
+
+    from xtr_maker.command.make_webhook_command import (  # noqa: PLC0415 — see above.
+        ROUTED_TYPES_PARAMETER,
+    )
+
+    config = builder.get_extension_config(WebhookConfig)
+    builder.set_parameter(ROUTED_TYPES_PARAMETER, sorted(config.routing))
+
+
+def _template_renderer() -> TemplateRenderer:
+    """Render the templates this package ships."""
+    return TemplateRenderer()
+
+
+def _file_manager(kernel: KernelInterface, config: MakerConfig) -> FileManager:
+    """Write into the configured package, else the kernel's own."""
+    return FileManager(kernel.project_dir, config.root_package or kernel.package)
+
+
+def _generator(
+    file_manager: FileManager, template_renderer: TemplateRenderer, config: MakerConfig
+) -> Generator:
+    """Build a generator with an empty queue, marking classes ``@final`` as configured."""
+    return Generator(file_manager, template_renderer, final_classes=config.final_classes)

xtr_maker/bundle/maker_config.py

@@ -0,0 +1,36 @@
+"""Configuration for :class:`~xtr_maker.bundle.maker_bundle.MakerBundle`."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from xtr_maker.exception.invalid_argument_error import InvalidArgumentError
+
+__all__ = ["MakerConfig"]
+
+
+@dataclass(frozen=True, slots=True)
+class MakerConfig:
+    """Where the makers write, and how the classes they write are declared.
+
+    Attributes:
+        root_package: The dotted application package the makers write into.
+            ``None`` takes the kernel's package, ``kernel.package``; set it
+            only to write into another one.
+        final_classes: Whether generated classes are marked ``@final``.
+
+    Raises:
+        InvalidArgumentError: When ``root_package`` is not a dotted Python
+            identifier.
+    """
+
+    root_package: str | None = None
+    final_classes: bool = True
+
+    def __post_init__(self) -> None:
+        """Refuse a package no import statement could name."""
+        if self.root_package is not None and not all(
+            part.isidentifier() for part in self.root_package.split(".")
+        ):
+            message = f"root_package {self.root_package!r} is not a dotted Python identifier"
+            raise InvalidArgumentError(message)

xtr_maker/class_name.py

@@ -0,0 +1,144 @@
+"""ClassName: what a person typed, as the class, module and file a maker writes."""
+
+from __future__ import annotations
+
+import builtins
+import keyword
+import re
+from dataclasses import dataclass
+from pathlib import PurePosixPath
+from typing import Final, final
+
+from .exception import InvalidClassNameError
+from .name_converter import NameConverter
+
+__all__ = ["ClassName"]
+
+_TYPED: Final = re.compile(r"[A-Za-z0-9_ ./-]+")
+"""What a typed name may hold: words, and the separators between them and their packages."""
+
+_PACKAGE_SEPARATOR: Final = re.compile(r"[./]")
+
+_BUILTINS: Final = frozenset(dir(builtins))
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class ClassName:
+    """A class a maker writes: its name, the package it lives in, and its file.
+
+    Built with :meth:`create` from what a person typed; built directly, every
+    part is checked the same way. The package is the folder for the kind of
+    class (``message_handler``) under the application package, plus the
+    subpackages the person typed before the name (``ordering.PlaceOrder``)::
+
+        name = ClassName.create(
+            "ordering.place order", root_package="app", kind="message_handler", suffix="Handler"
+        )
+        name.short_name  # "PlaceOrderHandler"
+        name.module  # "app.message_handler.ordering.place_order_handler"
+        name.path  # PurePosixPath("message_handler/ordering/place_order_handler.py")
+
+    Attributes:
+        root_package: The application package, dotted.
+        package: The package under it, one entry per folder.
+        short_name: The class's own name.
+        suffix: The ending every class of its kind carries, ``""`` for none.
+
+    Raises:
+        InvalidClassNameError: When the class name is not an identifier, is a
+            keyword, or shadows a builtin, or a package part is not an
+            identifier or is a keyword.
+    """
+
+    root_package: str
+    package: tuple[str, ...]
+    short_name: str
+    suffix: str = ""
+
+    def __post_init__(self) -> None:
+        """Refuse any part that would not import, or would hide a name the code relies on."""
+        _check_class(self.short_name)
+        for part in (*self.root_package.split("."), *self.package, self.snake_name):
+            _check_module(part, self.short_name)
+
+    @classmethod
+    def create(cls, name: str, *, root_package: str, kind: str, suffix: str = "") -> ClassName:
+        """Resolve what a person typed into the class a maker writes.
+
+        Args:
+            name: The class name as typed — ``place order``, ``PlaceOrder`` —
+                optionally after subpackages, separated by ``.`` or ``/``:
+                ``ordering.PlaceOrder`` puts the class in ``<kind>/ordering/``.
+            root_package: The application package, dotted.
+            kind: The folder for the kind of class, dotted when nested
+                (``security.voter``).
+            suffix: The ending every class of its kind carries; added unless
+                the name already ends with it.
+
+        Returns:
+            The class, its package and its suffix.
+
+        Raises:
+            InvalidClassNameError: When ``name`` is empty, holds a character no
+                name can, or resolves to a part :class:`ClassName` refuses.
+        """
+        typed = name.strip()
+        if not typed or _TYPED.fullmatch(typed) is None:
+            raise InvalidClassNameError(
+                name, "use letters, digits, spaces, '_' or '-', and '.' before a subpackage"
+            )
+        *subpackages, last = _PACKAGE_SEPARATOR.split(typed)
+        short_name = NameConverter.as_class_name(last)
+        if suffix and not short_name.endswith(suffix):
+            short_name += suffix
+        package = (
+            *kind.split("."),
+            *(NameConverter.as_snake_case(part) for part in subpackages),
+        )
+        return cls(root_package=root_package, package=package, short_name=short_name, suffix=suffix)
+
+    @property
+    def name_without_suffix(self) -> str:
+        """The class name without its kind's suffix: ``PlaceOrderHandler`` → ``PlaceOrder``."""
+        if self.suffix and self.short_name != self.suffix:
+            return self.short_name.removesuffix(self.suffix)
+        return self.short_name
+
+    @property
+    def snake_name(self) -> str:
+        """The module's own name: ``PlaceOrderHandler`` → ``place_order_handler``."""
+        return NameConverter.as_snake_case(self.short_name)
+
+    @property
+    def package_name(self) -> str:
+        """The dotted package the module lives in."""
+        return ".".join((self.root_package, *self.package))
+
+    @property
+    def module(self) -> str:
+        """The dotted module the class is imported from."""
+        return f"{self.package_name}.{self.snake_name}"
+
+    @property
+    def path(self) -> PurePosixPath:
+        """The module's file, relative to the application package's directory."""
+        return PurePosixPath(*self.package, f"{self.snake_name}.py")
+
+
+def _check_class(short_name: str) -> None:
+    """Refuse a class name that does not parse, or that hides a builtin."""
+    if not short_name.isidentifier():
+        raise InvalidClassNameError(short_name, "it is not a Python identifier")
+    if keyword.iskeyword(short_name) or keyword.issoftkeyword(short_name):
+        raise InvalidClassNameError(short_name, "it is a Python keyword")
+    if short_name in _BUILTINS:
+        raise InvalidClassNameError(short_name, "it would hide the builtin of the same name")
+
+
+def _check_module(part: str, short_name: str) -> None:
+    """Refuse a package or module name an import statement cannot spell."""
+    if not part.isidentifier():
+        raise InvalidClassNameError(short_name, f"module {part!r} is not a Python identifier")
+    if keyword.iskeyword(part):
+        raise InvalidClassNameError(short_name, f"module {part!r} is a Python keyword")

xtr_maker/command/__init__.py

@@ -0,0 +1,9 @@
+"""The ``make:*`` commands, one module each.
+
+Nothing is imported here: each module imports the library it writes code for,
+and the bundle loads it only when that library's bundle is active.
+"""
+
+from __future__ import annotations
+
+__all__: list[str] = []