Routes

Routes handle HTTP requests. Feather discovers modules in routes/api/ and routes/pages/ automatically.

routes/api/users.py

from feather import api, auth_required, inject
from services import UserService

@api.get('/users')
@inject(UserService)
def list_users(user_service):
    return {'users': user_service.list_all()}

@api.post('/users')
@auth_required
@inject(UserService)
def create_user(user_service, email: str, username: str):
    user = user_service.create(email=email, username=username)
    return {'user': user}, 201

Prefixes

Directory	Mounted at
`routes/api/*.py`	`/api/*`
`routes/pages/*.py`	`/*`

Keep routes thin

Parse the request, call a service, return a response. A handler doing work that belongs in a service is reported by feather check as the fat-route warning.

Services

Where business logic goes, with transactions handled for you.

Exceptions

Raise a typed exception and it becomes the right JSON response.

Redirecting after an action

Most actions end by sending the browser somewhere with a message. redirect_with_toast does both, and works for an htmx request and a plain form post alike: htmx gets an HX-Redirect, a normal request a 302, and the toast shows on the page that loads.

from feather import redirect_with_toast

@page.post('/projects/<project_id>/archive')
@auth_required
def archive_project(project_id):
    ProjectService().archive(project_id, current_user.id)
    return redirect_with_toast(url_for('page.dashboard'), "Project archived.")

For an htmx-only redirect with no message, htmx_redirect(url) sends just the header.

Auth decorators

Every route should carry one, or declare itself public. A route with no auth decorator is reported as the unprotected-route warning. A deliberately public one carries a # feather: public comment in its module. See Authentication for the full decorator set.

Template filters, globals and error pages

routes/pages/template_helpers.py

from feather import page
from feather.exceptions import NotFoundError


@page.app_template_filter("timeago")
def timeago(value): ...


@page.app_context_processor
def inject_permissions():
    return {"can_edit": can_edit()}


@page.app_errorhandler(NotFoundError)
def not_found(error): ...

The test suite builds its app from TestingConfig and never imports app.py, so anything registered there exists when you run the app and is missing in every test. The blueprint’s app_* hooks reach every app Feather builds from the project.

Discovery skips any module whose name starts with an underscore. routes/pages/_helpers.py is never imported and its decorators never run, so name it template_helpers.py.

Seeing what is registered

feather routes

Generate CRUD scaffolding with:

feather generate route users --model User     # API CRUD routes
feather generate route dashboard --page       # page route with template

Get started

Tutorial: build a Kanban app

Building the UI

Backend

Features

Tooling

Testing

Deployment

Prefixes

Keep routes thin

Services

Exceptions

Redirecting after an action

Auth decorators

Template filters, globals and error pages

Seeing what is registered

​Prefixes

​Keep routes thin

Services

Exceptions

​Redirecting after an action

​Auth decorators

​Template filters, globals and error pages

​Seeing what is registered

Prefixes

Keep routes thin

Redirecting after an action

Auth decorators

Template filters, globals and error pages

Seeing what is registered