Metadata-Version: 1.1
Name: djangorestframework-serializer-extensions
Version: 0.5.1
Summary: Extensions to DRY up Django Rest Framework serializers
Home-page: https://github.com/evenicoulddoit/django-rest-framework-serializer-extensions
Author: Ian Clark
Author-email: ianclark001@gmail.com
License: BSD
Description: Django REST framework serializer extensions
        ===========================================
        
        **A collection of useful tools to DRY up your Django Rest Framework
        serializers**
        
        Full documentation:
        http://django-rest-framework-serializer-extensions.readthedocs.io/
        
        |build-status-image| |coverage-status-image| |pypi-version|
        
        Overview
        --------
        
        Serializer extensions reduces the need for *very similar* serializers,
        by allowing the fields to be defined on a *per-view/request* basis.
        Fields can be whitelisted, blacklisted, and child serializers can be
        optionally expanded.
        
        Support for `HashIds <https://github.com/davidaurelio/hashids-python>`__
        is also provided. If you're currently exposing your internal IDs over a
        public API, we suggest you consider switching to HashIds instead.
        
        **:star: Lovingly open-sourced by
        `Housekeep <https://housekeep.com>`__.**
        
        Requirements
        ------------
        
        -  Python (2.7, 3.4, 3.5)
        -  `Django <https://github.com/django/django>`__ (1.8, 1.9, 1.10)
        -  `Django REST
           Framework <https://github.com/tomchristie/django-rest-framework>`__
           (3.3, 3.4, 3.5)
        -  `HashIds <https://github.com/davidaurelio/hashids-python>`__ (>1.0)
        
        Installation
        ------------
        
        Install using ``pip``:
        
        .. code:: bash
        
            $ pip install djangorestframework-serializer-extensions
        
        And add ``rest_framework_serializer_extensions`` to your
        ``INSTALLED_APPS`` setting:
        
        .. code:: py
        
            INSTALLED_APPS = (
                ...
                'rest_framework_serializer_extensions'
            )
        
        Basic Usage
        -----------
        
        To activate the serializer extensions, add the
        ``SerializerExtensionsMixin`` to your serializers:
        
        .. code:: py
        
            # serializers.py
            from rest_framework.serializers import ModelSerializer
            from rest_framework_serializer_extensions.serializers import SerializerExtensionsMixin
        
            ...
        
            class OwnerSerializer(SerializerExtensionsMixin, ModelSerializer):
                class Meta:
                    model = models.Owner
                    fields = ('id', 'name')
                    expandable_fields = dict(
                        organization=OrganizationSerializer,
                        cars=dict(
                            serializer=SkuSerializer,
                            many=True
                        )
                    )
        
        And add the ``SerializerExtensionsAPIViewMixin`` to your API views:
        
        .. code:: py
        
            from rest_framework.generics import RetrieveAPIView
            from rest_framework_serializer_extensions.views import SerializerExtensionsAPIViewMixin
        
            class RetriveOwnerAPIView(SerializerExtensionsAPIViewMixin, RetrieveAPIView):
                ...
        
        Examples
        --------
        
        Serializer extensions allows your API to re-use your serializers to fit
        a variety of use cases. The examples shown below use query parameters to
        modify the response, but individual views can interact with your
        serializers in much the same way.
        
        .. code:: js
        
            >>> GET /owner/x4F/
            {
              "id": 'x4F',
              "name": 'tyrell',
              "organization_id": 'kgD'
            }
        
        .. code:: js
        
            >>> GET /owner/x4F/?expand=organization
            {
              "id": 'x4F',
              "name": 'tyrell',
              "organization_id": 'kgD',
              "organization": {
                "id": "kgD",
                "name": "E Corp"
              }
            }
        
        .. code:: js
        
            >>> GET /owner/x4F/?expand=cars__model&exclude=name
            {
              "id": 'x4F',
              "organization_id": 'kgD',
              "cars": [
                {
                  "id": "wf9",
                  "variant": "P100D",
                  "model": {
                    "id": "ncX",
                    "name": "Model S"
                  }
                }
              ]
            }
        
        .. code:: js
        
            >>> GET /owner/x4F/?expand=cars&only=cars__variant
            {
              "cars": [
                {
                  "variant": "P100D",
                }
              ]
            }
        
        Testing
        -------
        
        Install testing requirements.
        
        .. code:: bash
        
            $ pip install -r requirements.txt
        
        Run with runtests.
        
        .. code:: bash
        
            $ ./runtests.py
        
        You can also use the excellent
        `tox <http://tox.readthedocs.org/en/latest/>`__ testing tool to run the
        tests against all supported versions of Python and Django. Install tox
        globally, and then simply run:
        
        .. code:: bash
        
            $ tox
        
        Documentation
        -------------
        
        To build the documentation, you’ll need to install ``mkdocs``.
        
        .. code:: bash
        
            $ pip install mkdocs
        
        To preview the documentation:
        
        .. code:: bash
        
            $ mkdocs serve
            Running at: http://127.0.0.1:8000/
        
        To build the documentation:
        
        .. code:: bash
        
            $ mkdocs build
        
        .. |build-status-image| image:: https://secure.travis-ci.org/evenicoulddoit/django-rest-framework-serializer-extensions.svg?branch=master
           :target: https://secure.travis-ci.org/evenicoulddoit/django-rest-framework-serializer-extensions?branch=master
        .. |coverage-status-image| image:: https://img.shields.io/codecov/c/github/evenicoulddoit/django-rest-framework-serializer-extensions/master.svg
           :target: http://codecov.io/github/evenicoulddoit/django-rest-framework-serializer-extensions?branch=master
        .. |pypi-version| image:: https://img.shields.io/pypi/v/djangorestframework-serializer-extensions.svg
           :target: https://pypi.python.org/pypi/djangorestframework-serializer-extensions
        
Platform: UNKNOWN
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Topic :: Internet :: WWW/HTTP
