Metadata-Version: 2.1
Name: drf-nested-resources
Version: 2.0.0
Summary: Support for nested routes in the Django REST Framework
Home-page: https://pypi.python.org/pypi/drf-nested-resources
Author: 2degrees Limited
Author-email: foss@2degreesnetwork.com
License: BSD (http://dev.2degreesnetwork.com/p/2degrees-license.html)
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Description-Content-Type: text/markdown
Requires-Dist: djangorestframework>=3.9.2
Requires-Dist: pyrecord>=1.0rc2

# drf-nested-resources

This is a django rest framework extension to allow developers to create nested
resources.

## How to use

### Configuration of nested resources

For this example we are going to create a simple API with the following
endpoints:

    /developers/
    /developers/<id>
    /developers/<id>/languages/
    /developers/<id>/languages/<id>

First we start with the following Django models:

```python
from django.db.models import CASCADE
from django.db.models.base import Model
from django.db.models.fields import CharField
from django.db.models.fields.related import ForeignKey


class Developer(Model):

    name = CharField(max_length=20)


class ProgrammingLanguage(Model):

    name = CharField(max_length=20)

    author = ForeignKey(
        Developer, 
        related_name='programming_languages', 
        on_delete=CASCADE,
    )
```

We will have the two viewsets for both the `developers` and `languages` resource
collections.

```python
from rest_framework.viewsets import ModelViewSet
from drf_nested_resources.fields import HyperlinkedNestedModelSerializer


class _DeveloperSerializer(HyperlinkedNestedModelSerializer):

    class Meta(object):

        model = Developer

        fields = ('url', 'name', 'programming_languages')


class DeveloperViewSet(ModelViewSet):

    queryset = Developer.objects.all()

    serializer_class = _DeveloperSerializer


class _ProgrammingLanguageSerializer(HyperlinkedNestedModelSerializer):

    class Meta(object):

        model = ProgrammingLanguage

        fields = ('url', 'name', 'author')


class ProgrammingLanguageViewSet(ModelViewSet):

    queryset = ProgrammingLanguage.objects.all()

    serializer_class = _ProgrammingLanguageSerializer
```

The related fields in the ViewSets `author` and `programming_languages` should
follow the model representation so that `author` will give us a url for the
developer who wrote the ProgrammingLanguage and the `programming_languages`
should give us a list of urls for the ProgrammingLanguages that the Developer
wrote.

This is how you would generate the urlpatterns for them:

```python
_RESOURCES = [
    Resource(
        'developer',
        'developers',
        DeveloperViewSet,
        [
            NestedResource(
                'language',
                'languages',
                ProgrammingLanguageViewSet,
                parent_field_lookup='author',
                )
            ],
        ),
    ]
urlpatterns = make_urlpatterns_from_resources(_RESOURCES)
```

For more examples of different relationships and authorization check the test
suite.

Changelog
=========

Version 2.0.0
-------------

Added support for Django 2.2 and removed support for Django < 2.2

Version 1.3
------------------

Updated dependencies and added coverage config


Version 1.2 Beta 3
------------------

Fixed error when urlconf was not explicitly set on the request


Version 1.2 Beta 2
------------------

Fixed support for non-session-based authenticators when checking permissions in
viewsets in the ancestry.


Version 1.2 Beta 1
------------------

Implemented ability to force a field value in a nested resource to be set to
the URL of an ascending resource. This is done using the optional attribute
``field_forced_to_ancestor`` on the serializer's ``Meta`` class.


Version 1.1
-----------

Re-worked the mechanism for URL generation to support cross-linking resource
trees.

**Breaking change**: Any previous usage of many-to-many fields on variables
in the current request's URL will now break.


Version 1.0 Release Candidate 3
-------------------------------

Added proper support for namespaced URLs


Version 1.0 Release Candidate 1
-------------------------------

Added support for Django 1.10 and Rest Framework 3.4.3


Version 1.0 Beta 1 (unreleased)
-------------------------------

Initial release.
