Skip to content

About

Small, typed, async-ready building blocks for Python, one package each: clock, console, dependency injection, logging, messenger and their contracts.

Topics

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

xtr

Small, typed, async-ready building blocks for Python applications — one repository, one package each.

python 3.14+ typed managed with uv license MIT

Each directory under packages/ is an independent distribution with its own version, dependencies, tests and README. They are developed together here so a change that crosses packages is one commit, and released separately so an application installs only what it uses.

Packages

Package What it is
xtr-ai Named language-model platforms and agents on pydantic-ai, configured once and injected by name, with conversation stores.
xtr-ai-orm-conversation-store Agent conversations kept in two tables on an xtr-orm connection, for xtr-ai.
xtr-cache Cache pools in memory, in files, in Redis, chained or tag-aware, with stampede protection.
xtr-cache-contracts The caching interfaces alone: fetch-or-compute, item pools, tags and namespaces.
xtr-cli uvx xtr-cli new: a new console or web application, its packages installed and their recipes applied, in one command; uvx xtr-cli serve runs it.
xtr-clock An injectable clock, a timezone-aware DatePoint, and a frozen clock for tests.
xtr-console Async-native console applications: commands as functions or classes, wired by a container.
xtr-dependency-injection A bundle and kernel layer for Python, compiled to a wireup container.
xtr-dotenv Layered .env files loaded into the environment, and the same layers behind a typed settings model.
xtr-event-dispatcher Events dispatched to listeners and subscribers by priority, any of them able to stop the rest.
xtr-event-dispatcher-contracts The event dispatching interfaces alone, for libraries that emit events without choosing who hears them.
xtr-http-client An async HTTP client behind one interface: typed options in, a response read on demand out, with scoped clients, retries, a pace, a trace, a private-network guard and a mock for tests.
xtr-http-client-contracts The async HTTP client interfaces alone: a request call, a response read on demand, typed options, errors, and a conformance suite.
xtr-http-foundation One question each about a request that arrived, composed into one matcher — the helpers that place an IP in a network, and the session a stateful request carries: attributes under an ID cookie, in whatever storage the application points at.
xtr-http-kernel A request lifecycle for FastAPI applications: requests turned into responses through events, wired by a container.
xtr-http-message The HTTP message interfaces implemented: requests, responses, streams, URIs, uploaded files and one factory for all six.
xtr-http-message-contracts The HTTP message interfaces alone: requests, responses, streams, URIs, uploaded files and their factories.
xtr-logging Channels, handlers, processors and formatters behind one logger interface.
xtr-logging-contracts The logging interface alone, for libraries that log but should not choose how.
xtr-mailer Email sent through SMTP, sendmail or a provider's API — picked by DSN, in-process or queued on a message bus, with failover, round-robin, envelope and header overrides, DKIM and S/MIME signing.
xtr-maker Console commands that write application code for the xtr libraries, refusing a file that already exists.
xtr-messenger A message bus: envelopes, stamps, a middleware chain and pluggable transports.
xtr-amqp-messenger A RabbitMQ transport for xtr-messenger: queues on an AMQP broker, a retry ladder, delays and real dead-lettering, through taskiq.
xtr-mime Email messages — addresses, headers, text and HTML bodies, attachments and inline images — rendered to standard MIME by Python's own email package, and signed with DKIM or S/MIME when asked.
xtr-notifier Notifications sent to chat, SMS and push channels — picked by the notification or its importance — through any provider configured by DSN, directly or through the message bus.
xtr-telegram-notifier Telegram for xtr-notifier: chat messages posted, edited and answered through a bot, with keyboards, media and file uploads.
xtr-slack-notifier Slack for xtr-notifier: chat messages posted, scheduled and updated in a channel, laid out with Block Kit blocks.
xtr-orm Engines, sessions and versioned schema migrations for async applications, configured once per connection.
xtr-orm-messenger A database transport for xtr-messenger: messages kept in a table on an xtr-orm connection, claimed by workers, delayed, redelivered and woken by notifications.
xtr-password-hasher Password hashing behind one interface: argon2id by default, legacy hashes verified and upgraded.
xtr-security-core The security core: users, tokens, roles, voters and the authorization decision.
xtr-security-csrf Cross-site request forgery protection: a manager that mints and checks tokens by id, and the session storage that keeps them.
xtr-security-http The HTTP edge of security: firewalls, authenticators, bearer access tokens and the request surface.
xtr-security-jwt Self-issued JSON Web Tokens: key sets, an encoder and a token manager for a user.
xtr-security The security bundle: the family facade and the container wiring that configures it.
xtr-security-oauth2-server-core The OAuth 2.0 authorization-server library: grants, servers, entities, response types and the resource server.
xtr-security-oauth2-server An OAuth 2.0 authorization server and resource-server authenticator.
xtr-security-openid-connect-server OpenID Connect on that authorization server: ID tokens, a userinfo endpoint and a configuration document for the authorization code flow.
xtr-serializer Objects turned into JSON and back exactly — dataclasses, models, class hierarchies and dates arrive as they left, or are refused — through a chain of normalizers and encoders.
xtr-service-contracts What a container drives on a service, not what the service does. No dependencies.
xtr-lock Exclusive and shared locks around resources, in memory, in files, in Redis, or across several stores.
xtr-scheduler Recurring messages on xtr-messenger: cron and intervals, catch-up after downtime, locks and saved state.
xtr-rate-limiter Limits on how often anything may happen, by fixed window, sliding window or token bucket, in memory, in a cache or atomically in Redis.
xtr-recipes A command that applies each dependency's use-in-an-application steps from a committed lock, and undoes them when the package is removed.
xtr-storage Files on local disk, in memory or in object stores, behind one async interface.
xtr-stopwatch Named events timed in nested sections — one set per concurrent unit of work — for a profile's timeline.
xtr-remote-event Events received from another system, as one value type, handed to the consumer registered under their source's name.
xtr-web-profiler In development, a toolbar on every page and a searchable profile of every request: timeline, logs, events, routing, the exception.
xtr-webhook Webhooks received as events — verified and replay-bounded — and sent signed, in the legacy or the Standard Webhooks format.
xtr-workflow Move objects through workflows and state machines — weighted places and transitions, guards, events at every step, definitions in code, config or on a class, dumped as Graphviz, PlantUML or Mermaid.

How they depend on each other (runtime dependencies; a dotted edge is an optional integration, used when the application installs that package too):

graph LR
    logging[xtr-logging] --> clock[xtr-clock]
    logging --> logcon[xtr-logging-contracts]
    logging --> svccon[xtr-service-contracts]
    messenger[xtr-messenger] --> logcon
    messenger --> eventcon
    messenger --> serializer
    messenger --> clock
    lock[xtr-lock] --> clock
    lock --> logcon
    cachecon[xtr-cache-contracts] --> clock
    cache[xtr-cache] --> cachecon
    cache --> lock
    cache --> clock
    cache --> logcon
    cache -. optional .-> console
    events[xtr-event-dispatcher] --> eventcon[xtr-event-dispatcher-contracts]
    events --> logcon
    events -. optional .-> stopwatch
    stopwatch[xtr-stopwatch] --> clock
    messenger -. optional .-> console[xtr-console]
    scheduler[xtr-scheduler] --> messenger
    scheduler --> serializer
    scheduler --> clock
    scheduler --> lock
    scheduler --> cachecon
    scheduler --> events
    scheduler --> eventcon
    scheduler --> svccon
    scheduler -. optional .-> console
    di[xtr-dependency-injection] --> svccon
    httpkernel[xtr-http-kernel] --> di
    httpkernel --> events
    httpkernel --> eventcon
    httpkernel --> logcon
    httpkernel --> svccon
    httpkernel -. optional .-> logging
    httpkernel -. optional .-> console
    httpmsgcon[xtr-http-message-contracts]
    httpmsg[xtr-http-message] --> httpmsgcon
    httpkernel --> httpmsg
    httpkernel --> httpmsgcon
    httpkernel --> clock
    httpkernel --> stopwatch
    webprofiler[xtr-web-profiler] --> httpkernel
    webprofiler --> di
    webprofiler --> httpmsgcon
    httpfoundation[xtr-http-foundation] --> httpmsgcon
    httpfoundation --> clock
    httpclientcon[xtr-http-client-contracts] --> httpmsgcon
    httpclient[xtr-http-client] --> httpclientcon
    httpclient -. optional .-> httpfoundation
    httpclient --> httpmsg
    httpclient --> httpmsgcon
    httpclient --> logcon
    httpclient --> svccon
    httpclient -. optional .-> di
    httpclient -. optional .-> ratelimiter
    orm[xtr-orm] --> logcon
    orm --> clock
    orm -. optional .-> di
    orm -. optional .-> svccon
    orm -. optional .-> console
    orm -. optional .-> messenger
    orm -. optional .-> ormmessenger
    ormmessenger[xtr-orm-messenger] --> messenger
    ormmessenger --> orm
    ormmessenger --> clock
    messenger -. optional .-> ormmessenger
    amqpmessenger[xtr-amqp-messenger] --> messenger
    amqpmessenger --> clock
    messenger -. optional .-> amqpmessenger
    ai[xtr-ai] --> clock
    ai --> logcon
    ai -. optional .-> di
    ai -. optional .-> orm
    ai -. optional .-> console
    ai -. optional .-> aiconversations
    aiconversations[xtr-ai-orm-conversation-store] --> ai
    aiconversations --> orm
    ratelimiter[xtr-rate-limiter] --> clock
    ratelimiter --> eventcon
    ratelimiter -. optional .-> cachecon
    ratelimiter -. optional .-> lock
    ratelimiter -. optional .-> di
    httpkernel -. optional .-> ratelimiter
    passwordhasher[xtr-password-hasher]
    passwordhasher -. optional .-> console
    securitycore[xtr-security-core] --> passwordhasher
    securitycore --> eventcon
    securitycore --> svccon
    securitycore --> clock
    securitycsrf[xtr-security-csrf] --> httpfoundation
    securityhttp[xtr-security-http] --> securitycore
    securityhttp --> securitycsrf
    securityhttp --> httpkernel
    securityhttp --> httpfoundation
    securityhttp --> httpmsgcon
    securityhttp --> di
    securityhttp --> events
    securityhttp --> eventcon
    securityhttp --> logcon
    securityhttp --> passwordhasher
    securityhttp --> ratelimiter
    securityhttp --> clock
    securityhttp --> httpclientcon
    securityhttp --> cachecon
    security[xtr-security] --> securitycore
    security --> securityhttp
    security --> securitycsrf
    security --> passwordhasher
    security --> di
    security --> events
    security --> httpkernel
    security --> httpfoundation
    security --> httpmsgcon
    security --> clock
    security --> httpclient
    security --> cache
    security --> ratelimiter
    security -. optional .-> console
    securityjwt[xtr-security-jwt] --> security
    securityjwt --> securitycore
    securityjwt --> securityhttp
    securityjwt --> httpmsgcon
    securityjwt --> di
    securityjwt --> clock
    securityjwt --> events
    securityjwt --> eventcon
    securityjwt -. optional .-> console
    oauth2core[xtr-security-oauth2-server-core] --> securitycore
    oauth2core --> securityjwt
    oauth2core --> clock
    oauth2core --> eventcon
    oauth2core --> httpmsgcon
    oauth2server[xtr-security-oauth2-server] --> oauth2core
    oauth2server --> securitycore
    oauth2server --> securityhttp
    oauth2server --> security
    oauth2server --> securityjwt
    oauth2server --> passwordhasher
    oauth2server --> clock
    oauth2server --> eventcon
    oauth2server --> events
    oauth2server --> logcon
    oauth2server --> di
    oauth2server --> httpmsgcon
    oauth2server --> httpkernel
    oauth2server -. optional .-> orm
    oauth2server -. optional .-> console
    oidcserver[xtr-security-openid-connect-server] --> oauth2server
    oidcserver --> oauth2core
    oidcserver --> securitycore
    oidcserver --> securityhttp
    oidcserver --> security
    oidcserver --> securityjwt
    oidcserver --> clock
    oidcserver --> eventcon
    oidcserver --> events
    oidcserver --> di
    oidcserver --> httpmsgcon
    oidcserver --> httpkernel
    storage[xtr-storage] -. optional .-> di
    dotenv[xtr-dotenv] -. optional .-> di
    dotenv -. optional .-> console
    recipes[xtr-recipes] --> di
    recipes --> console
    maker[xtr-maker] --> di
    maker --> console
    maker -. optional .-> messenger
    maker -. optional .-> scheduler
    maker -. optional .-> webhook
    maker -. optional .-> orm
    maker -. optional .-> events
    cli[xtr-cli] --> console
    remoteevent[xtr-remote-event] --> messenger
    remoteevent --> serializer
    remoteevent --> svccon
    webhook[xtr-webhook] --> remoteevent
    webhook --> messenger
    webhook --> serializer
    webhook --> clock
    webhook --> httpmsgcon
    webhook --> svccon
    webhook --> httpkernel
    webhook --> httpclientcon
    webhook --> httpfoundation
    webhook -. optional .-> di
    webhook -. optional .-> httpclient
    webhook --> httpmsg
    remoteevent -. optional .-> di
    notifier[xtr-notifier] --> clock
    notifier --> eventcon
    notifier --> httpclientcon
    notifier --> logcon
    notifier --> svccon
    notifier -. optional .-> messenger
    notifier -. optional .-> di
    telegramnotifier[xtr-telegram-notifier] --> notifier
    telegramnotifier --> httpclientcon
    slacknotifier[xtr-slack-notifier] --> notifier
    slacknotifier --> httpclientcon
    workflow[xtr-workflow] --> clock
    workflow --> events
    workflow --> eventcon
    workflow --> logcon
    workflow --> svccon
    serializer[xtr-serializer] -. optional .-> di
    serializer --> clock
    serializer -. optional .-> console
    mime[xtr-mime] --> clock
    mailer[xtr-mailer] --> mime
    mailer --> clock
    mailer --> eventcon
    mailer --> httpclientcon
    mailer --> logcon
    mailer --> svccon
    mailer -. optional .-> messenger
    mailer -. optional .-> ratelimiter
    mailer -. optional .-> console
Loading

The contracts packages exist so a library can depend on an interface without installing its implementation: xtr-messenger logs through xtr-logging-contracts, and the application decides whether xtr-logging is behind it.

Install

Each package is published to PyPI on its own:

uv add xtr-logging
uv add "xtr-messenger[amqp]"
uv add "xtr-scheduler[cron]"

Versions

Every package shares one version and is released together, even one that did not change — any two xtr-* packages at the same version are known to work together. Packages require their siblings by major version (xtr-logging-contracts>=7.0,<8).

scripts/release.py keeps that consistent:

uv run scripts/release.py check        # every package, this README and the docs on one version (CI runs this)
uv run scripts/release.py bump 7.1.0   # move every package, this README and the docs; on a new major, rewrite the ranges

A package classified Private :: Do Not Upload moves with the rest but is never published or split.

What changes between major versions, package by package, and how to keep the old behaviour where that is still possible, is in UPGRADING.md.

Releasing

uv run scripts/release.py bump 7.1.0
git commit -am "bump: 7.1.0" && git push
git tag 7.1.0 && git push origin 7.1.0

The tag starts the release workflow: it waits for CI to pass on the tagged commit's push to main — nothing is released otherwise — checks the tag against the packages' version, publishes every package to PyPI through trusted publishing, and tags each read-only repository 7.1.0.

Repositories

This repository is where everything is developed. Each published package is also copied, once CI passes on a push to main, into a repository of its own — xterr/python-<package>, e.g. python-xtr-logging — which carries only that package's directory and history, and its release tags. Those copies are read-only: pull requests there are closed automatically, so send issues and pull requests here.

Development

Requires uv. The repository is a uv workspace: one lockfile, one virtual environment, and every package installed editable, so a change in one package is immediately visible to the packages that use it.

git clone git@github.com:xterr/python-xtr.git
cd python-xtr
uv sync --all-packages
uv run pre-commit install

The pre-commit hook runs ruff on what you commit, basedpyright, ty and the tests of every package you touched, and the repository's own tests (tests/). Those run only there: they import every package, while CI checks each package on its own. CI runs every package's tests on Python 3.14.4 and the latest 3.14, and checks their types.

Work inside a package directory; each carries its own pytest, ruff, basedpyright and ty settings:

cd packages/xtr-logging
uv run pytest
uv run ruff check
uv run ruff format --check
uv run basedpyright
uv run ty check

To run one package against only the dependencies it declares, from the repository root:

uv run --package xtr-logging --exact pytest packages/xtr-logging

This is the check that catches a package importing a sibling it never listed in its pyproject.toml — something the shared environment would otherwise hide.

Creating a package

Every package follows the same shape. Rules that apply to code, tests, docs and commit messages live in AGENTS.md; this section is the mechanical checklist.

A package contains: a pyproject.toml at the current shared version, a src/xtr_<name>/ importable package with py.typed, tests under tests/, a README.md starting with the package's one-line pitch, and a LICENSE. A package integrates with xtr-dependency-injection through a bundle under src/xtr_<name>/bundle/. Neither the container nor any other xtr package it integrates with is a dependency: each is in the dev group for the tests, and the integration is used when the application installs it. Extras are only for third-party backends — and for a transport package an application would otherwise add by hand, as xtr-messenger[orm] brings xtr-orm-messenger and xtr-messenger[amqp] xtr-amqp-messenger.

Directory template

packages/xtr-<name>/
├── pyproject.toml
├── README.md
├── LICENSE
├── src/xtr_<name>/
│   ├── __init__.py
│   ├── py.typed
│   ├── <thing>.py                 # one public class per file
│   ├── <thing>_interface.py       # @runtime_checkable Protocol
│   ├── exception/
│   │   ├── __init__.py
│   │   ├── <name>_error.py        # package base error
│   │   └── <specific>_error.py
│   ├── .agents/skills/xtr-<name>/
│   │   └── SKILL.md               # agent skill, shipped in the wheel
│   └── bundle/
│       ├── __init__.py
│       ├── <name>_bundle.py
│       └── <name>_config.py
└── tests/
    ├── conftest.py
    ├── unit/
    ├── integration/
    ├── fixtures/
    └── support/

pyproject.toml

[project]
name = "xtr-<name>"
version = "7.1.0"
description = "<one-line pitch, on this project's own terms>."
readme = "README.md"
requires-python = ">=3.14.4"
license = "MIT"
license-files = ["LICENSE"]
authors = [
    { name = "Xterr", email = "me@xterr.dev" }
]
keywords = ["<name>"]
classifiers = [
    "Development Status :: 3 - Alpha",
    "Intended Audience :: Developers",
    "Programming Language :: Python :: 3.14",
    "Typing :: Typed",
]
dependencies = []

# Advertises the bundle so debug:bundles can name it when installed but not listed.
# Advertising activates nothing: an application lists the bundles it wants.
[project.entry-points."xtr_dependency_injection.bundles"]
<name> = "xtr_<name>.bundle:<Name>Bundle"

[dependency-groups]
dev = [
    "basedpyright>=1.21",
    "ruff>=0.8",
    "pytest>=8",
    "pytest-cov>=5",
    "anyio>=4.0",
    "ty>=0.0.83",
    "xtr-dependency-injection>=7.0,<8",
]

[build-system]
requires = ["uv_build>=0.9.18,<0.10.0"]
build-backend = "uv_build"

[tool.basedpyright]
typeCheckingMode = "all"
pythonVersion = "3.14"
pythonPlatform = "All"
include = ["src", "tests"]
exclude = ["**/__pycache__", "**/.venv", "**/build", "**/dist", ".tmp"]
reportUnusedCallResult = "warning"
reportUnnecessaryTypeIgnoreComment = "error"
reportUnusedVariable = "error"
reportMissingParameterType = "error"
reportPrivateUsage = "error"

[tool.ruff]
target-version = "py314"
line-length = 100
src = ["src", "tests"]

[tool.ruff.lint]
select = ["ALL"]
ignore = [
    "COM812", "ISC001", "D203", "D213", "CPY001", "FBT001", "FBT002", "TD002", "TD003", "FIX002",
    # Errors compose their message from typed fields; the string at a raise site is a reason.
    "TRY003", "EM101", "EM102",
    # Add when the package logs through the logging contract, whose context mapping
    # the standard library's format-argument checks misread:
    # "PLE1205", "PLE1206",
]
fixable = ["ALL"]
unfixable = []

[tool.ruff.lint.per-file-ignores]
"tests/**/*.py" = ["S101", "ARG", "PLR2004", "SLF001", "D"]

[tool.ruff.lint.pydocstyle]
convention = "google"

[tool.ruff.format]
quote-style = "double"
indent-style = "space"

[tool.ty.src]
include = ["src", "tests"]

[tool.pytest.ini_options]
minversion = "8.0"
testpaths = ["tests"]
addopts = ["-ra", "--strict-config", "--strict-markers"]
filterwarnings = ["error"]

[tool.coverage.run]
source = ["src"]
branch = true

[tool.coverage.report]
# CI runs the tests with --cov; a change taking coverage below this fails there.
fail_under = 95

Packages never declare their own [tool.uv.sources]; the root maps every xtr-* name to the workspace.

src/xtr_<name>/__init__.py

"""<one-line pitch, on this project's own terms>."""

from __future__ import annotations

__all__ = []

An empty src/xtr_<name>/py.typed sits next to it.

Bundle and config

The bundle is optional — a library without a container works as it stands — but the shape is fixed so every application configures every package the same way. Read packages/xtr-dependency-injection/README.md for what each hook means; the template below is a working starting point.

# src/xtr_<name>/bundle/<name>_config.py
"""Configuration for the <name> bundle."""

from __future__ import annotations

from dataclasses import dataclass

__all__ = ["<Name>Config"]


@dataclass(frozen=True, slots=True)
class <Name>Config:
    """Values the bundle builds from. Must be buildable with no arguments."""

    # example field; delete or replace
    option: str = "default"

    def __post_init__(self) -> None:
        """Validate combinations that dataclass defaults cannot express."""
# src/xtr_<name>/bundle/<name>_bundle.py
"""The xtr-<name> bundle."""

from __future__ import annotations

from typing import final, override

from xtr_dependency_injection import Bundle, ContainerBuilder, ServiceConfigurator, as_bundle

from .<name>_config import <Name>Config

__all__ = ["<Name>Bundle"]


@final
@as_bundle("<name>", config=<Name>Config)
class <Name>Bundle(Bundle[<Name>Config]):
    """Registers the <name> services under the container."""

    @override
    def load_extension(
        self,
        config: <Name>Config,
        services: ServiceConfigurator,
        builder: ContainerBuilder,
    ) -> None:
        """Register services on the container from ``config``."""
        del builder, config, services  # replace with real registrations
# src/xtr_<name>/bundle/__init__.py
"""The xtr-dependency-injection bundle for xtr-<name>."""

from __future__ import annotations

from .<name>_bundle import <Name>Bundle
from .<name>_config import <Name>Config

__all__ = ["<Name>Bundle", "<Name>Config"]

A package with a bundle also advertises it — the [project.entry-points] block in the pyproject.toml above — and its README carries a Use in an application section (see the skeleton below). Drop both for a package without a bundle.

Tests

Unit tests mirror src/xtr_<name>/ one-for-one under tests/unit/. Every bundle has a zero-config test:

# tests/unit/bundle/test_<name>_bundle.py
"""The <name> bundle honours the zero-config contract."""

from __future__ import annotations

import pytest
from xtr_dependency_injection.testing import assert_zero_config

from xtr_<name>.bundle import <Name>Bundle


@pytest.mark.anyio
async def test_it_builds_and_boots_with_no_configuration() -> None:
    await assert_zero_config(<Name>Bundle)
# tests/conftest.py
"""Shared test fixtures."""

from __future__ import annotations

import pytest


@pytest.fixture
def anyio_backend() -> str:
    return "asyncio"

README skeleton

<div align="center">

# xtr-<name>

**<one-line pitch>.**

</div>

---

## Why?

## Install

```sh
uv add xtr-<name>
```

## Quick start

## Use in an application

Everything adding this package to an application on
[xtr-dependency-injection](../xtr-dependency-injection) takes — and, read backwards, what
removing it undoes.

- **Install** — `uv add xtr-<name>`; the third-party backends it offers as extras (`[redis]`,
  `[postgres]`, …), and the xtr packages it works with when installed beside it — never an extra:
  installing the package is what turns the integration on.
- **Recipe** — `uv run xtr-recipes recipes:sync` does what *Activate*, *Configure*, *Environment*
  and *Ignore* list, from the recipe shipped beside the bundle; keep `recipe/` true when those
  bullets change (see [xtr-recipes](../xtr-recipes)).
- **Activate** — `<Name>Bundle: {"all": True}` in `BUNDLES` in `<app>/config/bundles.py`, imported
  from `xtr_<name>.bundle`.
- **Brings along** — the bundles its `@required_bundle` pulls in, and when.
- **Configure** — what the zero-config path gives; then the `<app>/config/packages/<name>.py`
  `@configure` function that changes it, linking to *Kernel / bundle*. A bundle listed for `dev`
  only shows it in `<app>/config/packages/dev/<name>.py` instead: only a `dev` build imports that
  folder, and production does not install the package.
- **Environment** — variables the application must set, or "nothing".
- **Ignore** — `.gitignore` lines for files it writes into the project, or "nothing".
- **Remove** — every step above, undone, ending with `uv remove xtr-<name>`.
- **Check** — the command that shows it working, usually `debug:bundles`.

Add **Entry point**, **Load** or **Run** only when the package needs one.

## Kernel / bundle

## Development

## License

MIT — see [LICENSE](LICENSE).

Agent skill

A package an application lists directly ships a skill at src/xtr_<name>/.agents/skills/xtr-<name>/SKILL.md, so a coding agent in that application can learn the package from the version it installed. The application registers them with uvx library-skills --all, which links in every skill its installed packages ship — rerun it after adding a package. The rules for what a skill holds are in AGENTS.md; xtr-clock's is a short example.

Registering the package

  1. Add xtr-<name> = { workspace = true } to [tool.uv.sources] in the root pyproject.toml.
  2. Add a row to the Packages table at the top of this README.
  3. Run uv lock from the repository root.
  4. Create the empty xterr/python-xtr-<name> repository on GitHub (CI's split job populates it once CI passes on a push to main), and add it to the split GitHub App's installation before pushing. The app's token is requested for every read-only repository at once, so one repository it cannot reach fails the split for all of them.
  5. Register a pending trusted publisher for xtr-<name> on PyPI before its first release.

If a sibling's version leaves a range, uv lock fails; that is the reminder to update the range.

Layout

python-xtr/
├── .github/workflows/  # ci (with the split into the read-only copies), release
├── packages/
│   └── xtr-<name>/
│       ├── .github/    # only for the read-only copy: closes its pull requests
│       ├── src/xtr_<name>/
│       ├── tests/
│       ├── pyproject.toml
│       ├── README.md
│       └── LICENSE
├── examples/bookshop/  # an application on every package — its own uv project, on the shared version
├── scripts/release.py  # one version for every package
├── pyproject.toml      # workspace root: members and sources, never published
└── uv.lock             # the packages' lockfile; the example has its own

Credits

Most packages are translations into Python of PHP libraries — chiefly Symfony's components, along with Monolog, Flysystem, Doctrine Migrations and LexikJWTAuthenticationBundle. CREDITS.md lists each project and the packages translated from it.

License

MIT — see LICENSE. Every package ships its own LICENSE, carrying the copyright lines of the projects it was translated from.

About

Small, typed, async-ready building blocks for Python, one package each: clock, console, dependency injection, logging, messenger and their contracts.

Topics

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages