kyro-routing 0.1.0__tar.gz

kyro_routing-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,60 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v6
+      - run: uv sync --locked
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run python -m mypy
+
+  test:
+    name: test (Python ${{ matrix.python }}, Django ${{ matrix.django }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # Lowest and highest Python supported by each Django version.
+        include:
+          - { python: "3.10", django: "4.2" }
+          - { python: "3.12", django: "4.2" }
+          - { python: "3.10", django: "5.2" }
+          - { python: "3.13", django: "5.2" }
+          - { python: "3.12", django: "6.0" }
+          - { python: "3.14", django: "6.0" }
+          - { python: "3.12", django: "6.1" }
+          - { python: "3.14", django: "6.1" }
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv sync --locked
+      - run: uv pip install "django~=${{ matrix.django }}.0"
+      - run: uv run --no-sync pytest
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v6
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

kyro_routing-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,68 @@
+name: Release
+
+# A version tag (v0.1.0) publishes to TestPyPI, then PyPI.
+# A manual run publishes to TestPyPI only, to try a release out.
+on:
+  push:
+    tags: ["v[0-9]*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v6
+      - run: uv build
+      - name: Check that the tag matches the package version
+        if: github.ref_type == 'tag'
+        run: |
+          wheel="dist/kyro_routing-${GITHUB_REF_NAME#v}-py3-none-any.whl"
+          if [ ! -f "$wheel" ]; then
+            echo "::error::Tag $GITHUB_REF_NAME does not match the built package: $(ls dist)"
+            exit 1
+          fi
+      - name: Check that the wheel installs and imports
+        run: uv run --isolated --no-project --with dist/*.whl python -c "import kyro.checks, kyro; print(kyro.__version__)"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  testpypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/kyro-routing
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          # A version already tried out with a manual run is kept as is.
+          skip-existing: true
+
+  pypi:
+    needs: testpypi
+    if: github.ref_type == 'tag'
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/kyro-routing
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

kyro_routing-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Tooling
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+*.sqlite3

kyro_routing-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

kyro_routing-0.1.0/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this
+project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-01
+
+First release.
+
+### Added
+
+- `@route` decorator for functions (sync and async), methods of any class, classes with
+  `__call__` and Django class-based views. On a class with routed methods, the class route
+  is a prefix for path, name, requirements, defaults and methods.
+- Paths in Django syntax (`<int:id>`) and Symfony syntax (`{id}`, `{id<\d+>}`, `{page?1}`,
+  `{page?}`), mixed freely. Trailing parameters with a default are optional.
+- Route options: `name` (generated when omitted), `methods`, `requirements`, `defaults` and
+  `priority`. Several routes can share a path with different methods; other methods get a
+  405 with an `Allow` header.
+- Parameter conversion from annotations: `int`, `float`, `Decimal`, `bool`, `UUID`, `date`,
+  `datetime` and `Enum`, plus Django models looked up by primary key, by field or with
+  `MapModel`. Invalid values and missing objects are a 404.
+- `kyro.discover()` to build the URL patterns from the `views` modules of the installed
+  apps, or from given modules; `Router` for separate sets of routes.
+- `debug_router` management command, listing the routes of the project or showing one in
+  detail.
+- `router_match` management command, telling which route serves a request.
+- System checks: shadowed routes (`kyro.W001`), shared route names (`kyro.W002`), routes
+  missing from the URLconf (`kyro.W003`) and ignored defaults (`kyro.W004`).
+- Support for Python 3.10 to 3.14 and Django 4.2, 5.2, 6.0 and 6.1.
+
+[Unreleased]: https://github.com/mistermerlin/kyro-routing/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/mistermerlin/kyro-routing/releases/tag/v0.1.0

kyro_routing-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aziz Ouattara
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kyro_routing-0.1.0/PKG-INFO

@@ -0,0 +1,222 @@
+Metadata-Version: 2.5
+Name: kyro-routing
+Version: 0.1.0
+Summary: Symfony-style attribute routing for Django: declare routes with decorators on views and controllers.
+Project-URL: Homepage, https://github.com/mistermerlin/kyro-routing
+Project-URL: Repository, https://github.com/mistermerlin/kyro-routing.git
+Project-URL: Issues, https://github.com/mistermerlin/kyro-routing/issues
+Project-URL: Changelog, https://github.com/mistermerlin/kyro-routing/blob/main/CHANGELOG.md
+Author-email: Aziz Ouattara <datoulobaben@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: decorator,django,router,routing,symfony,urls
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.2
+Classifier: Framework :: Django :: 6.0
+Classifier: Framework :: Django :: 6.1
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: django>=4.2
+Description-Content-Type: text/markdown
+
+# kyro
+
+[![CI](https://github.com/mistermerlin/kyro-routing/actions/workflows/ci.yml/badge.svg)](https://github.com/mistermerlin/kyro-routing/actions/workflows/ci.yml)
+
+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
+
+```bash
+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
+
+```python
+# 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
+        ...
+```
+
+```python
+# 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:
+
+| Syntax | Meaning |
+|---|---|
+| `<name>`, `<int:id>` | Django parameter and converter |
+| `{name}` | parameter (anything but `/`) |
+| `{id<\d+>}` | parameter with a regex requirement |
+| `{page?1}` | optional parameter with default `"1"` |
+| `{page?}` | optional parameter with default `None` |
+
+Trailing parameters with a default (inline or in `defaults=`) are optional:
+`/blog/{page?1}` matches `/blog` and `/blog/2`.
+
+## `@route` arguments
+
+| Argument | |
+|---|---|
+| `path` | the path, relative to the class prefix if any |
+| `name` | route name, appended to the class `name` prefix; generated when omitted |
+| `methods` | `"GET"` or `["GET", "POST"]`; others get a 405. `GET` also allows `HEAD` |
+| `requirements` | `{"id": r"\d+"}` |
+| `defaults` | defaults of optional parameters and extra kwargs passed to the view |
+| `priority` | higher priority routes are matched first; otherwise declaration order |
+
+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:
+
+```text
+$ 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:
+
+```text
+$ 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:
+
+| Id | Problem |
+|---|---|
+| `kyro.W001` | a route without parameters is served by an earlier route, for all or some of its methods (`/blog/{slug}` declared before `/blog/new`) |
+| `kyro.W002` | a route name is shared with other routes, so `reverse()` only returns one of them |
+| `kyro.W003` | routes declared with `@route` are not in the URLconf (`kyro.discover()` forgotten?) |
+| `kyro.W004` | a parameter has a default but is not trailing, so it cannot be omitted |
+
+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
+
+```bash
+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.

kyro_routing-0.1.0/README.md

@@ -0,0 +1,190 @@
+# kyro
+
+[![CI](https://github.com/mistermerlin/kyro-routing/actions/workflows/ci.yml/badge.svg)](https://github.com/mistermerlin/kyro-routing/actions/workflows/ci.yml)
+
+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
+
+```bash
+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
+
+```python
+# 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
+        ...
+```
+
+```python
+# 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:
+
+| Syntax | Meaning |
+|---|---|
+| `<name>`, `<int:id>` | Django parameter and converter |
+| `{name}` | parameter (anything but `/`) |
+| `{id<\d+>}` | parameter with a regex requirement |
+| `{page?1}` | optional parameter with default `"1"` |
+| `{page?}` | optional parameter with default `None` |
+
+Trailing parameters with a default (inline or in `defaults=`) are optional:
+`/blog/{page?1}` matches `/blog` and `/blog/2`.
+
+## `@route` arguments
+
+| Argument | |
+|---|---|
+| `path` | the path, relative to the class prefix if any |
+| `name` | route name, appended to the class `name` prefix; generated when omitted |
+| `methods` | `"GET"` or `["GET", "POST"]`; others get a 405. `GET` also allows `HEAD` |
+| `requirements` | `{"id": r"\d+"}` |
+| `defaults` | defaults of optional parameters and extra kwargs passed to the view |
+| `priority` | higher priority routes are matched first; otherwise declaration order |
+
+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:
+
+```text
+$ 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:
+
+```text
+$ 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:
+
+| Id | Problem |
+|---|---|
+| `kyro.W001` | a route without parameters is served by an earlier route, for all or some of its methods (`/blog/{slug}` declared before `/blog/new`) |
+| `kyro.W002` | a route name is shared with other routes, so `reverse()` only returns one of them |
+| `kyro.W003` | routes declared with `@route` are not in the URLconf (`kyro.discover()` forgotten?) |
+| `kyro.W004` | a parameter has a default but is not trailing, so it cannot be omitted |
+
+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
+
+```bash
+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.