Support polymorphic models

.gitignore

@@ -34,6 +34,8 @@ pip-delete-this-directory.txt
 
 # Tox
 .tox/
+.cache/
+.python-version
 
 # VirtualEnv
 .venv/

AUTHORS

@@ -1,7 +1,9 @@
 Adam Wróbel <https://adamwrobel.com>
 Christian Zosel <https://zosel.ch>
 Greg Aker <greg@gregaker.net>
+Jamie Bliss <astronouth7303@gmail.com>
 Jerel Unruh <mail@unruhdesigns.com>
+Léo S. <leo@naeka.fr>
 Matt Layman <http://www.mattlayman.com>
 Oliver Sauder <os@esite.ch>
 Yaniv Peer <yanivpeer@gmail.com>

CHANGELOG.md

@@ -1,5 +1,6 @@
 v2.3.0
 
+* Added support for polymorphic models via `django-polymorphic`
 * When `JSON_API_FORMAT_KEYS` is False (the default) do not translate request
   attributes and relations to snake\_case format. This conversion was unexpected
   and there was no way to turn it off.

docs/usage.md

@@ -425,6 +425,56 @@ field_name_mapping = {
 ```
 
 
+### Working with polymorphic resources
+
+Polymorphic resources (as backed by [django-polymorphic](https://django-polymorphic.readthedocs.io/en/stable/))
+allow you to easily use specialized subclasses without have to have special
+endpoints to expose the specialized versions. For example, if you had a
+`Project` that could be either an `ArtProject` or a `ResearchProject`, you can
+have both kinds at the same URL.
+
+#### Writing polymorphic resources
+
+A polymorphic endpoint can be set up if associated with a polymorphic serializer.
+A polymorphic serializer takes care of (de)serializing the correct instances types and can be defined like this:
+
+```python
+class ProjectSerializer(serializers.PolymorphicModelSerializer):
+    polymorphic_serializers = [ArtProjectSerializer, ResearchProjectSerializer]
+
+    class Meta:
+        model = models.Project
+```
+
+It must inherit from `serializers.PolymorphicModelSerializer` and define the `polymorphic_serializers` list.
+This attribute defines the accepted resource types.
+
+
+Polymorphic relations can also be handled with `relations.PolymorphicResourceRelatedField` like this:
+
+```python
+class CompanySerializer(serializers.ModelSerializer):
+    current_project = relations.PolymorphicResourceRelatedField(
+        ProjectSerializer, queryset=models.Project.objects.all())
+    future_projects = relations.PolymorphicResourceRelatedField(
+        ProjectSerializer, queryset=models.Project.objects.all(), many=True)
+
+    class Meta:
+        model = models.Company
+```
+
+They must be explicitly declared with the `polymorphic_serializer` (first positional argument) correctly defined.
+It must be a subclass of `serializers.PolymorphicModelSerializer`.
+
+<div class="warning">
+    <strong>Note:</strong>
+    Polymorphic resources are not compatible with
+    <code class="docutils literal">
+        <span class="pre">resource_name</span>
+    </code>
+    defined on the view.
+</div>
+
 ### Meta
 
 You may add metadata to the rendered json in two different ways: `meta_fields` and `get_root_meta`.

example/factories/__init__.py

@@ -2,7 +2,9 @@
 
 import factory
 from faker import Factory as FakerFactory
-from example.models import Blog, Author, AuthorBio, Entry, Comment, TaggedItem
+from example.models import (
+    Blog, Author, AuthorBio, Entry, Comment, TaggedItem, ArtProject, ResearchProject, Company
+)
 
 faker = FakerFactory.create()
 faker.seed(983843)
@@ -68,3 +70,35 @@ class Meta:
 
     content_object = factory.SubFactory(EntryFactory)
     tag = factory.LazyAttribute(lambda x: faker.word())
+
+
+class ArtProjectFactory(factory.django.DjangoModelFactory):
+    class Meta:
+        model = ArtProject
+
+    topic = factory.LazyAttribute(lambda x: faker.catch_phrase())
+    artist = factory.LazyAttribute(lambda x: faker.name())
+
+
+class ResearchProjectFactory(factory.django.DjangoModelFactory):
+    class Meta:
+        model = ResearchProject
+
+    topic = factory.LazyAttribute(lambda x: faker.catch_phrase())
+    supervisor = factory.LazyAttribute(lambda x: faker.name())
+
+
+class CompanyFactory(factory.django.DjangoModelFactory):
+    class Meta:
+        model = Company
+
+    name = factory.LazyAttribute(lambda x: faker.company())
+    current_project = factory.SubFactory(ArtProjectFactory)
+
+    @factory.post_generation
+    def future_projects(self, create, extracted, **kwargs):
+        if not create:
+            return
+        if extracted:
+            for project in extracted:
+                self.future_projects.add(project)

example/migrations/0003_polymorphics.py

@@ -0,0 +1,76 @@
+# -*- coding: utf-8 -*-
+# Generated by Django 1.11.1 on 2017-05-17 14:49
+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', '0002_taggeditem'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='Company',
+            fields=[
+                ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('name', models.CharField(max_length=100)),
+            ],
+        ),
+        migrations.CreateModel(
+            name='Project',
+            fields=[
+                ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('topic', models.CharField(max_length=30)),
+            ],
+            options={
+                'abstract': False,
+            },
+        ),
+        migrations.AlterField(
+            model_name='comment',
+            name='entry',
+            field=models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='comments', to='example.Entry'),
+        ),
+        migrations.CreateModel(
+            name='ArtProject',
+            fields=[
+                ('project_ptr', models.OneToOneField(auto_created=True, on_delete=django.db.models.deletion.CASCADE, parent_link=True, primary_key=True, serialize=False, to='example.Project')),
+                ('artist', models.CharField(max_length=30)),
+            ],
+            options={
+                'abstract': False,
+            },
+            bases=('example.project',),
+        ),
+        migrations.CreateModel(
+            name='ResearchProject',
+            fields=[
+                ('project_ptr', models.OneToOneField(auto_created=True, on_delete=django.db.models.deletion.CASCADE, parent_link=True, primary_key=True, serialize=False, to='example.Project')),
+                ('supervisor', models.CharField(max_length=30)),
+            ],
+            options={
+                'abstract': False,
+            },
+            bases=('example.project',),
+        ),
+        migrations.AddField(
+            model_name='project',
+            name='polymorphic_ctype',
+            field=models.ForeignKey(editable=False, null=True, on_delete=django.db.models.deletion.CASCADE, related_name='polymorphic_example.project_set+', to='contenttypes.ContentType'),
+        ),
+        migrations.AddField(
+            model_name='company',
+            name='current_project',
+            field=models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='companies', to='example.Project'),
+        ),
+        migrations.AddField(
+            model_name='company',
+            name='future_projects',
+            field=models.ManyToManyField(to='example.Project'),
+        ),
+    ]

example/models.py

@@ -6,6 +6,7 @@
 from django.contrib.contenttypes.fields import GenericRelation
 from django.db import models
 from django.utils.encoding import python_2_unicode_compatible
+from polymorphic.models import PolymorphicModel
 
 
 class BaseModel(models.Model):
@@ -86,3 +87,25 @@ class Comment(BaseModel):
 
     def __str__(self):
         return self.body
+
+
+class Project(PolymorphicModel):
+    topic = models.CharField(max_length=30)
+
+
+class ArtProject(Project):
+    artist = models.CharField(max_length=30)
+
+
+class ResearchProject(Project):
+    supervisor = models.CharField(max_length=30)
+
+
+@python_2_unicode_compatible
+class Company(models.Model):
+    name = models.CharField(max_length=100)
+    current_project = models.ForeignKey(Project, related_name='companies')
+    future_projects = models.ManyToManyField(Project)
+
+    def __str__(self):
+        return self.name

example/serializers.py

@@ -1,6 +1,12 @@
 from datetime import datetime
+
+import rest_framework
 from rest_framework_json_api import serializers, relations
-from example.models import Blog, Entry, Author, AuthorBio, Comment, TaggedItem
+from packaging import version
+from example.models import (
+    Blog, Entry, Author, AuthorBio, Comment, TaggedItem, Project, ArtProject, ResearchProject,
+    Company,
+)
 
 
 class TaggedItemSerializer(serializers.ModelSerializer):
@@ -115,3 +121,40 @@ class Meta:
         model = Comment
         exclude = ('created_at', 'modified_at',)
         # fields = ('entry', 'body', 'author',)
+
+
+class ArtProjectSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = ArtProject
+        exclude = ('polymorphic_ctype',)
+
+
+class ResearchProjectSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = ResearchProject
+        exclude = ('polymorphic_ctype',)
+
+
+class ProjectSerializer(serializers.PolymorphicModelSerializer):
+    polymorphic_serializers = [ArtProjectSerializer, ResearchProjectSerializer]
+
+    class Meta:
+        model = Project
+        exclude = ('polymorphic_ctype',)
+
+
+class CompanySerializer(serializers.ModelSerializer):
+    current_project = relations.PolymorphicResourceRelatedField(
+        ProjectSerializer, queryset=Project.objects.all())
+    future_projects = relations.PolymorphicResourceRelatedField(
+        ProjectSerializer, queryset=Project.objects.all(), many=True)
+
+    included_serializers = {
+        'current_project': ProjectSerializer,
+        'future_projects': ProjectSerializer,
+    }
+
+    class Meta:
+        model = Company
+        if version.parse(rest_framework.VERSION) >= version.parse('3.3'):
+            fields = '__all__'

example/settings/dev.py

@@ -23,6 +23,7 @@
     'django.contrib.auth',
     'django.contrib.admin',
     'rest_framework',
+    'polymorphic',
     'example',
 ]
 

example/tests/conftest.py

@@ -3,7 +3,7 @@
 
 from example.factories import (
     BlogFactory, AuthorFactory, AuthorBioFactory, EntryFactory, CommentFactory,
-    TaggedItemFactory
+    TaggedItemFactory, ArtProjectFactory, ResearchProjectFactory, CompanyFactory,
 )
 
 register(BlogFactory)
@@ -12,6 +12,9 @@
 register(EntryFactory)
 register(CommentFactory)
 register(TaggedItemFactory)
+register(ArtProjectFactory)
+register(ResearchProjectFactory)
+register(CompanyFactory)
 
 
 @pytest.fixture
@@ -33,3 +36,14 @@ def multiple_entries(blog_factory, author_factory, entry_factory, comment_factor
     comment_factory(entry=entries[0])
     comment_factory(entry=entries[1])
     return entries
+
+
+@pytest.fixture
+def single_company(art_project_factory, research_project_factory, company_factory):
+    company = company_factory(future_projects=(research_project_factory(), art_project_factory()))
+    return company
+
+
+@pytest.fixture
+def single_art_project(art_project_factory):
+    return art_project_factory()