Luxon routes incoming requests to resources based on a route path defined. The paths are defined for routes differently depending on the responder type. There are two types of responders:
- Responder Class known as Resources.
- Function known as Resource.
If the path requested by the client matches the template for a given route, the request is then passed on to the associated responder for processing. This responder then returns relevant payload.
If no route matches the request, then luxon.exceptions.NotFound is raised. This will result in sending a 404 response back to the client.
Note: The router is global for application.
Standard Routes Stanard routes are faster and simply a dictionary lookup routine. It automatically trims ‘/’ from route for more predictive matching.
Keyword Expression Routes These are pretty fast and scaleable using compiled router. A field expression consists of a bracketed field name. For example ‘/users/{domain}/{id}’
These are provided as kwargs to the responder.
Regex Routes These routes solves specific requirements. However they do not provide keyword arguements at this point to the responder. Please note that regex routes are far slower than ‘Standerd Routes’ or ‘Keyword Expression Routes’. They should only be used if deemed absolutly neccesary. They slow down the more they are used. In reality if these route matches are determined by scanning through a list until the compiled RE expression has found a match. Hence some cases order will be important.
However if you only use a couple of these, there will be no major performance impact. They are also only validated once ‘Standard routes’ and ‘Keyword Expression routes’ have found no matches. Hence it will NOT impact on performance of other route types.
Regex route follows the format of ‘regex:expression’. Its important that ‘regex:’ is prepended since its used to determine the processing needed for the route.
Refer to Responders for a usage example.
luxon.core.router.
Router
[source]¶Simple Router Interface.
The router is used to index and return views based on url and method.
routes
¶List of tuples containing routes. e.g. [ ( ‘GET’, ‘/test’, ‘rule1’, resource_view_object), ]
Type: | list |
---|
add
(methods, route, resource, tag=None, cache=0)[source]¶Add route to view.
The route() method is used to associate a URI template with a resource. Luxon then maps incoming requests to resources based on these templates.
URI Template example: “/music/rock”
If the route’s template contains field expressions, any responder that desires to receive requests for that route must accept arguments named after the respective field names defined in the template.
A field expression consists of a bracketed field name. For example, given the following template: “/music/{genre}”
Parameters: |
|
---|---|
Keyword Arguments: | |
tag (str) – Used to identify rule_set to apply. default: ‘None’ |
find
(method, route)[source]¶Route based on Request Object.
Search for a route that matches the given partial URI.
Parameters: |
|
---|
Luxon uses external code from the Falcon WSGI library for some router operations. To view the license please refer to Falcon License
luxon.ext.falcon.compiled.
CompiledRouter
[source]¶Fast URI router which compiles its routing logic to Python code.
Generally you do not need to use this router class directly, as an instance is created by default when the falcon.API class is initialized.
The router treats URI paths as a tree of URI segments and searches by checking the URI one segment at a time. Instead of interpreting the route tree for each look-up, it generates inlined, bespoke Python code to perform the search, then compiles that code. This makes the route processing quite fast.
add_route
(uri_template, method_map, resource, tag=None, cache=0)[source]¶Adds a route between a URI path template and a resource.
Parameters: |
|
---|
find
(uri, req=None)[source]¶Search for a route that matches the given partial URI.
Parameters: | uri (str) – The requested path to route. |
---|---|
Keyword Arguments: | |
req (object) – The Request object that will be passed to
the routed responder. Currently the value of this
argument is ignored by CompiledRouter .
Routing is based solely on the path. |
|
Returns: |
|
Return type: | tuple |
luxon.ext.falcon.compiled.
CompiledRouterOptions
[source]¶Defines a set of configurable router options.
An instance of this class is exposed via API.router_options
for configuring certain CompiledRouter
behaviors.
converters
¶Represents the collection of named converters that may be referenced in URI template field expressions. Adding additional converters is simply a matter of mapping an identifier to a converter class:
api.router_options.converters['mc'] = MyConverter
The identifier can then be used to employ the converter within a URI template:
api.add_route('/{some_field:mc}', some_resource)
Converter names may only contain ASCII letters, digits, and underscores, and must start with either a letter or an underscore.
Warning
Converter instances are shared between requests. Therefore, in threaded deployments, care must be taken to implement custom converters in a thread-safe manner.
luxon.ext.falcon.converters.
BaseConverter
[source]¶Abstract base class for URI template field converters.
luxon.ext.falcon.converters.
IntConverter
(num_digits=None, min=None, max=None)[source]¶Converts a field value to an int.
Identifier: int
Keyword Arguments: | |
---|---|
|
luxon.ext.falcon.converters.
DateTimeConverter
(format_string='%Y-%m-%dT%H:%M:%SZ')[source]¶Converts a field value to a datetime.
Identifier: dt
Keyword Arguments: | |
---|---|
format_string (str) – String used to parse the field value
into a datetime. Any format recognized by strptime() is
supported (default '%Y-%m-%dT%H:%M:%SZ' ). |
luxon.ext.falcon.converters.
UUIDConverter
[source]¶Converts a field value to a uuid.UUID.
Identifier: uuid
In order to be converted, the field value must consist of a string of 32 hexadecimal digits, as defined in RFC 4122, Section 3. Note, however, that hyphens and the URN prefix are optional.