Some cleanup of documentation and licenses

* mainly clean up to double check things
  and help ensure anyone looking at this code
  can get enough of an idea of things from the README
  and code.
* also removing a catalyst specific line from the README

Change-Id: I648e668553970f2934d1608b8af89448990e3d3d

README.md

@@ -168,7 +168,7 @@ If that was the case, the system should ideally also have been modular enough to
 
 #### What is an Action?
 
-Actions are a generic database model which knows what 'type' of action it is. On pulling the actions related to a Task from the database we wrap it into the appropriate class type which handlings all the logic associated with that action type.
+Actions are a generic database model which knows what 'type' of action it is. On pulling the actions related to a Task from the database we wrap it into the appropriate class type which handles all the logic associated with that action type.
 
 An Action is both a simple database representation of itself, and a more complex in memory class that handles all the logic around it.
 
@@ -245,7 +245,7 @@ $ stacktask runserver
 
 We use tox to build a venv and run the tests. The same tests are also run for us in CI via jenkins.
 
-Provided you have tox and it's requirements installed running tests is very simple:
+Provided you have tox and its requirements installed running tests is very simple:
 
 ```
 $ tox
@@ -253,7 +253,7 @@ $ tox
 
 ### Adding Actions:
 
-Adding new actions is done by creating a new django app and defining the action models and their serializers. Action must extend the BaseAction class as defined in the **actions.models** module. They also must add themselves to the global store of actions (see the bottom of existing models modules).
+Adding new actions is done by creating a new django app in the actions module and defining the action models and their serializers. Action must extend the BaseAction class as defined in the **actions.models** module. They also must add themselves to the global store of actions (see the bottom of existing models modules).
 
 The documentation for this is mainly inline.
 
@@ -279,7 +279,6 @@ Build the package:
   dpkg-buildpackage -us -uc
 
 Now a debian package has been built that will unpack a virtualenv containing stacktask and all dependencies in a self-contained package, so they do not conflict with other python packages on the system.
-Upload the package to repo-private: https://wiki.wgtn.cat-it.co.nz/wiki/Repo-private#APT
 
 ### Puppet module
 Then a puppet module will be able to install the debian package, setup a database, and run the service via nginx and uwsgi in the virtualenv.
@@ -294,7 +293,7 @@ Then a puppet module will be able to install the debian package, setup a databas
 
 Most future plans are around adding additional Actions to the service, but there will be some features that will require some refactoring.
 
-We are presently only working with the Keystone V2 API, but we intend to update the service to also manage and handle user groups. Managing Domains isn't really doable, but having the service be able to accept Domains, and multiple Domain back-ends is being planned.
+While we are presently working with the Keystone V3 API, groups are not being used, but we intend to update the service to also manage and handle user groups. Managing Domains isn't really doable, but having the service be able to accept Domains, and multiple Domain back-ends is being planned.
 
 Additional Actions we wish to add in the near future:
 
@@ -324,6 +323,8 @@ Features that might require a slight refactor:
 
 Even less likely, and further far-future additions:
 
+* Split the system into the api, a queue, and workers. That way tasks are processed asynchronously by the workers.
+  * Will require a bunch of rethinking, but most of the core logic will be reused, with the workers simply waiting for events and executing them on the tasks/actions in much the same way as they are presently.
 * Remove concept of predefined action steps entirely, setup Actions to have any possible number of 'steps'.
   * Will require moving actions to an iterator style pattern with a "next_action" style function as the driving force.
   * Will alter how chaining actions together works, thus may require a lot of work to define a sensible pattern for chaining them together.

stacktask/__init__.py

@@ -1,3 +1,18 @@
+# Copyright (C) 2015 Catalyst IT Ltd
+#
+#    Licensed under the Apache License, Version 2.0 (the "License"); you may
+#    not use this file except in compliance with the License. You may obtain
+#    a copy of the License at
+#
+#         http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#    License for the specific language governing permissions and limitations
+#    under the License.
+
+
 def management_command():
     """Entry-point for the 'stacktask' command-line admin utility."""
     import os

stacktask/actions/openerp/models.py

@@ -1,3 +1,17 @@
+# Copyright (C) 2015 Catalyst IT Ltd
+#
+#    Licensed under the Apache License, Version 2.0 (the "License"); you may
+#    not use this file except in compliance with the License. You may obtain
+#    a copy of the License at
+#
+#         http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#    License for the specific language governing permissions and limitations
+#    under the License.
+
 from actions.models import BaseAction
 from serializers import NewClientSerializer
 from django.conf import settings

stacktask/actions/user_store.py

@@ -63,6 +63,12 @@ class IdentityManager(object):
         return user
 
     def list_users(self, project):
+        """
+        Build a list of users for a given project using
+        the v3 api. Less straightforward than the v2 api,
+        but because we have the role data already, we add it
+        to the user model so later roles fetching is not needed.
+        """
         try:
             roles = self.ks_client.roles.list()
             role_dict = {role.id: role for role in roles}
@@ -108,6 +114,8 @@ class IdentityManager(object):
     def get_all_roles(self, user):
         """
         Returns roles for a given user across all projects.
+
+        Uses the new v3 assignments api method to quickly do this.
         """
         roles = self.ks_client.roles.list()
         role_dict = {role.id: role for role in roles}

stacktask/actions/views.py

@@ -1,17 +0,0 @@
-# Copyright (C) 2015 Catalyst IT Ltd
-#
-#    Licensed under the Apache License, Version 2.0 (the "License"); you may
-#    not use this file except in compliance with the License. You may obtain
-#    a copy of the License at
-#
-#         http://www.apache.org/licenses/LICENSE-2.0
-#
-#    Unless required by applicable law or agreed to in writing, software
-#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-#    License for the specific language governing permissions and limitations
-#    under the License.
-
-from django.shortcuts import render
-
-# Create your views here.

stacktask/middleware.py

@@ -11,6 +11,7 @@
 #    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 #    License for the specific language governing permissions and limitations
 #    under the License.
+
 from time import time
 from logging import getLogger
 from django.utils import timezone

stacktask/notifications/models.py

@@ -35,7 +35,7 @@ class NotificationEngine(object):
 class EmailNotification(NotificationEngine):
     """
     Basic email notification engine. Will
-    send an email in the given templates.
+    send an email with the given templates.
 
     Example conf:
         <TaskView>:

stacktask/settings.py

@@ -13,13 +13,13 @@
 #    under the License.
 
 """
-Django settings for user_reg project.
+Django settings for StackTask.
 
 For more information on this file, see
-https://docs.djangoproject.com/en/1.7/topics/settings/
+https://docs.djangoproject.com/en/1.8/topics/settings/
 
 For the full list of settings and their values, see
-https://docs.djangoproject.com/en/1.7/ref/settings/
+https://docs.djangoproject.com/en/1.8/ref/settings/
 """
 
 # Build paths inside the project like this: os.path.join(BASE_DIR, ...)
@@ -30,10 +30,6 @@ from stacktask.utils import setup_task_settings
 BASE_DIR = os.path.dirname(os.path.dirname(__file__))
 
 
-# Quick-start development settings - unsuitable for production
-# See https://docs.djangoproject.com/en/1.7/howto/deployment/checklist/
-
-
 TEMPLATE_DEBUG = True
 
 # Application definition
@@ -93,7 +89,8 @@ if 'test' in sys.argv:
 else:
     config_file = "/etc/stacktask/conf.yaml"
     if not os.path.isfile(config_file):
-        print "%s does not exist. Reverting to default config file." % config_file
+        print ("%s does not exist. Reverting to default config file." %
+               config_file)
         config_file = "conf/conf.yaml"
     with open(config_file) as f:
         CONFIG = yaml.load(f)

stacktask/utils.py

@@ -1,3 +1,17 @@
+# Copyright (C) 2015 Catalyst IT Ltd
+#
+#    Licensed under the Apache License, Version 2.0 (the "License"); you may
+#    not use this file except in compliance with the License. You may obtain
+#    a copy of the License at
+#
+#         http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#    License for the specific language governing permissions and limitations
+#    under the License.
+
 from copy import deepcopy
 
 

stacktask/wsgi.py

@@ -13,26 +13,27 @@
 #    under the License.
 
 """
-WSGI config for user_reg project.
+WSGI config for StackTask.
 
 It exposes the WSGI callable as a module-level variable named ``application``.
 
 For more information on this file, see
-https://docs.djangoproject.com/en/1.7/howto/deployment/wsgi/
+https://docs.djangoproject.com/en/1.8/howto/deployment/wsgi/
 """
 
 import os
-os.environ.setdefault("DJANGO_SETTINGS_MODULE", "stacktask.settings")
-
 from django.core.wsgi import get_wsgi_application
-application = get_wsgi_application()
-
-
 from django.conf import settings
-
 from urlparse import urlparse
 from keystonemiddleware.auth_token import AuthProtocol
 
+os.environ.setdefault("DJANGO_SETTINGS_MODULE", "stacktask.settings")
+
+
+application = get_wsgi_application()
+
+# Here we replace the default application with one wrapped by
+# the Keystone Auth Middleware.
 identity_url = urlparse(settings.KEYSTONE['auth_url'])
 conf = {
     'admin_user': settings.KEYSTONE['username'],