kyro

Symfony-style attribute routing for Django: declare routes with decorators directly on your views and controllers instead of maintaining a long urls.py.

Status: pre-alpha, under active development.

Installation

pip install kyro-routing   # or: uv add kyro-routing

The package is imported as kyro. Add "kyro" to INSTALLED_APPS for the management commands and the system checks.

Quick start

# blog/views.py
from django.http import HttpResponse
from kyro import route

from blog.models import Post


@route("/hello/{name}", name="hello")
def hello(request, name):
    return HttpResponse(f"Hello {name}")


@route("/blog", name="blog_")
class BlogController:
    @route("", name="index", methods="GET")
    def index(self, request): ...

    @route("", name="create", methods="POST")
    def create(self, request): ...

    @route(r"/page/{page<\d+>?1}", name="list")  # before /{slug}, which would catch /page
    def list(self, request, page: int): ...

    @route("/{slug}", name="show")
    def show(self, request, post: Post):  # fetched by slug, 404 if missing
        ...

# project/urls.py
import kyro

urlpatterns = kyro.discover()  # imports the `views` module of every installed app

Routes are plain Django URL patterns: reverse("blog_show", kwargs={"slug": "hello"}) and {% url "blog_index" %} work as usual, and so do include() and namespaces.

Paths

Both syntaxes are accepted, even in the same path:

Trailing parameters with a default (inline or in defaults=) are optional: /blog/{page?1} matches /blog and /blog/2.

@route arguments

Several routes may share a path with different methods: kyro dispatches each request to the right view. @route can be stacked to give a view several routes.

What can be routed

• Functions, sync or async. Put @route above or below other decorators.
• Methods of any class: the class is instantiated for each request. A @route on the class is a prefix (path, name, requirements, defaults, methods) for its methods. Classes defined inside a function must be decorated (@route() for no prefix).
• A class with __call__ and no routed method, or a Django View: the class route is the route of the class itself.

Parameter conversion

Annotated view arguments are converted from the URL:

• int, float, Decimal, bool, UUID, date, datetime, Enum: an invalid value is a 404.

• Django models, fetched like Symfony's entity resolver:

  • {post} for post: Post: lookup by primary key;
  • {slug} for post: Post: lookup by fields named like URL parameters (the parameter is only passed to the view if its signature accepts it);
  • post: Annotated[Post, MapModel(slug="post_slug")]: explicit mapping.

  A missing object is a 404, or None when the annotation is optional (Post | None).

Debugging routes

With "kyro" in INSTALLED_APPS, manage.py debug_router lists every route of the project, kyro or not, in matching order:

$ python manage.py debug_router
 -------------- ---------- ------------------
  Name           Method     Path
 -------------- ---------- ------------------
  blog_index     GET|HEAD   /blog
  blog_create    POST       /blog
  blog_show      ANY        /blog/{slug}
 -------------- ---------- ------------------

• debug_router blog_show shows one route in detail: Django routes, requirements, defaults, priority, view and the file and line where it is declared. A partial name shows the detail when it matches one route, the list of matches otherwise.
• --show-views adds the view of each route to the list, --format json outputs JSON and --urlconf inspects another URLconf than ROOT_URLCONF.

manage.py router_match tells which route serves a request, method dispatch included:

$ python manage.py router_match /blog --method POST
 ------------- ---------- ------- --------------------
  Name          Method     Path    Result
 ------------- ---------- ------- --------------------
  blog_index    GET|HEAD   /blog   method not allowed
  blog_create   POST       /blog   match
 ------------- ---------- ------- --------------------

Route 'blog_create' matches.

It then shows the route in detail with the kwargs its view receives. Routes matching the path but not the method, or hidden by an earlier route (shadowed), are listed; -v 2 lists every route. The command fails when no route serves the request (404 or 405). --format json and --urlconf work as for debug_router.

System checks

With "kyro" in INSTALLED_APPS, manage.py check (and runserver) warns about:

Silence one with SILENCED_SYSTEM_CHECKS = ["kyro.W003"].

Settings

• KYRO_DISCOVER (default ["views"]): app submodules imported by kyro.discover().

kyro.discover(["blog"]) imports the given modules (for a package, its KYRO_DISCOVER submodules too) and returns only their routes, to mount them under a prefix: path("blog/", include(kyro.discover(["blog"]))).

Development

uv sync              # create .venv and install dependencies
uv run pytest        # run the test suite
uv run ruff check .  # lint
uv run ruff format . # format
uv run python -m mypy # type check (strict)

Releasing

1. Set the version in src/kyro/__init__.py (__version__), and in CHANGELOG.md rename [Unreleased] to [x.y.z] - YYYY-MM-DD and update the links at the bottom.
2. Optionally, try the release out on TestPyPI: Actions → Release → Run workflow.
3. Commit, tag and push: git tag vx.y.z && git push origin main vx.y.z. The Release workflow publishes to TestPyPI, then PyPI.