Metadata-Version: 1.1
Name: djangorestframework-extras
Version: 0.2.1
Summary: Autogenerate API's for models. Expose core Django functionality. Validate against existing forms.
Home-page: http://github.com/praekelt/djangorestframework-extras
Author: Praekelt Consulting
Author-email: dev@praekelt.com
License: BSD
Description: Django Rest Framework Extras
        ############################
        .. image:: https://travis-ci.org/praekelt/djangorestframework-extras.svg?branch=develop
            :target: https://travis-ci.org/praekelt/djangorestframework-extras?branch=develop
        .. image:: https://coveralls.io/repos/github/praekelt/djangorestframework-extras/badge.svg
            :target: https://coveralls.io/github/praekelt/djangorestframework-extras
        
        **DRFE generates RESTful API's for any Django models. It builds on Django Rest Framework.**
        
        .. contents:: Table of Contents
           :depth: 1
        
        Prerequisite
        ============
        #. pip install ``djangorestframework``
        
        #. Add ``rest_framework`` to your ``INSTALLED_APPS`` setting in ``settings.py``.
        
        
        Installation
        ============
        
        #. Install or add ``djangorestframework-extras`` to your Python path.
        
        #. Add ``rest_framework_extras`` to your ``INSTALLED_APPS`` setting in ``settings.py``.
        
        
        Feature List
        ============
        
        - Generating default serializers and viewsets for all known applications to create RESTful API's.
        - Registering all viewsets known to the application with the Django Rest Framework router.
        - Custom serializers and permissions for the default user, the staff users and superusers.
        - Custom FormMixin that Delegates validation to a normal Django form.
        - Custom Hyperlink fields and serializer, ``HyperlinkedRelatedField`` and ``HyperlinkedModelSerializer``
        
        
        Usage
        =====
        
        User permissions and the custom UsersViewSet
        --------------------------------------------
        
        ``djangorestframework-extras`` provides a custom ViewSet ``UsersViewSet`` with serializers and permissions for the default user, the staff user and the superuser.
        
        Register UsersViewSet through the DefaultRouter::
        
            from rest_framework_extras.users.viewsets import UsersViewSet
        
            router = routers.DefaultRouter()
        
            router.register(r'users', UsersViewSet, 'user')
        
        Discovery and registration of ViewSets
        --------------------------------------
        
        Enable discovery and registration of default serializers and viewsets by adding the following to ``urls.py``::
        
            from rest_framework import routers
            import rest_framework_extras
            router = routers.DefaultRouter()
        
            rest_framework_extras.discover(router)
            rest_framework_extras.register(router)
        
            urlpatterns = [
                url(r"^api/(?P<version>(v1))/", include(router.urls))
            ]
        
        **Going through the code line by line:**
        
        #. Line 1 & 3: The router and DefaultRouter classes connects the views and urls automatically and also creates the API root.
        #. Line 5: The new discover function generates default serializers and viewsets. This function should be run before normal registration.
        #. Line 6: The new register function registers all viewsets (including the UsersViewSet), overriding any items already registered with the same name.
        #. Line 9: Define the urls by including router.urls.
        
        Available Settings
        ------------------
        
        ``REST_FRAMEWORK_EXTRAS``
        
        **blacklist**: A dictionary of the models to blacklist. By default the following models are blacklisted::
        
           "REST_FRAMEWORK_EXTRAS": {
              "blacklist": {
                   "sessions-session": {},
                   "admin-logentry": {}
              },
              "authentication-classes": (SessionAuthentication, BasicAuthentication),
              "permission-classes": (DjangoModelPermissions,)
           }
        
        Tips
        ====
        
        Change the name of the registered user model by changing the ``mapping`` parameter, such as::
        
            rest_framework_extras.register(router, mapping=(("user", UsersViewSet),))
        
        Restrict models that will be displayed through the Django Rest Framework by using the ``only`` and ``override`` parameters. Define a comma separated list, such as::
        
            rest_framework_extras.discover(router, only=["auth-user", "auth-permission"])
        
        todo: document override
        
        Unit Testing
        ============
        
        Run tests by using the following command::
        
            python manage.py test rest_framework_extras.tests --settings=rest_framework_extras.tests.settings.19
        
        License
        =======
        
        Please see the License requirements in the LICENSE file of this repository.
        
        
Platform: UNKNOWN
Classifier: Programming Language :: Python
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
