Why?
Every message, schedule, webhook, entity, command or listener starts as the same few files: a
class in the right folder, its imports, its decorator, a handler beside it. The make:*
commands write those files — named and placed the way the rest of the application is, formatted
the way the linter wants, and refused rather than overwritten when one already exists.
They are development tools: install the package as a development dependency and list its bundle
for the dev environment. Nothing reaches production, and nothing is written until a maker runs.
Install
uv add --dev xtr-maker
The makers write code for libraries, so each one is offered only when that library's bundle is active. An extra installs the library beside the makers, for an application that has not got it yet:
uv add --dev "xtr-maker[messenger,scheduler,webhook,orm,event-dispatcher]"
The makers
| Command | Writes | Listed when this bundle is active |
|---|---|---|
make:message |
A message and its handler | messenger |
make:schedule |
The provider of a schedule | scheduler |
make:webhook |
A webhook's parser, consumer and route | webhook |
make:entity |
An entity and its repository, or fields on one | orm |
make:command |
A console command class | — (the console bundle alone) |
make:listener |
A listener or a subscriber of one event | event_dispatcher |
make:migration |
A revision of what the tables changed | orm |
list make shows the ones an application has. A maker whose bundle is not active is not
registered at all: there is no command that tells you to install something.
Where the code goes
Each class goes in the folder named after what it is, under the application package, one public class per module:
| Folder | Module | Written by |
|---|---|---|
entity/ |
<snake>.py |
make:entity |
repository/ |
<snake>_repository.py |
make:entity |
message/ |
<snake>.py |
make:message |
message_handler/ |
<snake>_handler.py |
make:message |
scheduler/ |
<snake>_schedule.py |
make:schedule |
webhook/ |
<snake>_request_parser.py |
make:webhook |
remote_event/ |
<snake>_webhook_consumer.py |
make:webhook |
config/packages/ |
webhook_<snake>.py |
make:webhook |
command/ |
<snake>_command.py |
make:command |
event_listener/ |
<snake>_listener.py |
make:listener |
event_subscriber/ |
<snake>_subscriber.py |
make:listener |
A name may carry a subpackage: make:message ordering.PlaceOrder writes
message/ordering/place_order.py. A folder with no __init__.py gets one declaring nothing, so
the module imports by its dotted name and the container's scan finds it.
make:message
make:message [name] [--transport TRANSPORT] [--wire-name WIRE_NAME]
Writes message/<snake>.py — a frozen slotted dataclass declared with @as_message — and
message_handler/<snake>_handler.py, a class whose async def __call__(self, message) takes it.
| Asked | Answer | Default |
|---|---|---|
| The message's class name | PlaceOrder, "place order", ordering.PlaceOrder |
none: it must be answered |
| The transport it goes to when no route names one | [no transport], or one of MessageBusConfig.transports |
[no transport] |
| The name it travels under | any non-empty text | <package>.<snake>.v1 |
- The transport question is skipped when the bus has no transport configured; a
--transportthat names none is refused, listing the configured ones. - The wire name is pinned in the decorator, so moving the class later changes nothing on the wire.
- With
-n: the name must be on the command line, the transport is none unless--transportnames one, and the wire name is its default.
$ uv run app make:message PlaceOrder --transport async -n
created: src/app/message/place_order.py
created: src/app/message_handler/place_order_handler.py
[OK] Wrote PlaceOrder and PlaceOrderHandler.
Next:
- Open src/app/message/place_order.py and add its fields.
- Open src/app/message_handler/place_order_handler.py and write what handling it does.
make:schedule
make:schedule [name] [--schedule SCHEDULE] [--message MESSAGE] [--stateful] [--lock]
Writes scheduler/<snake>_schedule.py: an @as_schedule("<schedule>") provider deriving from
ScheduleProviderInterface, which builds its Schedule once in its constructor.
| Asked | Answer | Default |
|---|---|---|
| The provider's class name | ReportSchedule, "report" — Schedule is appended if missing |
none: it must be answered |
| The schedule it provides | letters, digits, _, - or . |
default |
| The message it sends every hour | [empty schedule], or one of the application's @as_message classes |
[empty schedule] |
| Keep what already ran in the scheduler cache pool? | yes/no, asked only with the cache bundle active |
no |
| Send from the worker holding a lock only? | yes/no, asked only with the lock bundle active |
no |
- The messages offered are the
@as_messageclasses of the application package, by class name, ormodule:Classwhen two share one. A message whose constructor takes arguments is written as a comment instead, so the module imports and the kernel boots before its fields are known. - A schedule another declared provider already provides is refused. One that only tasks are declared on is free: the tasks join this schedule.
--statefulwithout thecachebundle, or--lockwithout thelockbundle, is refused, naming the bundle to activate.- With
-n: the name must be given, the schedule isdefault, and nothing is sent, kept or locked unless the options say so.
$ uv run app make:schedule ReportSchedule --schedule reports -n
created: src/app/scheduler/report_schedule.py
[OK] Wrote ReportSchedule, which provides the reports schedule.
Next:
- Open src/app/scheduler/report_schedule.py and set what it sends, and how often.
- Run it: messenger:consume scheduler_reports
make:webhook
make:webhook [name] [--matcher MATCHER]...
The name is the webhook type: the last segment of the URL its sender posts to, and the source name of the events it carries. Three modules come out of it:
| Module | Holds |
|---|---|
webhook/<snake>_request_parser.py |
An AbstractRequestParser: get_request_matcher claims the sender's requests, do_parse compares the signature header with the secret and reads a RemoteEvent from the JSON body |
remote_event/<snake>_webhook_consumer.py |
An @as_remote_event_consumer("<type>") class with async def consume(self, event) |
config/packages/webhook_<snake>.py |
A @configure transform adding a RouteConfig(parser=..., secret=env("<TYPE>_WEBHOOK_SECRET")) to whatever routing is configured |
The matchers are asked for one at a time — [done], then every one not picked yet — whether or
not the name was given, each written with placeholder arguments to replace:
Attributes, Callable, Header, Host, Ips, IsJson, Method, Path, Port,
QueryParameter, Scheme.
- One matcher is returned as it is; several are wrapped in a
ChainRequestMatcher; none writes an empty chain, with a comment saying it claims every request. --matchertakes a name with or withoutRequestMatcher, without case, repeatable; one that is not offered is refused, listing them.- A type the webhook configuration already routes is refused. The routed types are read as the kernel builds, not from the injected configuration, so a secret that is not set yet does not stop the next webhook from being made.
- With
-n: the name must be given, and the matchers areMethodandIsJsonunless--matchernames others.
$ uv run app make:webhook stripe --matcher Method -n
created: src/app/webhook/stripe_request_parser.py
created: src/app/remote_event/stripe_webhook_consumer.py
created: src/app/config/packages/webhook_stripe.py
[OK] Wrote StripeRequestParser, StripeWebhookConsumer and the stripe route.
Next:
- Add STRIPE_WEBHOOK_SECRET to .env.local: the secret stripe shares with you.
- Open src/app/webhook/stripe_request_parser.py and replace the secret check with the one its sender's protocol asks for.
- Open src/app/remote_event/stripe_webhook_consumer.py and write what an event leads to.
- Make sure config/routes/webhook.py exists, with an @as_routes function including resources["webhook"]: the sender posts to /webhook/stripe.
make:entity
make:entity [name] [--field FIELD]... [--relation RELATION]... [--id uuid|uuid7|bigint] [--no-audit]
A new entity gets entity/<snake>.py, stored in the plural of its name, and
repository/<snake>_repository.py — a SQLAlchemyAsyncRepository subclass with an @as_service
factory scoped like the AsyncSession it takes. An entity that exists gets only the new
properties, every other line kept as it was, and no repository.
The base class comes from --id and --no-audit:
--id |
Audited (the default) | --no-audit |
|---|---|---|
uuid (the default) |
UUIDAuditBase |
UUIDBase |
uuid7 |
UUIDv7AuditBase |
UUIDv7Base |
bigint |
BigIntAuditBase |
BigIntBase |
Both only choose a new entity's base; either one given for an entity that exists is refused.
Fields — --field name:type[:settings][?], repeatable; ? makes the column nullable, which
also makes the attribute T | None:
| Type | Attribute | Column |
|---|---|---|
string[:length] |
str |
String(length), 255 by default |
text |
str |
Text |
integer, big_integer, small_integer |
int |
Integer, BigInteger, SmallInteger |
boolean |
bool |
Boolean |
float |
float |
Float |
decimal[:precision[:scale]] |
Decimal |
Numeric(precision, scale), 10, 2 by default |
date, time |
date, time |
Date, Time |
datetime |
datetime |
DateTimeUTC(timezone=True) |
json |
dict[str, object] |
JSON |
uuid |
UUID |
GUID |
enum:<dotted class> |
the enum class | Enum(<class>) |
binary |
bytes |
LargeBinary |
Asked for one at a time, the type offered is the one the name suggests — _at a datetime,
_id a uuid, is_/has_ a boolean, anything else a string — and ? at the prompt lists
them all.
Relations — --relation name:kind:Target[?][,inverse=name|none], repeatable:
| Kind | This entity gets | The other entity gets |
|---|---|---|
many_to_one |
<name>_id with a ForeignKey, and the relationship |
a collection, named after this one in the plural |
one_to_many |
a collection | the key and the relationship; the inverse must be named |
one_to_one |
a unique <name>_id and the relationship |
one of this entity |
many_to_many |
a collection through an association table, written in a module of its own | a collection |
? makes the foreign key nullable, which many_to_many has not got. inverse=none adds nothing
to the other entity; left out, the inverse is this entity's name, pluralized when that side
reaches many of it. The other entity is imported for annotations only: the relationship finds it
by name once every entity is mapped.
With --field or --relation, or with -n, nothing is asked. With neither and a terminal, the
questions run until a property name is left empty. Every name is checked before anything is
written: a property the entity already has, or an unimportable enum, leaves both entities as they
were.
$ uv run app make:entity Book --field title:string:120 -n
created: src/app/entity/book.py
created: src/app/repository/book_repository.py
[OK] Wrote Book and BookRepository.
Next:
- Run make:migration to write the revision the change needs.
- Then run orm:migrations:migrate -n to apply it.
make:command
make:command [name] [--argument ARGUMENT]... [--option OPTION]...
Writes command/<snake>_command.py: a class declared with @as_command, named after the last
part of the console name — app:send-report is SendReportCommand. Its __call__ takes the
arguments, then the options after a bare *, each documented in the docstring --help reads,
and its body prints every value it was given, so the command runs as soon as it is written.
--argument name[?][:type]:?makes it optional. Types arestr(the default),int,float,list(list[str]) and an enum class asmodule.Class.--option name[:type]: types arebool(the default) and the same others.- A list argument takes every value left, so none is asked after it; a required argument may not
follow an optional one;
iois reserved; names are unique. - A name a command already answers to is refused, and so is one whose last part cannot name a class.
- With neither
--argumentnor--optionand a terminal, they are asked one at a time until a name is left empty. With-nand neither, the command takes anameargument and ayelloption to start from.
$ uv run app make:command app:send-report --argument recipient -n
created: src/app/command/send_report_command.py
[OK] Wrote SendReportCommand.
Next:
- Run app:send-report --help to see its arguments and options.
- Open src/app/command/send_report_command.py and write what it does.
make:listener
make:listener [name] [event]
A name ending in Listener writes event_listener/<snake>_listener.py, a class whose
async def on_<event> method carries @as_event_listener. One ending in Subscriber writes
event_subscriber/<snake>_subscriber.py, deriving from EventSubscriberInterface and mapping the
event to that method in get_subscribed_events. Any other name is asked which, a listener by
default, and the suffix is appended.
The event is a class — by its name, as module:Class, or as a dotted path — or a name it is
dispatched under. When it is asked, the events found are listed: those of the installed xtr
packages, those of the application's own event package, and those the dispatcher already has a
listener for. A name close to some of them is answered with what it may have meant; a name that
matches none is offered as a plain dispatch name to confirm, and the generated code then imports
Event for the annotation.
With -n both the name and the event must be given, and the event must resolve: a plain dispatch
name needs the question, so it is refused.
$ uv run app make:listener WorkerStatsSubscriber WorkerStartedEvent -n
created: src/app/event_subscriber/worker_stats_subscriber.py
[OK] Wrote WorkerStatsSubscriber, reacting to xtr_messenger.event:WorkerStartedEvent.
Next:
- Open src/app/event_subscriber/worker_stats_subscriber.py and write what on_worker_started_event does.
make:migration
make:migration [--message MESSAGE] [--connection CONNECTION]
The only maker with no template of its own: it compares a connection's database with its table
definitions and lets the connection's migrator write the revision, into its migrations directory,
exactly as orm:migrations:diff does. The file is never opened or edited afterwards.
--messagenames what the revision does, and its file; asked when left out, defaulting toauto. An empty one is refused.--connectionpicks the connection; the default one when left out. One the registry does not know is refused, listing the names it has.- The database must have every revision applied first, or the comparison would see what is still
to run rather than what the tables add. A database that is behind reports how many revisions are
waiting, then
Run orm:migrations:migrate -n first. - Nothing differing is a note,
No database changes were detected., and a successful exit with nothing written.
$ uv run app make:migration --message books -n
created: migrations/20261029105403_c51185006457_books.py
[OK] Wrote the revision c51185006457.
Next:
- Review the new revision, then run orm:migrations:migrate -n.
What every maker does, and never does
- Nothing is overwritten. A target that exists, or one another file of the same run already
claimed, ends the run before anything reaches the disk. The exception is
make:entityon an entity that exists: it adds the new properties and their imports and writes the module back, every other line byte-identical. - All or nothing. A run renders every file first and writes them together, so a name already taken or a template that renders source which does not parse leaves the working tree as it was.
- Configuration is never edited.
make:webhookwrites a new@configuretransform module rather than touching the application's webhook configuration; every other maker writes no configuration at all. - Secrets are never generated. A maker that needs one prints the
.env.localstep instead. - Nothing is written outside the project. A path that leaves the project directory, or is a symbolic link, is refused, so what is typed at a prompt cannot reach elsewhere on disk.
- Where the code goes is the kernel's own package,
kernel.package, unlessMakerConfig.root_packagenames another. Classes are marked@finalunlessMakerConfig.final_classesis off. - The application package is found when a maker first needs it — in the folder the import system loads it from, whatever the project's layout — never when the console starts.
Generated code and the linters
Every module is written the way the formatter would write it: lines of at most 88 columns,
double quotes, imports grouped standard library, third-party then the application's own package
and sorted the way the import rules sort them, a statement too long for one line wrapped with a
trailing comma.
Each file opens with a docstring, from __future__ import annotations and its __all__.
Two things to know when the project's own settings are stricter:
- Annotations read at runtime. A console command's parameter types, and a container-hydrated
constructor's, and an entity's column types, are read at runtime, so they cannot move into
if TYPE_CHECKING:. The rules that would move them (TC001,TC002,TC003) have to be off for such modules, as they are in an application on the container. Everything genuinely used for annotations only is already in aTYPE_CHECKINGblock. - Two-way relations.
make:entitywrites each side's import of the other underTYPE_CHECKING, which basedpyright'sreportImportCyclessees as a cycle all the same. The entity therefore carries# pyright: reportImportCycles=false, with the reason, above that block.
A statement split over lines ends with a trailing comma, so a formatter set to a wider line length
keeps it split: the output passes ruff format --check at any width from 88 up.
Use in an application
Everything adding this package to an application on xtr-dependency-injection takes — and, read backwards, what removing it undoes.
-
Install —
uv run xtr-recipes recipes:add --dev xtr-maker, oruv add --dev xtr-makerthenuv run xtr-recipes recipes:sync: the makers write code while you develop, so they are a development dependency, never a runtime one. Add the extras of the libraries you want makers for if the application has not got them yet. -
Recipe —
uv run xtr-recipes recipes:syncdoes the Activate step below, and only that: it listsMakerBundlefor thedevenvironment, which is what this package's recipe declares. There is nothing for it to configure, no variable to write and nothing to ignore. -
Activate — import the bundle at the top of
<app>/config/bundles.py, like every other one, and list it fordev:# <app>/config/bundles.py from xtr_maker.bundle import MakerBundle BUNDLES = { MakerBundle: {"dev": True}, }
Production still starts without the development dependencies installed: there the kernel stands in for the bundle, which is not active, and never needs its package.
-
Brings along — the console bundle, which the makers are commands of. The messenger, scheduler, webhook, orm and event dispatcher bundles are not brought along: each is read, not required, and decides which makers are registered.
-
Configure — nothing to configure: the code goes into the kernel's own package and every class is
@final. To change either, put the settings in thedevenvironment folder,<app>/config/packages/dev/: production does not install this package, and only adevbuild imports that folder, so a production start never importsxtr_maker.# <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)
-
Environment — nothing. A maker that needs a secret prints the variable to set in
.env.localrather than reading one itself. -
Ignore — nothing: what the makers write is code to commit.
-
Remove —
uv run xtr-recipes recipes:remove xtr-maker: it runsuv remove --dev xtr-maker, and the sync after it drops theBUNDLESentry. Delete<app>/config/packages/dev/maker.pyif you wrote one. The code the makers wrote stays yours. -
Check —
debug:bundleslistsmakeras active indev;list makeshows onemake:*command for each library whose bundle is active.
Kernel / bundle
MakerBundle is declared @as_bundle("maker", config=MakerConfig) and requires the console
bundle. Its load_extension registers three services and then the command module of each maker
whose library's bundle is active:
| Service | Lifetime | Is |
|---|---|---|
TemplateRenderer |
singleton | The templates this package ships, rendered, then parsed before anything is queued |
FileManager |
singleton | The project directory and the application package, and the only way a maker writes |
Generator |
scoped | One maker run's queue of files: a failed run leaves nothing queued for the next |
MakerConfig is a frozen dataclass buildable with no arguments:
| Field | Default | Is |
|---|---|---|
root_package |
None |
The dotted application package the makers write into; None takes kernel.package. A value that is not a dotted Python identifier raises InvalidArgumentError |
final_classes |
True |
Whether generated classes are marked @final |
Errors
All of them derive from MakerError, so one except catches anything that can stop a maker:
| 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 cannot name a class: a keyword, no identifier, or shadowing a builtin |
TargetExistsError |
A file to write exists, or another file of the same run already claimed it — also a FileExistsError |
UnsafePathError |
A path leaves the project directory, or is a symbolic link |
A command turns them into 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 migration
that could not be written, ExitCode.SUCCESS otherwise — nothing to write included.
Development
Developed in the python-xtr monorepo, under
packages/xtr-maker; run the commands below from there. The python-xtr-maker
repository is a read-only copy, so send issues and pull requests to the monorepo.
uv sync
uv run ruff check
uv run ruff format --check
uv run basedpyright
uv run ty check
uv run pytest
License
MIT — see LICENSE.
Metadata
Release files for xtr-maker 6.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| xtr_maker-6.3.0.tar.gz | 90.0 kB | With provenance | Details for xtr_maker-6.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| xtr_maker-6.3.0-py3-none-any.whl | Python 3 | none | any | Details for xtr_maker-6.3.0-py3-none-any.whl |
Total release size: 204.5 kB
Release files / xtr_maker-6.3.0.tar.gz
| Download URL | xtr_maker-6.3.0.tar.gz |
|---|---|
| Size | 90.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c5ea637636206854fbdde220ede3d9e0e7062f305cbb287fbf030469f119afdb
|
|
BLAKE2b-256 checksum How to use checksums |
c8f1300869bc71ac1f8dbe7dd853c443412ec23f357fab0994d37748118dcf7d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.
Transparency logRelease files / xtr_maker-6.3.0-py3-none-any.whl
| Download URL | xtr_maker-6.3.0-py3-none-any.whl |
|---|---|
| Size | 114.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e51f5ef7ccb124095c182c2e19744a5cc5160e040500ab10a5075a3fe3b96d83
|
|
BLAKE2b-256 checksum How to use checksums |
c59f4370072abfb97692695d2f8b37cf55e525c616f2f2b9b9e4726f380f9a59
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.
Transparency logSecurity for xtr-maker 6.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for xtr_maker-6.3.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.