darkheir/falcon-sorting-hook

falcon-sorting-hook

A small falcon hook to parse sorting elements from the request.

Usage

The easiest way to use this hook is the following:

class Resource:
    sorting_fields = ("foo", "bar")  # List of fields allowed for sorting

    @falcon.before(SortingHook())
    def on_get(self, req, resp, user):
        # Here req['context']['sort'] is set

The Hook will look in the query parameters for parameters looking like sort=value.

The default sorting order is ascending. To sort in a descending order a minus (-) sign needs to be specified before the value. i.e. sort=-value

It is possible to specify multiple sorting values by separating them with a comma. i.e. sort=-value1,value2

It will create a list in the request context accessible at req.context['sort']. This list consists of tuples where the first element is the name of the field to sort on and the second the order to follow (either ASC or DESC)

i.e. [('foo', 'ASC'), ('bar', 'DESC')].

Configuration options

Allowing fields for sorting

For security reasons, the fields allowed for sorting must be specified in the sorting_fields attribute of the resource.

All the fields not defined in it will be discarded by the hook.

Default sorting order

It is possible to specify a default sorting order by setting the default_sorting attribute in the resource.

This attribute must be a string or a tuple that respects the convention we have for the request parameter.

The attributes specified as the default order must also be part of sorting_fields.

Examples:

default_sorting = '-foo'
# or
default_sorting = ('foo', '-bar')

Hook configuration

One parameter can be passed to the hook:

• sort_query_key : The name of the key used in the query to sort data. Default: sort.

Example:

@falcon.before(PaginationFromRequestHook(
    sort_query_key='order',
))
def on_get(self, req, resp, user):
    # Get request