docs for handlers

docs/develop/api_doc.rst

@@ -52,12 +52,6 @@ Logs API
 .. automodule:: nailgun.api.handlers.logs
 
 
-OSTF API
------------------
-
-.. automodule:: nailgun.api.handlers.ostf
-
-
 Plugin API
 ----------
 

nailgun/nailgun/api/handlers/disks.py

@@ -14,6 +14,10 @@
 #    License for the specific language governing permissions and limitations
 #    under the License.
 
+"""
+Handlers dealing with disks
+"""
+
 import web
 import traceback
 
@@ -29,17 +33,31 @@ from nailgun.logger import logger
 
 
 class NodeDisksHandler(JSONHandler):
+    """
+    Node disks handler
+    """
 
     validator = NodeDisksValidator
 
     @content_json
     def GET(self, node_id):
+        """
+        :returns: JSONized node disks.
+        :http: * 200 (OK)
+               * 404 (node not found in db)
+        """
         node = self.get_object_or_404(Node, node_id)
         node_volumes = node.attributes.volumes
         return DisksFormatConvertor.format_disks_to_simple(node_volumes)
 
     @content_json
     def PUT(self, node_id):
+        """
+        :returns: JSONized node disks.
+        :http: * 200 (OK)
+               * 400 (invalid disks data specified)
+               * 404 (node not found in db)
+        """
         node = self.get_object_or_404(Node, node_id)
         data = self.checked_data()
 
@@ -61,9 +79,17 @@ class NodeDisksHandler(JSONHandler):
 
 
 class NodeDefaultsDisksHandler(JSONHandler):
+    """
+    Node default disks handler
+    """
 
     @content_json
     def GET(self, node_id):
+        """
+        :returns: JSONized node disks.
+        :http: * 200 (OK)
+               * 404 (node or its attributes not found in db)
+        """
         node = self.get_object_or_404(Node, node_id)
         if not node.attributes:
             return web.notfound()
@@ -75,9 +101,17 @@ class NodeDefaultsDisksHandler(JSONHandler):
 
 
 class NodeVolumesInformationHandler(JSONHandler):
+    """
+    Node volumes information handler
+    """
 
     @content_json
     def GET(self, node_id):
+        """
+        :returns: JSONized volumes info for node.
+        :http: * 200 (OK)
+               * 404 (node not found in db)
+        """
         node = self.get_object_or_404(Node, node_id)
 
         volumes_info = []

nailgun/nailgun/api/handlers/logs.py

@@ -14,6 +14,10 @@
 #    License for the specific language governing permissions and limitations
 #    under the License.
 
+"""
+Handlers dealing with logs
+"""
+
 import re
 import os
 import time
@@ -68,9 +72,39 @@ def read_backwards(file, bufsize=4096):
 
 
 class LogEntryCollectionHandler(JSONHandler):
+    """
+    Log entry collection handler
+    """
 
     @content_json
     def GET(self):
+        """
+        Receives following parameters:
+
+        - *date_before* - get logs before this date
+        - *date_after* - get logs after this date
+        - *source* - source of logs
+        - *node* - node id (for getting node logs)
+        - *level* - log level (all levels showed by default)
+        - *to* - number of entries
+        - *max_entries* - max number of entries to load
+
+        :returns: Collection of log entries, log file size
+        and if there are new entries.
+        :http: * 200 (OK)
+               * 400 (invalid *date_before* value)
+               * 400 (invalid *date_after* value)
+               * 400 (invalid *source* value)
+               * 400 (invalid *node* value)
+               * 400 (invalid *level* value)
+               * 400 (invalid *to* value)
+               * 400 (invalid *max_entries* value)
+               * 404 (log file not found)
+               * 404 (log files dir not found)
+               * 404 (node not found)
+               * 500 (node has no assigned ip)
+               * 500 (invalid regular expression in config)
+        """
         user_data = web.input()
         date_before = user_data.get('date_before')
         if date_before:
@@ -257,6 +291,9 @@ class LogEntryCollectionHandler(JSONHandler):
 
 
 class LogPackageHandler(object):
+    """
+    Log package handler
+    """
 
     def sed(self, from_filename, to_filename, gz=False):
         accounts = db().query(RedHatAccount).all()
@@ -293,6 +330,10 @@ class LogPackageHandler(object):
         tf.close()
 
     def GET(self):
+        """
+        :returns: logs packed into TAR.GZ archive.
+        :http: * 200 (OK)
+        """
         f = tempfile.TemporaryFile(mode='r+b')
         tf = tarfile.open(fileobj=f, mode='w:gz')
 
@@ -327,16 +368,31 @@ class LogPackageHandler(object):
 
 
 class LogSourceCollectionHandler(JSONHandler):
+    """
+    Log source collection handler
+    """
 
     @content_json
     def GET(self):
+        """
+        :returns: Collection of log sources (from settings)
+        :http: * 200 (OK)
+        """
         return settings.LOGS
 
 
 class LogSourceByNodeCollectionHandler(JSONHandler):
+    """
+    Log source by node collection handler
+    """
 
     @content_json
     def GET(self, node_id):
+        """
+        :returns: Collection of log sources by node (from settings)
+        :http: * 200 (OK)
+               * 404 (node not found in db)
+        """
         node = self.get_object_or_404(Node, node_id)
 
         def getpath(x):

nailgun/nailgun/api/handlers/network_configuration.py

@@ -14,6 +14,10 @@
 #    License for the specific language governing permissions and limitations
 #    under the License.
 
+"""
+Handlers dealing with network configurations
+"""
+
 import json
 import traceback
 import web
@@ -37,11 +41,22 @@ from nailgun.api.serializers.network_configuration \
 
 
 class NetworkConfigurationVerifyHandler(JSONHandler):
+    """
+    Network configuration verify handler
+    """
 
     validator = NetworkConfigurationValidator
 
     @content_json
     def PUT(self, cluster_id):
+        """
+        :IMPORTANT: this method should be rewritten to be more RESTful
+
+        :returns: JSONized Task object.
+        :http: * 202 (network checking task failed)
+               * 200 (network verification task started)
+               * 404 (cluster not found in db)
+        """
         cluster = self.get_object_or_404(Cluster, cluster_id)
 
         try:
@@ -68,16 +83,29 @@ class NetworkConfigurationVerifyHandler(JSONHandler):
 
 
 class NetworkConfigurationHandler(JSONHandler):
+    """
+    Network configuration handler
+    """
 
     validator = NetworkConfigurationValidator
     serializer = NetworkConfigurationSerializer
 
     @content_json
     def GET(self, cluster_id):
+        """
+        :returns: JSONized network configuration for cluster.
+        :http: * 200 (OK)
+               * 404 (cluster not found in db)
+        """
         cluster = self.get_object_or_404(Cluster, cluster_id)
         return self.serializer.serialize_for_cluster(cluster)
 
     def PUT(self, cluster_id):
+        """
+        :returns: JSONized Task object.
+        :http: * 202 (network checking task created)
+               * 404 (cluster not found in db)
+        """
         data = json.loads(web.data())
         cluster = self.get_object_or_404(Cluster, cluster_id)
 

nailgun/nailgun/api/handlers/notifications.py

@@ -14,6 +14,10 @@
 #    License for the specific language governing permissions and limitations
 #    under the License.
 
+"""
+Handlers dealing with notifications
+"""
+
 import json
 import logging
 
@@ -27,6 +31,10 @@ from nailgun.settings import settings
 
 
 class NotificationHandler(JSONHandler):
+    """
+    Notification single handler
+    """
+
     fields = (
         "id",
         "cluster",
@@ -56,11 +64,22 @@ class NotificationHandler(JSONHandler):
 
     @content_json
     def GET(self, notification_id):
+        """
+        :returns: JSONized Notification object.
+        :http: * 200 (OK)
+               * 404 (notification not found in db)
+        """
         notification = self.get_object_or_404(Notification, notification_id)
         return self.render(notification)
 
     @content_json
     def PUT(self, notification_id):
+        """
+        :returns: JSONized Notification object.
+        :http: * 200 (OK)
+               * 400 (invalid notification data specified)
+               * 404 (notification not found in db)
+        """
         notification = self.get_object_or_404(Notification, notification_id)
         data = self.validator.validate_update(web.data())
         for key, value in data.iteritems():
@@ -76,6 +95,10 @@ class NotificationCollectionHandler(JSONHandler):
 
     @content_json
     def GET(self):
+        """
+        :returns: Collection of JSONized Notification objects.
+        :http: * 200 (OK)
+        """
         user_data = web.input(limit=settings.MAX_ITEMS_PER_PAGE)
         limit = user_data.limit
         query = db().query(Notification).limit(limit)
@@ -87,6 +110,11 @@ class NotificationCollectionHandler(JSONHandler):
 
     @content_json
     def PUT(self):
+        """
+        :returns: Collection of JSONized Notification objects.
+        :http: * 200 (OK)
+               * 400 (invalid data specified for collection update)
+        """
         data = self.validator.validate_collection_update(web.data())
         q = db().query(Notification)
         notifications_updated = []

nailgun/nailgun/api/handlers/plugin.py

@@ -14,6 +14,10 @@
 #    License for the specific language governing permissions and limitations
 #    under the License.
 
+"""
+Handlers dealing with plugins
+"""
+
 
 import web
 import json

nailgun/nailgun/api/handlers/redhat.py

@@ -12,6 +12,10 @@
 #    License for the specific language governing permissions and limitations
 #    under the License.
 
+"""
+Handlers dealing with exclusive Red Hat tasks
+"""
+
 import traceback
 
 import web
@@ -32,6 +36,9 @@ from nailgun.settings import settings
 
 
 class RedHatAccountHandler(JSONHandler):
+    """
+    Red Hat account handler
+    """
 
     fields = (
         'username',
@@ -44,6 +51,11 @@ class RedHatAccountHandler(JSONHandler):
 
     @content_json
     def GET(self):
+        """
+        :returns: JSONized RedHatAccount object.
+        :http: * 200 (OK)
+               * 404 (account not found in db)
+        """
         account = db().query(RedHatAccount).first()
         if not account:
             raise web.notfound()
@@ -51,6 +63,12 @@ class RedHatAccountHandler(JSONHandler):
 
     @content_json
     def POST(self):
+        """
+        :returns: JSONized RedHatAccount object.
+        :http: * 200 (OK)
+               * 400 (invalid account data specified)
+               * 404 (account not found in db)
+        """
         data = self.checked_data()
 
         license_type = data.get("license_type")
@@ -75,11 +93,22 @@ class RedHatAccountHandler(JSONHandler):
 
 
 class RedHatSetupHandler(JSONHandler):
+    """
+    Red Hat setup handler
+    """
 
     validator = RedHatAccountValidator
 
     @content_json
     def POST(self):
+        """
+        Starts Red Hat setup and download process
+
+        :returns: JSONized Task object.
+        :http: * 202 (setup task created and started)
+               * 400 (invalid account data specified)
+               * 404 (release not found in db)
+        """
         data = self.checked_data()
 
         license_type = data.get("license_type")

nailgun/nailgun/api/handlers/tasks.py

@@ -22,8 +22,16 @@ from nailgun.db import db
 from nailgun.api.models import Task
 from nailgun.api.handlers.base import JSONHandler, content_json
 
+"""
+Handlers dealing with tasks
+"""
+
 
 class TaskHandler(JSONHandler):
+    """
+    Task single handler
+    """
+
     fields = (
         "id",
         "cluster",
@@ -38,10 +46,21 @@ class TaskHandler(JSONHandler):
 
     @content_json
     def GET(self, task_id):
+        """
+        :returns: JSONized Task object.
+        :http: * 200 (OK)
+               * 404 (task not found in db)
+        """
         task = self.get_object_or_404(Task, task_id)
         return self.render(task)
 
     def DELETE(self, task_id):
+        """
+        :returns: JSONized Cluster object.
+        :http: * 204 (task successfully deleted)
+               * 400 (can't delete running task manually)
+               * 404 (task not found in db)
+        """
         task = self.get_object_or_404(Task, task_id)
         if task.status not in ("ready", "error"):
             raise web.badrequest("You cannot delete running task manually")
@@ -56,9 +75,20 @@ class TaskHandler(JSONHandler):
 
 
 class TaskCollectionHandler(JSONHandler):
+    """
+    Task collection handler
+    """
 
     @content_json
     def GET(self):
+        """
+        May receive cluster_id parameter to filter list
+        of tasks
+
+        :returns: Collection of JSONized Task objects.
+        :http: * 200 (OK)
+               * 404 (task not found in db)
+        """
         user_data = web.input(cluster_id=None)
         if user_data.cluster_id == '':
             tasks = db().query(Task).filter_by(

nailgun/nailgun/api/handlers/version.py

@@ -14,6 +14,10 @@
 #    License for the specific language governing permissions and limitations
 #    under the License.
 
+"""
+Product info handlers
+"""
+
 import os
 import web
 import json
@@ -23,9 +27,16 @@ from nailgun.api.handlers.base import JSONHandler, content_json
 
 
 class VersionHandler(JSONHandler):
+    """
+    Version info handler
+    """
 
     @content_json
     def GET(self):
+        """
+        :returns: FUEL/FUELWeb commit SHA, release version.
+        :http: * 200 (OK)
+        """
         return {
             "sha": str(settings.COMMIT_SHA),
             "release": str(settings.PRODUCT_VERSION),