web api app

components/tools/OmeroWeb/omeroweb/api/__init__.py

@@ -0,0 +1,20 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+# Copyright (C) 2016 University of Dundee & Open Microscopy Environment.
+# All rights reserved.
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as
+# published by the Free Software Foundation, either version 3 of the
+# License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+"""api module provides JSON OMERO API."""

components/tools/OmeroWeb/omeroweb/webgateway/api_exceptions.py → components/tools/OmeroWeb/omeroweb/api/api_exceptions.py

@@ -17,38 +17,51 @@
 # You should have received a copy of the GNU Affero General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
+"""Exceptions used by the api/views methods."""
+
 
 class BadRequestError(Exception):
     """
-    An exception that will result in a response status of 400
-    due to invalid client input
+    An exception that will result in a response status of 400.
+
+    Due to invalid client input
     """
+
     status = 400
 
     def __init__(self, message, stacktrace=None):
+        """Override init to handle message and stacktrace."""
         super(BadRequestError, self).__init__(message)
         self.stacktrace = stacktrace
 
 
 class NotFoundError(Exception):
     """
-    An exception that will result in a response status of 404
-    due to objects not being found
+    An exception that will result in a response status of 404.
+
+    Raised due to objects not being found.
     """
+
     status = 404
 
     def __init__(self, message, stacktrace=None):
+        """Override init to handle message and stacktrace."""
         super(NotFoundError, self).__init__(message)
         self.stacktrace = stacktrace
 
 
 class CreatedObject(Exception):
     """
-    An exception that is thrown when new object created
-    that returns a status of 201
+    An exception that is thrown when new object created.
+
+    This is not really an error but indicates to the handler
+    that a JsonResponse with status 201 should be returned.
+    The dict content is passed in as 'response'.
     """
+
     status = 201
 
     def __init__(self, response):
+        """Override init to include response dict."""
         super(CreatedObject, self).__init__(response)
         self.response = response

components/tools/OmeroWeb/omeroweb/webgateway/api_marshal.py → components/tools/OmeroWeb/omeroweb/api/api_marshal.py

@@ -17,15 +17,17 @@
 # You should have received a copy of the GNU Affero General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-''' Helper functions for views that handle object trees '''
+"""Helper functions for views that handle object trees."""
 
 
 from omero_marshal import get_encoder
 
 
 def normalize_objects(objects):
     """
-    Takes a list of dicts generated from omero_marshal and
+    Normalize the groups and owners from omero_marshal dicts.
+
+    Take a list of dicts generated from omero_marshal and
     normalizes the groups and owners into separate
     lists. omero:details will only retain group and owner IDs.
     """
@@ -47,12 +49,11 @@ def normalize_objects(objects):
 
 def marshal_objects(objects, extras=None, normalize=False):
     """
-    Marshals a list of OMERO.model objects using omero_marshal
+    Marshal a list of OMERO.model objects using omero_marshal.
 
     @param extras:      A dict of id:dict to add extra data to each object
     @param normalize:   If true, normalize groups & owners into separate lists
     """
-
     marshalled = []
     for o in objects:
         encoder = get_encoder(o.__class__)

components/tools/OmeroWeb/omeroweb/webgateway/api_query.py → components/tools/OmeroWeb/omeroweb/api/api_query.py

@@ -17,7 +17,7 @@
 # You should have received a copy of the GNU Affero General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-''' Helper functions for views that handle object trees '''
+"""Helper functions for views that handle object trees."""
 
 import omero
 

components/tools/OmeroWeb/omeroweb/webgateway/decorators.py → components/tools/OmeroWeb/omeroweb/api/decorators.py

@@ -34,28 +34,25 @@
 
 
 class login_required(omeroweb.decorators.login_required):
-    """
-    webgateway specific extension of the OMERO.web login_required() decorator.
-    """
+    """webgateway specific extension of the login_required() decorator."""
 
     def on_not_logged_in(self, request, url, error=None):
-        """
-        Used for json api methods
-        """
+        """Used for json api methods."""
         return JsonResponse({'message': 'Not logged in'},
                             status=403)
 
 
 class json_response(object):
     """
     Class-based decorator for wrapping Django views methods.
+
     Returns JsonResponse based on dict returned by views methods.
     Also handles exceptions from views methods, returning
     JsonResponse with appropriate status values.
     """
 
     def __init__(self):
-        """Initialises the decorator."""
+        """Initialise the decorator."""
         pass
 
     def handle_success(self, rv):
@@ -74,7 +71,6 @@ def handle_error(self, ex, trace):
         By default, we format exception or message and return this
         as a JsonResponse with an appropriate status code.
         """
-
         # Default status is 500 'server error'
         # But we try to handle all 'expected' errors appropriately
         # TODO: handle omero.ConcurrencyException
@@ -99,9 +95,9 @@ def handle_error(self, ex, trace):
             rsp_json = ex.response
         return JsonResponse(rsp_json, status=status)
 
-    def __call__(ctx, f):
+    def __call__(self, f):
         """
-        Returns the decorator.
+        Return the decorator.
 
         The decorator calls the wrapped function and
         handles success or exception, returning a
@@ -111,8 +107,8 @@ def wrapped(request, *args, **kwargs):
             logger.debug('json_response')
             try:
                 rv = f(request, *args, **kwargs)
-                return ctx.handle_success(rv)
+                return self.handle_success(rv)
             except Exception, ex:
                 trace = traceback.format_exc()
-                return ctx.handle_error(ex, trace)
+                return self.handle_error(ex, trace)
         return update_wrapper(wrapped, f)

components/tools/OmeroWeb/omeroweb/webgateway/urls_api.py → components/tools/OmeroWeb/omeroweb/api/urls.py

@@ -17,10 +17,10 @@
 # You should have received a copy of the GNU Affero General Public License
 # along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-# Handles all 'api' urls without including '/webgateway/' in the url.
+"""Handles all 'api' urls."""
 
 from django.conf.urls import url, patterns
-from omeroweb.webgateway import views
+from omeroweb.api import views
 from omeroweb.webgateway.views import LoginView
 from django.conf import settings
 import re