Skip to main content

A simple falcon library that allows defining a single resource class to handle requests for a single item as well as multiple items

Project description

version Build Status License Wheel

A simple falcon library that allows defining a single resource class to handle requests for a single item as well as multiple items. While though its not purely RESTful, sometimes you require your resource to support custom endpoints. The library allows you to define such custom endpoints as well as part of the same single resource class.


Install the library using pip, or easy_install.

$ pip install -U falcon-resource-factory


This library exposes a single class falcon_resource_factory.ResourceFactory which is used to add your single resource class to falcon as shown below.

import falcon
from falcon_resource_factory import ResourceFactory

api = falcon.API()

class Resource(object):
    def on_get(req, res, **kwargs):
        # Return single object

    def on_get_list(req, res, **kwargs):
        # Returns list of objects

resource_factory = ResourceFactory()
resource_factory.add_routes(app, '/res', Resource())

The ResourceFactory instance will create two separate resources internally called ResourceDetail and ResourceList for handling single item and list of items respectively and register them with falcon at appropriate routes. The generated resources have appropriate handlers for all http methods supported by your resource which in turn just wrappers around your resource handlers.

For eg for the resource defined above, the generated resources will look like as follows

class ResourceDetail(object):

    def on_get(req, res, **kwargs):
        resource.on_get(req, res, **kwargs):

class ResourceList(object):
    def on_get(req, res, **kwargs):
        resource.on_get_list(req, res, **kwargs):

Custom Detail Identifier

ResourceFactory creates the route for detail resource by appending a resource identifier to the passed route. By default detail identifier is id but you can change it by passing it to ResourceFactory during initialization

resource_factory = ResourceFactory(detail_identifier='uuid')

Custom Method Map

ResourceFactory by default maps HTTP methods to handlers in the resource by using <method> : on_<method> for detail resources and <method>: on_<method>_list for list resources. However both of them are configiurable during initialization of ResourceFactory. You can pass a mapping of HTTP methods to methods of your resources for both list and detail resources.

resource_factory = ResourceFactory(list_method_map={
    'GET': 'on_get_collection',
    'POST': 'on_post_collection'
}, detail_method_map={
    'GET': 'get_obj',
    'POST': 'post_obj'

class Resource(object):

    def on_get_collection(req, res, **kwargs)

    def on_post_collection(req, res, **kwargs)

    def get_obj(req, res, **kwargs)

    def post_obj(req, res, **kwargs)


Sometimes, you want to support api’s that are not CRUD. In such situations, purely RESTful approach suggests that you create more resources instead of defining custom verbs. However, sometime its easier to define custom endpoints/actions instead of mapping them to resources which might not be that straightforward. ResourceFactory support defining custom views by automatically creating separate resources for each custom view and registering with falcon. You need to pass a list of view specs to ResourceFactory during initialization and it takes care of rest

resource_factory = ResourceFactory(custom_views=[
        "route": "/action1/",
        "view": "action1",
        "methods": ['GET']
        "route": "/action2/",
        "view": "action2",
        "methods": ['POST']

class Resource(object):

    def on_get(req, res, **kwargs):

    def action1(req, res, **kwargs):

    def action2(req, res, **kwargs):

#### Contributing falcon-resource-factory is distributed under MIT License.

Fork the repository to your own account.

Clone the repository to a suitable location on your local machine.

$git clone

To update the project from within the project’s folder you can run the following command:

$git pull --rebase

##### Building

Install the project’s dependencies.

$pip install -r requirements.txt
$pip install -r requirements-dev.txt

##### Feature Requests

I’m always looking for suggestions to improve this project. If you have a suggestion for improving an existing feature, or would like to suggest a completely new feature, please file an issue with my Github repository

##### Bug Reports

You may file bug reports on Github repository

##### Pull Requests

Along with my desire to hear your feedback and suggestions, I’m also interested in accepting direct assistance in the form of new code or documentation. Please feel free to file pull requests against my Github repository

##### Tests

All pull request should pass the test suite which can launched simply with

python test

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for falcon-resource-factory, version 0.0.2
Filename, size File type Python version Upload date Hashes
Filename, size falcon_resource_factory-0.0.2-py2.py3-none-any.whl (9.1 kB) File type Wheel Python version 3.6 Upload date Hashes View
Filename, size falcon-resource-factory-0.0.2.tar.gz (5.6 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page