Re #11 -- more docstring progress

Author: mboersma

api/models.py

@@ -44,8 +44,7 @@ def import_tasks(provider_type):
 
 
 class AuditedModel(models.Model):
-    """Add 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)
@@ -56,8 +55,7 @@ class Meta:
 
 
 class UuidAuditedModel(AuditedModel):
-    """Add a UUID primary key to an audited model.
-    """
+    """Add a UUID primary key to an :class:`AuditedModel`."""
 
     uuid = fields.UuidField('UUID', primary_key=True)
 
@@ -122,11 +120,10 @@ class Meta:
 
 @python_2_unicode_compatible
 class FlavorManager(models.Manager):
-
-    """Manages database interactions for :class:`Flavor`."""
+    """Manage database interactions for :class:`Flavor`."""
 
     def load_cloud_config_base(self):
-        """Read the base configuration file and return the YAML data it contains."""
+        """Read the base configuration file and return YAML data."""
         # load cloud-config-base yaml_
         _cloud_config_path = os.path.abspath(
             os.path.join(__file__, '..', 'files', 'cloud-config-base.yml'))
@@ -198,6 +195,7 @@ class ScalingError(Exception):
 
 @python_2_unicode_compatible
 class FormationManager(models.Manager):
+    """Manage database interactions for :class:`Formation`."""
 
     def publish(self, **kwargs):
         # build data bag
@@ -259,6 +257,7 @@ class Meta:
         unique_together = (('owner', 'id'),)
 
     def scale_layers(self, **kwargs):
+        """Scale layers up or down to match requested."""
         layers = self.layers.copy()
         funcs = []
         for layer_id, requested in layers.items():
@@ -293,6 +292,7 @@ def scale_layers(self, **kwargs):
         return databag
 
     def scale_containers(self, **kwargs):
+        """Scale containers up or down to match requested."""
         requested_containers = self.containers.copy()
         runtime_layers = self.layer_set.filter(id='runtime')
         if len(runtime_layers) < 1:
@@ -389,7 +389,7 @@ def __str__(self):
         return self.id
 
     def calculate(self):
-        "Return a Chef data bag item for this formation"
+        """Return a Chef data bag item for this formation"""
         release = self.release_set.all().order_by('-created')[0]
         d = {}
         d['id'] = self.id
@@ -427,7 +427,7 @@ def calculate(self):
         return d
 
     def converge(self, databag):
-        # call a celery task to update the formation data bag
+        """Call a celery task to update the formation data bag."""
         if settings.CHEF_ENABLED:
             controller.update_formation.delay(self.id, databag).wait()  # @UndefinedVariable
         # TODO: batch node converging by layer.level
@@ -437,7 +437,7 @@ def converge(self, databag):
         return databag
 
     def destroy(self):
-        # create subtasks to terminate all nodes in parallel
+        """Create subtasks to terminate all nodes in parallel."""
         all_layers = self.layer_set.all()
         tasks = [layer.destroy(async=True) for layer in all_layers]
         node_tasks, layer_tasks = [], []
@@ -626,7 +626,7 @@ def destroy(self, async=False):
 class Container(UuidAuditedModel):
 
     """
-    Docker container used to securely host an application process
+    Docker container used to securely host an application process.
     """
 
     owner = models.ForeignKey(settings.AUTH_USER_MODEL)

api/routers.py

@@ -4,45 +4,46 @@
 
 from __future__ import unicode_literals
 
-from rest_framework import routers
+from rest_framework.routers import DefaultRouter
 from rest_framework.routers import Route
 
 
-class ApiRouter(routers.DefaultRouter):
-
-    """Routes UUID interchangeably with owner/handle."""
+class ApiRouter(DefaultRouter):
+    """Generate URL patterns for list, detail, and viewset-specific
+    HTTP routes.
+    """
 
     routes = [
         # List route.
         Route(
-            url=r'^{prefix}/?$',
+            url=r"^{prefix}/?$",
             mapping={
                 'get': 'list',
                 'post': 'create'
             },
-            name='{basename}-list',
+            name="{basename}-list",
             initkwargs={'suffix': 'List'}
         ),
         # Detail route.
         Route(
-            url=r'^{prefix}/{lookup}/?$',
+            url=r"^{prefix}/{lookup}/?$",
             mapping={
                 'get': 'retrieve',
                 'put': 'update',
                 'patch': 'partial_update',
                 'delete': 'destroy'
             },
-            name='{basename}-detail',
+            name="{basename}-detail",
             initkwargs={'suffix': 'Instance'}
         ),
         # Dynamically generated routes, from @action or @link decorators
         # on methods of the viewset.
         Route(
-            url=r'^{prefix}/{lookup}/{methodname}/?$',
+            url=r"^{prefix}/{lookup}/{methodname}/?$",
             mapping={
-                '{httpmethod}': '{methodname}',
+                "{httpmethod}": "{methodname}",
             },
-            name='{basename}-{methodnamehyphen}',
+            name="{basename}-{methodnamehyphen}",
             initkwargs={}
         ),
     ]

api/serializers.py

@@ -13,8 +13,7 @@
 
 
 class UserSerializer(serializers.ModelSerializer):
-
-    """Serializes a User model."""
+    """Serialize a :class:`~api.models.User` model."""
 
     class Meta:
         """Metadata options for a UserSerializer."""
@@ -24,7 +23,7 @@ class Meta:
 
     @property
     def data(self):
-        "Custom data property that removes secure user fields"
+        """Custom data property that removes secure user fields"""
         d = super(UserSerializer, self).data
         for f in ('password',):
             if f in d:
@@ -33,8 +32,7 @@ def data(self):
 
 
 class KeySerializer(serializers.ModelSerializer):
-
-    """Serializes a Key model."""
+    """Serialize a :class:`~api.models.Key` model."""
 
     owner = serializers.Field(source='owner.username')
 
@@ -45,8 +43,7 @@ class Meta:
 
 
 class ProviderSerializer(serializers.ModelSerializer):
-
-    """Serializes a Provider model."""
+    """Serialize a :class:`~api.models.Provider` model."""
 
     owner = serializers.Field(source='owner.username')
 
@@ -57,84 +54,78 @@ class Meta:
 
 
 class FlavorSerializer(serializers.ModelSerializer):
-
-    """Serializes a Flavor model."""
+    """Serialize a :class:`~api.models.Flavor` model."""
 
     owner = serializers.Field(source='owner.username')
     provider = serializers.SlugRelatedField(slug_field='id')
 
     class Meta:
-        """Metadata options for a FlavorSerializer."""
+        """Metadata options for a :class:`FlavorSerializer`."""
         model = models.Flavor
         read_only_fields = ('created', 'updated')
 
 
 class ConfigSerializer(serializers.ModelSerializer):
-
-    """Serializes a Config model."""
+    """Serialize a :class:`~api.models.Config` model."""
 
     owner = serializers.Field(source='owner.username')
     formation = serializers.SlugRelatedField(slug_field='id')
     values = serializers.ModelField(
         model_field=models.Config()._meta.get_field('values'), required=False)
 
     class Meta:
-        """Metadata options for a ConfigSerializer."""
+        """Metadata options for a :class:`ConfigSerializer`."""
         model = models.Config
         read_only_fields = ('uuid', 'created', 'updated')
 
 
 class BuildSerializer(serializers.ModelSerializer):
-
-    """Serializes a Build model."""
+    """Serialize a :class:`~api.models.Build` model."""
 
     owner = serializers.Field(source='owner.username')
     formation = serializers.SlugRelatedField(slug_field='id')
 
     class Meta:
-        """Metadata options for a BuildSerializer."""
+        """Metadata options for a :class:`BuildSerializer`."""
         model = models.Build
         read_only_fields = ('uuid', 'created', 'updated')
 
 
 class ReleaseSerializer(serializers.ModelSerializer):
-
-    """Serializes a Release model."""
+    """Serialize a :class:`~api.models.Release` model."""
 
     owner = serializers.Field(source='owner.username')
     formation = serializers.SlugRelatedField(slug_field='id')
     config = serializers.SlugRelatedField(slug_field='uuid')
     build = serializers.SlugRelatedField(slug_field='uuid', required=False)
 
     class Meta:
-        """Metadata options for a ReleaseSerializer."""
+        """Metadata options for a :class:`ReleaseSerializer`."""
         model = models.Release
         read_only_fields = ('uuid', 'created', 'updated')
 
 
 class FormationSerializer(serializers.ModelSerializer):
-
-    """Serializes a Formation model."""
+    """Serialize a :class:`~api.models.Formation` model."""
 
     owner = serializers.Field(source='owner.username')
     id = serializers.SlugField(default=utils.generate_app_name)
 
     class Meta:
-        """Metadata options for a FormationSerializer."""
+        """Metadata options for a :class:`FormationSerializer`."""
         model = models.Formation
         read_only_fields = ('created', 'updated')
 
 
 class LayerSerializer(serializers.ModelSerializer):
-
-    """Serializes a Layer model."""
+    """Serialize a :class:`~api.models.Layer` model."""
 
     owner = serializers.Field(source='owner.username')
     formation = serializers.SlugRelatedField(slug_field='id')
     flavor = serializers.SlugRelatedField(slug_field='id')
 
     class Meta:
-        """Metadata options for a LayerSerializer."""
+        """Metadata options for a :class:`LayerSerializer`."""
         model = models.Layer
         read_only_fields = ('created', 'updated')
 
@@ -149,28 +140,26 @@ def data(self):
 
 
 class NodeSerializer(serializers.ModelSerializer):
-
-    """Serializes a Node model."""
+    """Serialize a :class:`~api.models.Node` model."""
 
     owner = serializers.Field(source='owner.username')
     formation = serializers.SlugRelatedField(slug_field='id')
     layer = serializers.SlugRelatedField(slug_field='id')
 
     class Meta:
-        """Metadata options for a NodeSerializer."""
+        """Metadata options for a :class:`NodeSerializer`."""
         model = models.Node
         read_only_fields = ('created', 'updated')
 
 
 class ContainerSerializer(serializers.ModelSerializer):
-
-    """Serializes a Container model."""
+    """Serialize a :class:`~api.models.Container` model."""
 
     owner = serializers.Field(source='owner.username')
     formation = serializers.SlugRelatedField(slug_field='id')
     node = serializers.SlugRelatedField(slug_field='uuid')
 
     class Meta:
-        """Metadata options for a ContainerSerializer."""
+        """Metadata options for a :class:`ContainerSerializer`."""
         model = models.Container
         read_only_fields = ('created', 'updated')