Falcon Resource Factory
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.
Installation
Install the library using pip, or easy_install.
$ pip install -U falcon-resource-factory
Usage
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
pass
def on_get_list(req, res, **kwargs):
# Returns list of objects
pass
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)
pass
def on_post_collection(req, res, **kwargs)
pass
def get_obj(req, res, **kwargs)
pass
def post_obj(req, res, **kwargs)
pass
CustomViews
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):
pass
def action1(req, res, **kwargs):
pass
def action2(req, res, **kwargs):
pass
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 https://github.com/loanzen/falcon-resource-factory.git
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 setup.py test
[1]: