Fixes import formatting and docstrings.

Author: FranciscoCanas

src/freeseer/frontend/controller/configuration.py

@@ -22,14 +22,19 @@
 # For support, questions, suggestions or any other inquiries, visit:
 # http://wiki.github.com/Freeseer/freeseer/
 import signal
-
-from flask import Blueprint, request
 import re
-from freeseer import settings, logging
+
+from flask import Blueprint
+from flask import request
+
+from freeseer import settings
+from freeseer import logging
 from freeseer.framework.config.exceptions import InvalidOptionValueError
-from freeseer.framework.config.profile import ProfileDoesNotExist, ProfileAlreadyExists
+from freeseer.framework.config.profile import ProfileDoesNotExist
+from freeseer.framework.config.profile import ProfileAlreadyExists
 from freeseer.framework.plugin import PluginManager
-from freeseer.frontend.controller.server import http_response, HTTPError
+from freeseer.frontend.controller.server import http_response
+from freeseer.frontend.controller.server import HTTPError
 
 log = logging.getLogger(__name__)
 configuration = Blueprint('configuration', __name__)
@@ -72,6 +77,9 @@
 def map_plugin_name(plugin):
     """
     Maps a resource name to a plugin name.
+
+    Raises:
+        HTTPError: If no plugin exists by given name.
     """
     try:
         name = plugin_names_map[plugin]
@@ -80,22 +88,33 @@ def map_plugin_name(plugin):
     return name
 
 
-def map_plugin_category(plugin_type):
+def map_plugin_category(category):
     """
-    Maps a resource name to a plugin category name.
+    Maps a plugin category resource name to a plugin category name.
+
+    Raises:
+        HTTPError: If no plugin category exists by given name.
     """
     try:
-        category = plugin_types_map[plugin_type]
+        category = plugin_types_map[category]
     except KeyError:
-        raise HTTPError('Invalid Plugin Category: {}'.format(plugin_type), 400)
+        raise HTTPError('Invalid Plugin Category: {}'.format(category), 400)
     return category
 
 
 def update_config(config, data):
     """
-    Updates given Config instance with request data.
+    Updates given config instance with request data.
+
+    Args:
+        config: A Configuration instance.
+        data: A key, value dict containing changes to config.
+
+    Raises:
+        HTTPError: If given data changes don't conform to config's schema.
     """
     for key, value in data.items():
+        # TODO: Add json-schema validation when pr #646 is merged.
         try:
             opt_instance = config.options[key]
             value = opt_instance.decode(value)
@@ -110,23 +129,28 @@ def update_config(config, data):
 @configuration.before_app_first_request
 def configure_configuration():
     """
-    Initializes the profile, configuration, and plugin manager.
     Runs on first call to server.
     """
     signal.signal(signal.SIGINT, teardown_configuration)
 
 
-def load_configuration(profile):
+def load_profile_configuration(profile):
     """
     Returns the configuration for a given profile.
+
+    Raises:
+        HTTPError: If profile does not exist.
     """
     profile_instance = load_profile(profile)
     return profile_instance.get_config('freeseer.conf', settings.FreeseerConfig, storage_args=['Global'], read_only=False)
 
 
 def load_profile(profile):
     """
-    Returns the profile instance for a given profile.
+    Returns the profile instance for a given profile name.
+
+    Raises:
+        HTTPError: If profile does not exist.
     """
     try:
         profile = settings.profile_manager.get(profile, create_if_needed=False)
@@ -135,6 +159,31 @@ def load_profile(profile):
     return profile
 
 
+def get_plugin_config(profile, category, plugin, id):
+    """
+    Returns the config instance for the given id, plugin, category, and profile.
+
+    Args:
+        profile: Name of a freeseer profile.
+        category: Resource name for a category plugin.
+        plugin: Resource name for a plugin type.
+        id: The instance number for a plugin.
+
+    Raises:
+        HTTPError: If profile, category, or plugin don't exist.
+    """
+    profile_instance = load_profile(profile)
+    plugin_manager = PluginManager(profile_instance)
+    plugin = plugin_manager.get_plugin_by_name(map_plugin_name(plugin),
+                                               map_plugin_category(category))
+    if not plugin:
+        raise HTTPError('No plugin {} of type {}'.format(plugin, category))
+
+    plugin_object = plugin.plugin_object
+    plugin_object.set_instance(id)
+    return plugin_object.config
+
+
 def teardown_configuration(signum, frame):
     """
     Teardown method for configuration api.
@@ -161,9 +210,12 @@ def list_profiles():
 @http_response(200)
 def view_profile(profile):
     """
-    View the configuration profile specified by :profile.
+    View the configuration profile specified by profile.
+
+    Raises:
+        HTTPError: If profile doesn't exist.
     """
-    profile_configuration = load_configuration(profile)
+    profile_configuration = load_profile_configuration(profile)
     return {'profile_configuration': profile_configuration.values}
 
 
@@ -172,6 +224,9 @@ def view_profile(profile):
 def create_profile():
     """
     Create new profile under 'name' specified in request arg.
+
+    Raises:
+        HTTPError: If profile name is invalid, or profile already exists..
     """
     pattern = '^\w+$'
     profile_name = request.form['name']
@@ -189,7 +244,10 @@ def create_profile():
 @http_response(204)
 def delete_profile(profile):
     """
-    Delete the profile specified by :profile.
+    Delete the profile specified by profile.
+
+    Raises:
+        HTTPError: If profile doesn't exist.
     """
     try:
         settings.profile_manager.delete(profile)
@@ -202,9 +260,13 @@ def delete_profile(profile):
 @http_response(200)
 def modify_profile(profile):
     """
-    Modify the profile specified by :profile.
+    Modify the profile specified by given profile name.
+
+    Raises:
+        HTTPError: If profile doesn't exist, or changes don't conform
+            to Config's schema.
     """
-    profile_configuration = load_configuration(profile)
+    profile_configuration = load_profile_configuration(profile)
     changes = request.form
     update_config(profile_configuration, changes)
     return ''
@@ -223,9 +285,12 @@ def modify_profile(profile):
 @http_response(200)
 def view_general_configuration(profile):
     """
-    Returns the general configuration for the given :profile.
+    Returns the general configuration for the given profile.
+
+    Raises:
+        HTTPError: If profile does not exist.
     """
-    profile_configuration = load_configuration(profile)
+    profile_configuration = load_profile_configuration(profile)
     return {
         'default_language': profile_configuration.default_language,
         'auto_hide': profile_configuration.auto_hide,
@@ -236,9 +301,13 @@ def view_general_configuration(profile):
 @http_response(200)
 def modify_general_configuration(profile):
     """
-    Modifies the general configuration for the given :profile.
+    Modifies the general configuration for the given profile.
+
+    Raises:
+        HTTPError: If profile does not exist or changes don't conform to
+            Config's schema.
     """
-    profile_configuration = load_configuration(profile)
+    profile_configuration = load_profile_configuration(profile)
     changes = request.form
     update_config(profile_configuration, changes)
     return ''
@@ -255,9 +324,12 @@ def modify_general_configuration(profile):
 @http_response(200)
 def view_recording_configuration(profile):
     """
-    Returns the recording configuration for the given :profile.
+    Returns the recording configuration for the given profile.
+
+    Raises:
+        HTTPError: If profile does not exist.
     """
-    profile_configuration = load_configuration(profile)
+    profile_configuration = load_profile_configuration(profile)
     return {
         'record_to_file': profile_configuration.record_to_file,
         'videodir': profile_configuration.videodir,
@@ -275,9 +347,13 @@ def view_recording_configuration(profile):
 @http_response(200)
 def modify_recording_configuration(profile):
     """
-    Modifies the recording configuration for the given :profile.
+    Modifies the recording configuration for the given profile.
+
+    Raises:
+        HTTPError: If profile does not exist or changes don't conform
+            to Config's schema.
     """
-    profile_configuration = load_configuration(profile)
+    profile_configuration = load_profile_configuration(profile)
     changes = request.form
     update_config(profile_configuration, changes)
     return ''
@@ -293,9 +369,12 @@ def modify_recording_configuration(profile):
 @http_response(200)
 def list_plugin_category(profile, category):
     """
-    List the available plugins for the given :profile and plugin :category.
+    List the available plugins for the given profile and plugin category.
+
+    Raises:
+        HTTPError: If profile, or category do not exist.
     """
-    profile_configuration = load_configuration(profile)
+    profile_configuration = load_profile_configuration(profile)
     plugin_manager = PluginManager(profile_configuration)
     plugin_infos = plugin_manager.get_plugins_of_category(map_plugin_category(category))
     return {
@@ -314,7 +393,8 @@ def list_plugin_category(profile, category):
 @http_response(200)
 def list_plugin_instances(profile, category, plugin):
     """
-    List existing plugin instances for the given :profile, plugin :category, and :plugin type..
+    List existing plugin instances for the given profile, plugin category,
+    and plugin type.
     """
     raise HTTPError('Unimplemented', 501)
 
@@ -323,24 +403,24 @@ def list_plugin_instances(profile, category, plugin):
 @http_response(200)
 def view_plugin_instance(profile, category, plugin, id):
     """
-    View the config for instance :id of the given :profile, plugin :category, and :plugin type..
+    View the config for instance id of the given profile, plugin category,
+    and plugin type.
+
+    Raises:
+        HTTPError: If profile, category, or plugin do not exist.
     """
-    profile_instance = load_profile(profile)
-    plugin_manager = PluginManager(profile_instance)
-    plugin = plugin_manager.get_plugin_by_name(map_plugin_name(plugin),
-                                               map_plugin_category(category))
-    plugin_object = plugin.plugin_object
-    plugin_object.set_instance(id)
+    plugin_config = get_plugin_config(profile, category, plugin, id)
     return {
-        'configuration': plugin_object.config.values
+        'configuration': plugin_config.values
     }
 
 
 @configuration.route('/profiles/<string:profile>/recording/<string:category>/<string:plugin>', methods=['POST'])
 @http_response(200)
 def create_plugin_instance(profile, category, plugin):
     """
-    Create a new instance of a plugin for the given :profile, plugin :category, and :plugin type.
+    Create a new instance of a plugin for the given profile, plugin category,
+    and plugin type.
     """
     raise HTTPError('Unimplemented', 501)
 
@@ -350,16 +430,16 @@ def create_plugin_instance(profile, category, plugin):
 @http_response(200)
 def modify_plugin_instance(profile, category, plugin, id):
     """
-    Modify the config for an instance :id of the plugin for the given :profile, plugin :category, and :plugin type.
+    Modify the config for an instance id of the plugin for the given profile,
+    and plugin category.
+
+    Raises:
+        HTTPError: If profile, category, or plugin do not exist, or if
+            changes do not conform to Config's schema.
     """
-    profile_instance = load_profile(profile)
-    plugin_manager = PluginManager(profile_instance)
-    plugin = plugin_manager.get_plugin_by_name(map_plugin_name(plugin),
-                                               map_plugin_category(category))
-    plugin_object = plugin.plugin_object
-    plugin_object.set_instance(id)
+    plugin_config = get_plugin_config(profile, category, plugin, id)
     changes = request.form
-    update_config(plugin_object.config, changes)
+    update_config(plugin_config, changes)
     return ''
 #
 # End of plugin endpoints.