Metadata-Version: 1.1
Name: drf_dynamic_fields
Version: 0.2.0
Summary: Dynamically return subset of Django REST Framework serializer fields
Home-page: https://github.com/dbrgn/drf-dynamic-fields
Author: Danilo Bargen
Author-email: mail@dbrgn.ch
License: MIT
Description: Dynamic Serializer Fields for Django REST Framework
        ===================================================
        
        .. image:: https://secure.travis-ci.org/dbrgn/drf-dynamic-fields.png?branch=master
            :alt: Build status
            :target: http://travis-ci.org/dbrgn/drf-dynamic-fields
        
        .. image:: https://img.shields.io/pypi/v/drf-dynamic-fields.svg
            :alt: PyPI Version
            :target: https://pypi.python.org/pypi/drf-dynamic-fields
        
        .. image:: https://img.shields.io/pypi/dm/drf-dynamic-fields.svg?maxAge=3600
            :alt: PyPI Downloads
            :target: https://pypi.python.org/pypi/drf-dynamic-fields
        
        .. image:: https://img.shields.io/github/license/mashape/apistatus.svg?maxAge=2592000
            :alt: License is MIT
            :target: https://github.com/dbrgn/drf-dynamic-fields/blob/master/LICENSE
        
        This package provides a mixin that allows the user to dynamically select only a
        subset of fields per resource.
        
        
        What It Does
        ------------
        
        Example serializer:
        
        .. sourcecode:: python
        
            class IdentitySerializer(serializers.HyperlinkedModelSerializer):
                class Meta:
                    model = models.Identity
                    fields = ('id', 'url', 'type', 'data')
        
        A regular request returns all fields:
        
        ``GET /identities``
        
        .. sourcecode:: json
        
            [
              {
                "id": 1,
                "url": "http://localhost:8000/api/identities/1/",
                "type": 5,
                "data": "John Doe"
              },
              ...
            ]
        
        A query with the `fields` parameter on the other hand returns only a subset of
        the fields:
        
        ``GET /identities/?fields=id,data``
        
        .. sourcecode:: json
        
            [
              {
                "id": 1,
                "data": "John Doe"
              },
              ...
            ]
        
        And a query with the `omit` parameter excludes specified fields.
        
        ``GET /identities/?omit=data``
        
        .. sourcecode:: json
        
            [
              {
                "id": 1,
                "url": "http://localhost:8000/api/identities/1/",
                "type": 5
              },
              ...
            ]
        
        You can use both `fields` and `omit` in the same request!
        
        ``GET /identities/?omit=data,fields=data,id``
        
        .. sourcecode:: json
        
            [
              {
                "id": 1
              },
              ...
            ]
        
        
        Though why you would want to do something like that is beyond this author.
        
        It also works on single objects!
        
        ``GET /identities/1/?fields=id,data``
        
        .. sourcecode:: json
        
            {
              "id": 1,
              "data": "John Doe"
            }
        
        Usage
        -----
        
        When defining a serializer, use the ``DynamicFieldsMixin``:
        
        .. sourcecode:: python
        
            class IdentitySerializer(DynamicFieldsMixin, serializers.ModelSerializer):
                class Meta:
                    model = models.Identity
                    fields = ('id', 'url', 'type', 'data')
        
        The mixin needs access to the ``request`` object. Some DRF classes like the
        ``ModelViewSet`` set that by default, but if you handle serializers yourself,
        pass in the request through the context:
        
        .. sourcecode:: python
        
            events = Event.objects.all()
            serializer = EventSerializer(events, many=True, context={'request': request})
        
        
        Testing
        -------
        
        To run tests, install Django and DRF and then run ``runtests.py``:
        
            $ python runtests.py
        
        
        Credits
        -------
        
        - The implementation is based on `this
          <http://stackoverflow.com/a/23674297/284318>`__ StackOverflow answer. Thanks
          ``YAtOff``!
        - The GitHub users ``X17`` and ``rawbeans`` provided improvements on `my gist
          <https://gist.github.com/dbrgn/4e6fc1fe5922598592d6>`__ that were incorporated
          into this library. Thanks!
        - For other contributors, please see `Github contributor stats
          <https://github.com/dbrgn/drf-dynamic-fields/graphs/contributors>`__.
        
        
        License
        -------
        
        MIT license, see ``LICENSE`` file.
        
Keywords: drf restframework rest_framework django_rest_framework serializers
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 3
Classifier: Framework :: Django
Classifier: Environment :: Web Environment
