http.router
import http.router
httplifts part of this module out to its own top level; each name below is shown with the path that reaches it. Anything still spelledhttp.router.*needsimport http.router.
Matching a request to a handler.
Router holds the route table, Route is one pattern, and RouteMatch
is the result of matching including whatever the path parameters
captured. Patterns support named parameters and wildcards, and the
router answers 405 rather than 404 when a path exists under a
different method.
Classes
Route
class http.Route
One registered route.
- printable — has a
@to_string(), soechoandprint()show something useful
Fields
| Field | Type | Description |
|---|---|---|
method | string | The method this route answers, uppercased. |
pattern | string | The pattern it was registered with, e.g. '/users/:id'. |
handler | function | The function called when the route matches, taking the request and the response. |
name | ?string | An optional name, so a URL can be built from the route rather than written out again at every call site. |
Constructor
http.Route(method, pattern, handler, name)
Route.to_string()
http.Route.to_string()
RouteMatch
class http.router.RouteMatch
The result of asking a router about a request.
Fields
| Field | Type | Description |
|---|---|---|
route | ?Route | The matched route, or nil when nothing matched. |
params | dict | Path parameters captured from the pattern. |
allowed | list | When a path matched but the method did not, the methods that path does answer - which is exactly what a… |
Constructor
http.router.RouteMatch(route, params, allowed)
RouteMatch.is_match()
http.router.RouteMatch.is_match() -> bool
Whether a route was found.
Returns bool
RouteMatch.is_method_mismatch()
http.router.RouteMatch.is_method_mismatch() -> bool
Whether the path exists but not for the requested method, which calls
for a 405 rather than a 404.
Returns bool
Router
class http.Router
Matches request paths to handlers.
Patterns are made of literal segments, named parameters, and an optional trailing catch-all:
| Pattern | Matches | Captures |
|---|---|---|
/users | /users | |
/users/:id | /users/42 | id = '42' |
/users/:id/posts | /users/42/posts | id = '42' |
/static/ + *path | /static/css/site.css | path = 'css/site.css' |
A literal segment always beats a parameter, and a parameter always beats
a catch-all, so /users/new and /users/:id can coexist and the
specific one wins - regardless of which was registered first, which is a
property a list-of-patterns router cannot offer.
Matching happens over a trie, so a router with a thousand routes costs the same per request as one with ten.
Constructor
http.Router()
Router.add()
http.Router.add(method: string, pattern: string, handler, name: ?string) -> Route
Registers handler for method requests to pattern.
Parameters
method(string)pattern(string)handler(function(2)) — called with the request and responsename(?string) — a name to look the route up by later
Returns Route
Raises HttpError if the pattern is malformed, or if the same
method and pattern were already registered
Router.match()
http.Router.match(method: string, path: string) -> RouteMatch
Finds the route for method and path.
When the path matches but the method does not, the returned match
carries the methods that path does answer, so the caller can send a
405 with a correct Allow header instead of a misleading 404.
HEAD falls back to the GET route when no HEAD route was
registered, since RFC 9110 §9.3.2 defines HEAD as GET without the body,
and the response writer drops the body anyway.
Parameters
method(string)path(string)
Returns RouteMatch
Router.url_for()
http.Router.url_for(name: string, params: ?dict) -> string
Builds the path for a named route, substituting params into its
pattern.
router.add('GET', '/users/:id', show, 'user.show')
router.url_for('user.show', { id: 42 }) # '/users/42'
Parameters
name(string)params(?dict)
Returns string
Raises HttpError if no route has that name, or a parameter the
pattern needs was not supplied
Router.routes()
http.Router.routes() -> list
Every registered route.
Returns list
Router.length()
http.Router.length() -> number
How many routes are registered.
Returns number
2026, Richard Ore and Zuri contributors