Add feature flipping models to Projects, plus example feature flip

Also, use a new pattern for API instance objects

Author: agjohnson

readthedocs/doc_builder/python_environments.py

@@ -11,6 +11,7 @@
 from readthedocs.doc_builder.config import ConfigWrapper
 from readthedocs.doc_builder.loader import get_builder_class
 from readthedocs.projects.constants import LOG_TEMPLATE
+from readthedocs.projects.models import Feature
 
 log = logging.getLogger(__name__)
 
@@ -128,8 +129,14 @@ def install_core_requirements(self):
         if self.project.documentation_type == 'mkdocs':
             requirements.append('mkdocs==0.15.0')
         else:
-            requirements.extend(['sphinx==1.5.3', 'sphinx-rtd-theme<0.3',
-                                 'readthedocs-sphinx-ext<0.6'])
+            if self.project.has_feature(Feature.USE_SPHINX_LATEST):
+                requirements.append('sphinx<1.7')
+            else:
+                requirements.append('sphinx==1.5.6')
+            requirements.extend([
+                'sphinx-rtd-theme<0.3',
+                'readthedocs-sphinx-ext<0.6'
+            ])
 
         cmd = [
             'python',

readthedocs/projects/admin.py

@@ -13,9 +13,10 @@
 from readthedocs.redirects.models import Redirect
 from readthedocs.notifications.views import SendNotificationView
 
-from .notifications import ResourceUsageNotification
-from .models import (Project, ImportedFile,
+from .forms import FeatureForm
+from .models import (Project, ImportedFile, Feature,
                      ProjectRelationship, EmailHook, WebHook, Domain)
+from .notifications import ResourceUsageNotification
 from .tasks import remove_dir
 
 
@@ -180,8 +181,14 @@ class DomainAdmin(admin.ModelAdmin):
     model = Domain
 
 
+class FeatureAdmin(admin.ModelAdmin):
+    model = Feature
+    form = FeatureForm
+
+
 admin.site.register(Project, ProjectAdmin)
 admin.site.register(ImportedFile, ImportedFileAdmin)
 admin.site.register(Domain, DomainAdmin)
+admin.site.register(Feature, FeatureAdmin)
 admin.site.register(EmailHook)
 admin.site.register(WebHook)

readthedocs/projects/forms.py

@@ -22,7 +22,7 @@
 from readthedocs.projects import constants
 from readthedocs.projects.exceptions import ProjectSpamError
 from readthedocs.projects.models import (
-    Project, ProjectRelationship, EmailHook, WebHook, Domain)
+    Project, ProjectRelationship, EmailHook, WebHook, Domain, Feature)
 from readthedocs.redirects.models import Redirect
 
 
@@ -595,3 +595,23 @@ class Meta(object):
     def __init__(self, *args, **kwargs):
         self.project = kwargs.pop('project', None)
         super(ProjectAdvertisingForm, self).__init__(*args, **kwargs)
+
+
+class FeatureForm(forms.ModelForm):
+
+    """Project feature form for dynamic admin choices
+
+    This form converts the CharField into a ChoiceField on display. The
+    underlying driver won't attempt to do validation on the choices, and so we
+    can dynamically populate this list.
+    """
+
+    feature = forms.ChoiceField()
+
+    class Meta(object):
+        model = Feature
+        fields = ['project', 'feature']
+
+    def __init__(self, *args, **kwargs):
+        super(FeatureForm, self).__init__(*args, **kwargs)
+        self.fields['feature'].choices = Feature.FEATURES

readthedocs/projects/migrations/0019_add-features.py

@@ -0,0 +1,28 @@
+# -*- coding: utf-8 -*-
+# Generated by Django 1.9.12 on 2017-10-26 14:40
+from __future__ import unicode_literals
+
+from django.db import migrations, models
+import django.db.models.deletion
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('projects', '0018_fix-translation-model'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='Feature',
+            fields=[
+                ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('feature', models.CharField(max_length=32, verbose_name='Project feature')),
+            ],
+        ),
+        migrations.AddField(
+            model_name='feature',
+            name='project',
+            field=models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, related_name='features', to='projects.Project'),
+        ),
+    ]

readthedocs/projects/models.py

@@ -821,6 +821,35 @@ def add_comment(self, version_slug, page, content_hash, commit, user, text):
                                      hash=content_hash, commit=commit)
         return node.comments.create(user=user, text=text)
 
+    def has_feature(self, feature):
+        """Does project have existing feature flag"""
+        return self.features.filter(feature=feature).exists()
+
+
+class APIProject(Project):
+
+    """Project object from API data deserialization
+
+    This is to preserve the Project model methods for use in builder instances.
+    Properties can be read only here, as the builders don't need write access to
+    a number of attributes.
+    """
+
+    features = []
+
+    class Meta:
+        proxy = True
+
+    def __init__(self, *args, **kwargs):
+        self.features = kwargs.pop('features', [])
+        super(APIProject, self).__init__(*args, **kwargs)
+
+    def save(self, *args, **kwargs):
+        return 0
+
+    def has_feature(self, feature):
+        return feature in self.features
+
 
 @python_2_unicode_compatible
 class ImportedFile(models.Model):
@@ -921,3 +950,52 @@ def delete(self, *args, **kwargs):  # pylint: disable=arguments-differ
         from readthedocs.projects import tasks
         broadcast(type='app', task=tasks.symlink_domain, args=[self.project.pk, self.pk, True])
         super(Domain, self).delete(*args, **kwargs)
+
+
+@python_2_unicode_compatible
+class Feature(models.Model):
+
+    """Project feature flags
+
+    Features should generally be added here as choices, however features may
+    also be added dynamically from a signal in other packages. See the
+    FeatureForm implementation for this.
+
+    Features can be added by external packages with the use of signals::
+
+        @receiver(pre_init, sender=Feature)
+        def add_features(sender, **kwargs):
+            sender.FEATURES += (('blah', 'BLAH'),)
+
+    The FeatureForm will grab the updated list on instantiation.
+    """
+
+    # Feature constants - this is not a exhaustive list of features, features
+    # may be added by other packages
+    USE_SPHINX_LATEST = 'use_sphinx_latest'
+
+    FEATURES = (
+        (USE_SPHINX_LATEST, _('Use latest version of Sphinx')),
+    )
+
+    project = models.ForeignKey(
+        Project,
+        related_name='features',
+    )
+    # Feature is not implemented as a ChoiceField, as we don't want validation
+    # at the database level on this field. Arbitrary values are allowed here.
+    feature = models.CharField(
+        _('Project feature'),
+        max_length=32,
+    )
+
+    def __str__(self):
+        return "{0} feature for {1}".format(self.get_feature_display(), self.project)
+
+    def get_feature_display(self):
+        """Implement display name field for fake ChoiceField
+
+        Because choices are implemented in FeatureForm, we need to reimplement
+        this here.
+        """
+        return dict(self.FEATURES).get(self.feature, self.feature)

readthedocs/projects/utils.py

@@ -192,11 +192,10 @@ def make_api_version(version_data):
 
 def make_api_project(project_data):
     """Make mock Project instance from API return"""
-    from readthedocs.projects.models import Project
+    from readthedocs.projects.models import APIProject
     for key in ['users', 'resource_uri', 'absolute_url', 'downloads',
                 'main_language_project', 'related_projects']:
         if key in project_data:
             del project_data[key]
-    project = Project(**project_data)
-    project.save = _new_save
+    project = APIProject(**project_data)
     return project

readthedocs/restapi/serializers.py

@@ -1,13 +1,13 @@
 """Defines serializers for each of our models."""
 
 from __future__ import absolute_import
-from builtins import object
 
+from builtins import object
 from rest_framework import serializers
 
 from readthedocs.builds.models import Build, BuildCommandResult, Version
-from readthedocs.projects.models import Project, Domain
 from readthedocs.oauth.models import RemoteOrganization, RemoteRepository
+from readthedocs.projects.models import Project, Domain
 
 
 class ProjectSerializer(serializers.ModelSerializer):
@@ -28,6 +28,18 @@ class Meta(object):
 
 class ProjectAdminSerializer(ProjectSerializer):
 
+    """Project serializer for admin only access
+
+    Includes special internal fields that don't need to be exposed through the
+    general API, mostly for fields used in the build process
+    """
+
+    features = serializers.SlugRelatedField(
+        many=True,
+        read_only=True,
+        slug_field='feature',
+    )
+
     class Meta(ProjectSerializer.Meta):
         fields = ProjectSerializer.Meta.fields + (
             'enable_epub_build',
@@ -44,6 +56,7 @@ class Meta(ProjectSerializer.Meta):
             'skip',
             'requirements_file',
             'python_interpreter',
+            'features',
         )