Metadata-Version: 1.0
Name: falcon-resource-factory
Version: 0.0.2
Summary: A simple falcon library that allows defining a single resource class to handle requests for a single item as well as multiple items
Home-page: https://github.com/loanzen/falcon-resource-factory
Author: Ritesh Kadmawala
Author-email: ritesh@loanzen.in
License: MIT
Description: Falcon Resource Factory
        ~~~~~~~~~~~~~~~~~~~~~~~
        
        |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.
        
        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 <https://github.com/loanzen/falcon-resource-factory/issues>`__
        
        ##### Bug Reports
        
        You may file bug reports on `Github
        repository <https://github.com/loanzen/falcon-resource-factory/issues>`__
        
        ##### 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 <https://github.com/loanzen/falcon-resource-factory/issues>`__
        
        ##### Tests
        
        All pull request should pass the test suite which can launched simply
        with
        
        ::
        
            python setup.py test
        
        .. |version| image:: https://img.shields.io/pypi/v/falcon-resource-factory.svg
           :target: https://pypi.python.org/pypi/falcon-resource-factory/
        .. |Build Status| image:: https://travis-ci.org/loanzen/falcon-resource-factory.svg?branch=master
           :target: https://travis-ci.org/loanzen/falcon-resource-factory
        .. |License| image:: http://img.shields.io/:license-mit-blue.svg
           :target: https://pypi.python.org/pypi/falcon-resource-factory/
        .. |Wheel| image:: https://img.shields.io/pypi/wheel/factory-resource-factory.svg
           :target: https://pypi.python.org/pypi/falcon-resource-factory/
        
Platform: UNKNOWN
