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
 * 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,59 @@ field_name_mapping = {
 ```
 
 
+### Working with polymorphic resources
+
+Polymorphic resources allow you to use specialized subclasses without requiring
+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.
+
+DJA tests its polymorphic support against [django-polymorphic](https://django-polymorphic.readthedocs.io/en/stable/).
+The polymorphic feature should also work with other popular libraries like
+django-polymodels or django-typed-models.
+
+#### 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()