Add some notes about where we are at now

services/workflow/src/workflow/server.py

@@ -10,6 +10,28 @@ from sqlalchemy.ext.declarative import declarative_base
 from sqlalchemy.orm import sessionmaker
 
 
+"""
+Work done:
+
+ ☑ Initial sketch of using SQL Alchemy with Pyramid
+ ☑ Sketch of first routes we need
+
+Work to do:
+
+ ☐ Bring over interfaces from wksp0 project
+ ☐ Need to flesh out the object model—requests have their own files, workflows have templates
+ ☐ Separate REST hierarchy for workflow definitions
+ ☐ Actually do the work, preferably in model classes, not REST API directly
+ ☐ Separate this into separate modules, once it makes sense to people how it works
+ ☐ Workflow initiation CLI
+
+To consider:
+ ☐ Do we want to use Marshmallow to validate inputs/generate API documentation?
+ ☐ Do we want to have a separate package with interfaces/model? Or perhaps only JSON schemas?
+
+"""
+
+
 # ---------------------------------------------------------
 #
 #    M O D E L
@@ -42,22 +64,31 @@ WORKFLOWS = [{'id': 1, 'name': 'foo', 'files': {'file.txt': {'id': 1, 'name': 'f
 
 
 def lookup_workflow(request):
+    # this should change to use SQL Alchemy
     return WORKFLOWS[int(request.matchdict['id'])]
 
 
 def lookup_file(request):
+    # this should change to use SQL Alchemy
     return lookup_workflow(request)['files'][request.matchdict['filename']]
 
 
 @view_defaults(route_name='workflows', renderer='json')
 class WorkflowService:
+    """
+    Top-level service for workflow requests.
+
+    TODO: rename this to requests and add new service about workflow definitions with this name
+    """
     def __init__(self, request):
         self.request = request
 
     @view_config(request_method='GET')
     def list_workflows(self):
         """
-        List the workflow requests that we know about
+        List the workflow requests that we know about.
+
+        Audience: front-end
         :return:
         """
         return self.request.dbsession.query(Workflow).all()
@@ -65,7 +96,9 @@ class WorkflowService:
     @view_config(request_method='POST')
     def create_workflow(self):
         """
-        Create a new workflow request
+        Create a new workflow request from the name/arguments supplied.
+
+        Audience: front-end and CLI
         :return:
         """
         WORKFLOWS.append(self.request.json_body)
@@ -75,6 +108,8 @@ class WorkflowService:
     def get_workflow(self):
         """
         Look up a workflow request
+
+        Audience: front-end
         :return:
         """
         return self.request.context
@@ -83,6 +118,8 @@ class WorkflowService:
     def submit_workflow(self):
         """
         Submit this workflow request for processing.
+
+        Audience: front-end and CLI
         :return:
         """
         print(f"Submitting workflow {self.request.context['id']}")
@@ -99,14 +136,18 @@ class WorkflowFilesService:
     @view_config(request_method='POST')
     def add_file(self):
         """
-        Add a file to this workflow request
+        Add a file to this workflow request.
+
+        Audience: front-end and CLI
         """
         print('Adding a file')
 
     @view_config(request_method='GET')
     def get_files(self):
         """
-        Get the files associated with this workflow request
+        Get the files associated with this workflow request.
+
+        Audience: front-end
         :return:
         """
         return self.request.context['files']
@@ -115,6 +156,8 @@ class WorkflowFilesService:
     def get_file_text(self):
         """
         Get the text contents of this file
+
+        Audience: ???
         :return:
         """
         return self.request.context['content']
@@ -123,6 +166,8 @@ class WorkflowFilesService:
     def get_file_json(self):
         """
         Get a JSON representation of this file
+
+        Audience: ???
         :return:
         """
         return self.request.context