Refs #11 -- more docstring improvement.

Author: mboersma

api/models.py

@@ -30,12 +30,11 @@
 
 
 def import_tasks(provider_type):
-    """Return the celerytasks module for a given provider.
+    """Return the celerytasks module for a provider.
 
-        :param provider_type: type of cloud provider **currently only "ec2"**
-        :type  provider_type: string
-        :rtype: celerytasks module for the provider
-        :raises: :py:class:`ImportError` if the provider isn't recognized
+    :param string provider_type: type of cloud provider **currently only "ec2"**
+    :rtype: celerytasks module for the provider
+    :raises: :py:class:`ImportError` if the provider isn't recognized
     """
     try:
         tasks = importlib.import_module('celerytasks.' + provider_type)
@@ -45,37 +44,30 @@ def import_tasks(provider_type):
 
 
 class AuditedModel(models.Model):
-
-    """Adds created and updated fields to a model.
+    """Add created and updated fields to a model.
     """
 
     created = models.DateTimeField(auto_now_add=True)
     updated = models.DateTimeField(auto_now=True)
 
     class Meta:
-        """
-        Metadata options for `AuditedModel`, marking this class as abstract.
-        """
+        """Mark :class:`AuditedModel` as abstract."""
         abstract = True
 
 
 class UuidAuditedModel(AuditedModel):
-
-    """
-    Adds a UUID primary key to an audited model.
+    """Add a UUID primary key to an audited model.
     """
+
     uuid = fields.UuidField('UUID', primary_key=True)
 
     class Meta:
-        """
-        Metadata options for UuidAuditedModel, marking this class as abstract.
-        """
+        """Mark :class:`UuidAuditedModel` as abstract."""
         abstract = True
 
 
 @python_2_unicode_compatible
 class Key(UuidAuditedModel):
-
     """An SSH public key."""
 
     owner = models.ForeignKey(settings.AUTH_USER_MODEL)
@@ -92,8 +84,7 @@ def __str__(self):
 
 @python_2_unicode_compatible
 class ProviderManager(models.Manager):
-
-    """Manages database interactions for Provider objects."""
+    """Manage database interactions for :class:`Provider`."""
 
     def seed(self, user, **kwargs):
         """Seeds the database with Providers for clouds supported by deis.
@@ -108,10 +99,11 @@ def seed(self, user, **kwargs):
 
 @python_2_unicode_compatible
 class Provider(UuidAuditedModel):
+    """Cloud provider information for a user.
 
+    Available as `user.provider_set`.
     """
-    Cloud provider information for a user. Available as `user.provider_set`.
-    """
+
     objects = ProviderManager()
 
     PROVIDERS = (
@@ -131,7 +123,7 @@ class Meta:
 @python_2_unicode_compatible
 class FlavorManager(models.Manager):
 
-    """Manages database interactions for Flavors."""
+    """Manages database interactions for :class:`Flavor`."""
 
     def load_cloud_config_base(self):
         """Read the base configuration file and return the YAML data it contains."""
@@ -534,12 +526,12 @@ def new(self, formation, layer):
 
 @python_2_unicode_compatible
 class Node(UuidAuditedModel):
-
     """
     Node used to host containers
 
     List of nodes available as `formation.nodes`
     """
+
     objects = NodeManager()
 
     owner = models.ForeignKey(settings.AUTH_USER_MODEL)
@@ -709,8 +701,7 @@ def __str__(self):
 
     @classmethod
     def push(cls, push):
-        """
-        Process a push from a local Git server
+        """Process a push from a local Git server.
 
         Creates a new Build and returns the formation's
         databag for processing by the git-receive hook
@@ -751,7 +742,6 @@ def push(cls, push):
 
 @python_2_unicode_compatible
 class Release(UuidAuditedModel):
-
     """
     The deployment of a Build to Instances and the restarting of Processes.
     """
@@ -781,8 +771,9 @@ def rollback(self):
 
 @receiver(release_signal)
 def new_release(sender, **kwargs):
-    """Catches a release_signal and creates a new release from the
-    last release.
+    """Catch a release_signal and clone a new release from the previous one.
+
+    :returns: a newly created :class:`Release`
     """
     formation, user = kwargs['formation'], kwargs['user']
     last_release = Release.objects.filter(

api/serializers.py

@@ -140,7 +140,7 @@ class Meta:
 
     @property
     def data(self):
-        "Custom data property that removes secure fields"
+        """Custom data property that removes secure fields"""
         d = super(LayerSerializer, self).data
         for f in ('ssh_private_key',):
             if f in d:

api/views.py

@@ -7,15 +7,14 @@
 import json
 
 from Crypto.PublicKey import RSA
-from django.conf import settings
-from django.contrib.auth.models import Group, AnonymousUser, User
+from django.contrib.auth.models import AnonymousUser, User
 from django.db.utils import IntegrityError
 from django.utils import timezone
 from rest_framework import permissions, status, viewsets
 from rest_framework.authentication import BaseAuthentication
 from rest_framework.generics import get_object_or_404
 from rest_framework.response import Response
-from rest_framework.status import HTTP_400_BAD_REQUEST, HTTP_201_CREATED
+from rest_framework.status import HTTP_201_CREATED, HTTP_400_BAD_REQUEST
 
 from api import models
 from api import serializers
@@ -33,7 +32,7 @@ def authenticate(self, request):
 
 class IsAnonymous(permissions.BasePermission):
     """
-    Object-level permission to allow anonymous users
+    Object-level permission to allow anonymous users.
     """
 
     def has_permission(self, request, view):
@@ -60,16 +59,6 @@ def has_object_permission(self, request, view, obj):
             return False
 
 
-class GroupViewSet(viewsets.ModelViewSet):
-
-    model = Group
-
-
-class UserViewSet(viewsets.ModelViewSet):
-
-    model = settings.AUTH_USER_MODEL
-
-
 class UserRegistrationView(viewsets.GenericViewSet,
                            viewsets.mixins.CreateModelMixin):
 
@@ -80,12 +69,13 @@ class UserRegistrationView(viewsets.GenericViewSet,
     serializer_class = serializers.UserSerializer
 
     def post_save(self, user, created=False):
+        """Seed both `Providers` and `Flavors` after registration."""
         if created:
             models.Provider.objects.seed(user)
             models.Flavor.objects.seed(user)
 
     def pre_save(self, obj):
-        "Replicate UserManager.create_user functionality"
+        """Replicate UserManager.create_user functionality."""
         now = timezone.now()
         obj.last_login = now
         obj.date_joined = now
@@ -94,43 +84,50 @@ def pre_save(self, obj):
 
 
 class OwnerViewSet(viewsets.ModelViewSet):
-    """
-    Base ViewSet for views scoped to a particular Owner
-    """
+    """Scope views to an `owner` attribute."""
+
     permission_classes = (permissions.IsAuthenticated, IsOwner)
 
     def pre_save(self, obj):
         obj.owner = self.request.user
 
     def get_queryset(self, **kwargs):
+        """Filter all querysets by an `owner` attribute.
+        """
         return self.model.objects.filter(owner=self.request.user)
 
 
 class KeyViewSet(OwnerViewSet):
+    """RESTful views for :class:`~api.models.Key`."""
 
     model = models.Key
     serializer_class = serializers.KeySerializer
     lookup_field = 'id'
 
     def post_save(self, obj, created=False, **kwargs):
-        # update gitosis
+        """Publish all Formations when a Key is saved so gitosis stays updated.
+        """
         models.Formation.objects.publish()
 
     def destroy(self, request, **kwargs):
+        """Publish all Formations when a Key is destroyed so gitosis
+        stays updated.
+        """
         resp = super(KeyViewSet, self).destroy(self, request, **kwargs)
-        # publish gitosis updates
         models.Formation.objects.publish()
         return resp
 
 
 class ProviderViewSet(OwnerViewSet):
+    """RESTful views for :class:`~api.models.Provider`."""
 
     model = models.Provider
     serializer_class = serializers.ProviderSerializer
     lookup_field = 'id'
 
 
 class FlavorViewSet(OwnerViewSet):
+    """RESTful views for :class:`~api.models.Flavor`."""
 
     model = models.Flavor
     serializer_class = serializers.FlavorSerializer
@@ -145,6 +142,7 @@ def create(self, request, **kwargs):
 
 
 class FormationViewSet(OwnerViewSet):
+    """RESTful views for :class:`~api.models.Formtion`."""
 
     model = models.Formation
     serializer_class = serializers.FormationSerializer
@@ -233,6 +231,7 @@ def destroy(self, request, **kwargs):
 
 
 class FormationLayerViewSet(OwnerViewSet):
+    """RESTful views for :class:`~api.models.Layer`."""
 
     model = models.Layer
     serializer_class = serializers.LayerSerializer
@@ -275,6 +274,7 @@ def destroy(self, request, **kwargs):
 
 
 class FormationNodeViewSet(OwnerViewSet):
+    """RESTful views for :class:`~api.models.Node`."""
 
     model = models.Node
     serializer_class = serializers.NodeSerializer
@@ -298,6 +298,7 @@ def destroy(self, request, **kwargs):
 
 
 class FormationContainerViewSet(OwnerViewSet):
+    """RESTful views for :class:`~api.models.Container`."""
 
     model = models.Container
     serializer_class = serializers.ContainerSerializer
@@ -315,6 +316,7 @@ def get_object(self, *args, **kwargs):
 
 
 class FormationImageViewSet(OwnerViewSet):
+    """RESTful views for :class:`~api.models.Image`."""
 
     model = models.Release
     serializer_class = serializers.ReleaseSerializer
@@ -339,6 +341,7 @@ def reset_image(self, request, *args, **kwargs):
 
 
 class FormationConfigViewSet(OwnerViewSet):
+    """RESTful views for :class:`~api.models.Config`."""
 
     model = models.Config
     serializer_class = serializers.ConfigSerializer
@@ -382,6 +385,7 @@ def create(self, request, *args, **kwargs):
 
 
 class FormationBuildViewSet(OwnerViewSet):
+    """RESTful views for :class:`~api.models.Build`."""
 
     model = models.Build
     serializer_class = serializers.BuildSerializer
@@ -412,6 +416,7 @@ def create(self, request, *args, **kwargs):
 
 
 class FormationReleaseViewSet(OwnerViewSet):
+    """RESTful views for :class:`~api.models.Release`."""
 
     model = models.Release
     serializer_class = serializers.ReleaseSerializer

deis/settings.py

@@ -248,7 +248,8 @@
 # EMAIL_HOST_USER = 'foo'
 # EMAIL_HOST_PASSWORD = 'bar'
 
+
 try:
     from .local_settings import *  # @UnusedWildImport # noqa
 except ImportError:
-    print('No deis/local_settings.py file found!')
+    print('\033[96mdeis/local_settings.py \033[91mfile not found!\033[0m')