Merge branch 'develop' of github.com:django-json-api/django-rest-framework-json-api into develop

Author: Eric Hurst

docs/usage.md

@@ -457,8 +457,53 @@ Adding `url` to `fields` on a serializer will add a `self` link to the `links` k
 
 Related links will be created automatically when using the Relationship View.
 
+### Included
+
+JSON API can include additional resources in a single network request.
+The specification refers to this feature as
+[Compound Documents](http://jsonapi.org/format/#document-compound-documents).
+Compound Documents can reduce the number of network requests
+which can lead to a better performing web application.
+To accomplish this,
+the specification permits a top level `included` key.
+The list of content within this key are the extra resources
+that are related to the primary resource.
+
+To make a Compound Document,
+you need to modify your `ModelSerializer`.
+The two required additions are `included_resources`
+and `included_serializers`.
+
+For example,
+suppose you are making an app to go on quests,
+and you would like to fetch your chosen knight
+along with the quest.
+You could accomplish that with:
+
+```python
+class KnightSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = Knight
+        fields = ('id', 'name', 'strength', 'dexterity', 'charisma')
+
+
+class QuestSerializer(serializers.ModelSerializer):
+    included_serializers = {
+        'knight': KnightSerializer,
+    }
+
+    class Meta:
+        model = Quest
+        fields = ('id', 'title', 'reward', 'knight')
+
+    class JSONAPIMeta:
+        included_resources = ['knight']
+```
+
+`included_resources` informs DJA of **what** you would like to include.
+`included_serializers` tells DJA **how** you want to include it.
+
 <!--
 ### Relationships
-### Included
 ### Errors
 -->

example/factories/__init__.py

@@ -2,7 +2,7 @@
 
 import factory
 from faker import Factory as FakerFactory
-from example.models import Blog, Author, AuthorBio, Entry, Comment
+from example.models import Blog, Author, AuthorBio, Entry, Comment, TaggedItem
 
 faker = FakerFactory.create()
 faker.seed(983843)
@@ -58,3 +58,11 @@ class Meta:
     body = factory.LazyAttribute(lambda x: faker.text())
     author = factory.SubFactory(AuthorFactory)
 
+
+class TaggedItemFactory(factory.django.DjangoModelFactory):
+
+    class Meta:
+        model = TaggedItem
+
+    content_object = factory.SubFactory(EntryFactory)
+    tag = factory.LazyAttribute(lambda x: faker.word())

example/migrations/0002_taggeditem.py

@@ -0,0 +1,31 @@
+# -*- coding: utf-8 -*-
+# Generated by Django 1.10.5 on 2017-02-01 08:34
+from __future__ import unicode_literals
+
+from django.db import migrations, models
+import django.db.models.deletion
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('contenttypes', '0002_remove_content_type_name'),
+        ('example', '0001_initial'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='TaggedItem',
+            fields=[
+                ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('created_at', models.DateTimeField(auto_now_add=True)),
+                ('modified_at', models.DateTimeField(auto_now=True)),
+                ('tag', models.SlugField()),
+                ('object_id', models.PositiveIntegerField()),
+                ('content_type', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, to='contenttypes.ContentType')),
+            ],
+            options={
+                'abstract': False,
+            },
+        ),
+    ]

example/models.py

@@ -1,6 +1,9 @@
 # -*- encoding: utf-8 -*-
 from __future__ import unicode_literals
 
+from django.contrib.contenttypes.models import ContentType
+from django.contrib.contenttypes.fields import GenericForeignKey
+from django.contrib.contenttypes.fields import GenericRelation
 from django.db import models
 from django.utils.encoding import python_2_unicode_compatible
 
@@ -16,10 +19,21 @@ class Meta:
         abstract = True
 
 
+class TaggedItem(BaseModel):
+    tag = models.SlugField()
+    content_type = models.ForeignKey(ContentType, on_delete=models.CASCADE)
+    object_id = models.PositiveIntegerField()
+    content_object = GenericForeignKey('content_type', 'object_id')
+
+    def __str__(self):
+        return self.tag
+
+
 @python_2_unicode_compatible
 class Blog(BaseModel):
     name = models.CharField(max_length=100)
     tagline = models.TextField()
+    tags = GenericRelation(TaggedItem)
 
     def __str__(self):
         return self.name
@@ -54,6 +68,7 @@ class Entry(BaseModel):
     n_comments = models.IntegerField(default=0)
     n_pingbacks = models.IntegerField(default=0)
     rating = models.IntegerField(default=0)
+    tags = GenericRelation(TaggedItem)
 
     def __str__(self):
         return self.headline

example/serializers.py

@@ -1,11 +1,23 @@
 from datetime import datetime
 from rest_framework_json_api import serializers, relations
-from example.models import Blog, Entry, Author, AuthorBio, Comment
+from example.models import Blog, Entry, Author, AuthorBio, Comment, TaggedItem
+
+
+class TaggedItemSerializer(serializers.ModelSerializer):
+
+    class Meta:
+        model = TaggedItem
+        fields = ('tag', )
 
 
 class BlogSerializer(serializers.ModelSerializer):
 
     copyright = serializers.SerializerMethodField()
+    tags = TaggedItemSerializer(many=True, read_only=True)
+
+    include_serializers = {
+        'tags': 'example.serializers.TaggedItemSerializer',
+    }
 
     def get_copyright(self, resource):
         return datetime.now().year
@@ -17,7 +29,8 @@ def get_root_meta(self, resource, many):
 
     class Meta:
         model = Blog
-        fields = ('name', 'url',)
+        fields = ('name', 'url', 'tags')
+        read_only_fields = ('tags', )
         meta_fields = ('copyright',)
 
 
@@ -36,6 +49,7 @@ def __init__(self, *args, **kwargs):
         'comments': 'example.serializers.CommentSerializer',
         'featured': 'example.serializers.EntrySerializer',
         'suggested': 'example.serializers.EntrySerializer',
+        'tags': 'example.serializers.TaggedItemSerializer',
     }
 
     body_format = serializers.SerializerMethodField()
@@ -52,6 +66,7 @@ def __init__(self, *args, **kwargs):
     # single related from serializer
     featured = relations.SerializerMethodResourceRelatedField(
             source='get_featured', model=Entry, read_only=True)
+    tags = TaggedItemSerializer(many=True, read_only=True)
 
     def get_suggested(self, obj):
         return Entry.objects.exclude(pk=obj.pk)
@@ -65,9 +80,13 @@ def get_body_format(self, obj):
     class Meta:
         model = Entry
         fields = ('blog', 'headline', 'body_text', 'pub_date', 'mod_date',
-                  'authors', 'comments', 'featured', 'suggested',)
+                  'authors', 'comments', 'featured', 'suggested', 'tags')
+        read_only_fields = ('tags', )
         meta_fields = ('body_format',)
 
+    class JSONAPIMeta:
+        included_resources = ['comments']
+
 
 class AuthorBioSerializer(serializers.ModelSerializer):
 

example/tests/conftest.py

@@ -1,20 +1,23 @@
 import pytest
 from pytest_factoryboy import register
 
-from example.factories import BlogFactory, AuthorFactory, AuthorBioFactory, EntryFactory, CommentFactory
+from example.factories import BlogFactory, AuthorFactory, AuthorBioFactory, EntryFactory, CommentFactory, \
+    TaggedItemFactory
 
 register(BlogFactory)
 register(AuthorFactory)
 register(AuthorBioFactory)
 register(EntryFactory)
 register(CommentFactory)
+register(TaggedItemFactory)
 
 
 @pytest.fixture
-def single_entry(blog, author, entry_factory, comment_factory):
+def single_entry(blog, author, entry_factory, comment_factory, tagged_item_factory):
 
     entry = entry_factory(blog=blog, authors=(author,))
     comment_factory(entry=entry)
+    tagged_item_factory(content_object=entry)
     return entry
 
 

example/tests/integration/test_includes.py

@@ -3,15 +3,9 @@
 
 from example.tests.utils import load_json
 
-try:
-    from unittest import mock
-except ImportError:
-    import mock
-
 pytestmark = pytest.mark.django_db
 
 
-@mock.patch('rest_framework_json_api.utils.get_default_included_resources_from_serializer', new=lambda s: ['comments'])
 def test_default_included_data_on_list(multiple_entries, client):
     return test_included_data_on_list(multiple_entries=multiple_entries, client=client, query='?page_size=5')
 
@@ -28,7 +22,6 @@ def test_included_data_on_list(multiple_entries, client, query='?include=comment
     assert comment_count == expected_comment_count, 'List comment count is incorrect'
 
 
-@mock.patch('rest_framework_json_api.utils.get_default_included_resources_from_serializer', new=lambda s: ['comments'])
 def test_default_included_data_on_detail(single_entry, client):
     return test_included_data_on_detail(single_entry=single_entry, client=client, query='')
 

example/tests/integration/test_meta.py

@@ -2,7 +2,7 @@
 from django.core.urlresolvers import reverse
 
 import pytest
-from example.tests.utils import dump_json, redump_json
+from example.tests.utils import load_json
 
 pytestmark = pytest.mark.django_db
 
@@ -19,6 +19,11 @@ def test_top_level_meta_for_list_view(blog, client):
             "links": {
                 "self": 'http://testserver/blogs/1'
             },
+            "relationships": {
+                "tags": {
+                    "data": []
+                }
+            },
             "meta": {
                 "copyright": datetime.now().year
             },
@@ -36,10 +41,9 @@ def test_top_level_meta_for_list_view(blog, client):
     }
 
     response = client.get(reverse("blog-list"))
-    content_dump = redump_json(response.content)
-    expected_dump = dump_json(expected)
+    parsed_content = load_json(response.content)
 
-    assert content_dump == expected_dump
+    assert expected == parsed_content
 
 
 def test_top_level_meta_for_detail_view(blog, client):
@@ -51,6 +55,11 @@ def test_top_level_meta_for_detail_view(blog, client):
             "attributes": {
                 "name": blog.name
             },
+            "relationships": {
+                "tags": {
+                    "data": []
+                }
+            },
             "links": {
                 "self": "http://testserver/blogs/1"
             },
@@ -64,7 +73,6 @@ def test_top_level_meta_for_detail_view(blog, client):
     }
 
     response = client.get(reverse("blog-detail", kwargs={'pk': blog.pk}))
-    content_dump = redump_json(response.content)
-    expected_dump = dump_json(expected)
+    parsed_content = load_json(response.content)
 
-    assert content_dump == expected_dump
+    assert expected == parsed_content

example/tests/integration/test_non_paginated_responses.py

@@ -1,17 +1,26 @@
 from django.core.urlresolvers import reverse
 from django.conf import settings
 
+try:
+    from unittest import mock
+except ImportError:
+    import mock
+
 import pytest
 
 from example.views import EntryViewSet
 from rest_framework_json_api.pagination import PageNumberPagination
 
-from example.tests.utils import dump_json, redump_json
+from example.tests.utils import load_json
 
 pytestmark = pytest.mark.django_db
 
 
 # rf == request_factory
+@mock.patch(
+    'rest_framework_json_api.utils'
+    '.get_default_included_resources_from_serializer',
+    new=lambda s: [])
 def test_multiple_entries_no_pagination(multiple_entries, rf):
 
     expected = {
@@ -48,6 +57,9 @@ def test_multiple_entries_no_pagination(multiple_entries, rf):
                             "related": "http://testserver/entries/1/suggested/",
                             "self": "http://testserver/entries/1/relationships/suggested"
                         }
+                    },
+                    "tags": {
+                        "data": []
                     }
                 }
             },
@@ -83,6 +95,9 @@ def test_multiple_entries_no_pagination(multiple_entries, rf):
                             "related": "http://testserver/entries/2/suggested/",
                             "self": "http://testserver/entries/2/relationships/suggested"
                         }
+                    },
+                    "tags": {
+                        "data": []
                     }
                 }
             },
@@ -101,7 +116,6 @@ class NonPaginatedEntryViewSet(EntryViewSet):
     response = view(request)
     response.render()
 
-    content_dump = redump_json(response.content)
-    expected_dump = dump_json(expected)
+    parsed_content = load_json(response.content)
 
-    assert content_dump == expected_dump
+    assert expected == parsed_content