docs (Tornado): provide more docs, comments

Author: TaykYoku

src/DIRAC/Core/Tornado/Server/TornadoREST.py

@@ -3,16 +3,10 @@
 It directly inherits from :py:class:`tornado.web.RequestHandler`
 """
 
-from __future__ import absolute_import
-from __future__ import division
-from __future__ import print_function
-
-__RCSID__ = "$Id$"
-
 import inspect
 from urllib.parse import unquote
 
-from DIRAC import gLogger, S_OK
+from DIRAC import gLogger
 from DIRAC.ConfigurationSystem.Client import PathFinder
 from DIRAC.Core.Tornado.Server.private.BaseRequestHandler import BaseRequestHandler
 
@@ -21,19 +15,19 @@
 
 class TornadoREST(BaseRequestHandler):  # pylint: disable=abstract-method
     """Base class for all the endpoints handlers.
-    It directly inherits from :py:class:`DIRAC.Core.Tornado.Server.BaseRequestHandler.BaseRequestHandler`
-
-    Each HTTP request is served by a new instance of this class.
 
     ### Example
-    In order to create a handler for your service, it has to follow a certain skeleton:
+    In order to create a handler for your service, it has to follow a certain skeleton.
 
     .. code-block:: python
 
         from DIRAC.Core.Tornado.Server.TornadoREST import TornadoREST
         class yourEndpointHandler(TornadoREST):
 
-            SYSTEM = "Configuration"
+            # To use only the HTTP POST method
+            SUPPORTED_METHODS = ["POST"]
+
+            # Base URL
             LOCATION = "/registry"
 
             @classmethod
@@ -61,41 +55,39 @@ def web_users(self, count: int = 0):
                 '''
                 return Registry.getAllUsers()[:count]
 
+    This class can read the method annotation to understand what type of argument expects to get the method,
+    see :py:meth:`_getMethodArgs`.
+
     Note that because we inherit from :py:class:`tornado.web.RequestHandler`
     and we are running using executors, the methods you export cannot write
-    back directly to the client. Please see inline comments for more details.
+    back directly to the client. Please see inline comments in
+    :py:class:`BaseRequestHandler <DIRAC.Core.Tornado.Server.private.BaseRequestHandler.BaseRequestHandler>` for more details.
 
-    In order to pass information around and keep some states, we use instance attributes.
-    These are initialized in the :py:meth:`.initialize` method.
-
-    The handler define the ``post`` and ``get`` verbs. Please refer to :py:meth:`.post` for the details.
     """
 
+    # By default we enable all authorization grants, see DIRAC.Core.Tornado.Server.private.BaseRequestHandler for details
     USE_AUTHZ_GRANTS = ["SSL", "JWT", "VISITOR"]
     METHOD_PREFIX = "web_"
     LOCATION = "/"
 
     @classmethod
-    def _getServiceName(cls, request):
-        """Define endpoint full name
-
-        :param object request: tornado Request
+    def _getComponentInfoDict(cls, fullComponentName: str, fullURL: str) -> dict:
+        """Fills the dictionary with information about the current component,
 
-        :return: str
+        :param fullComponentName: full component name, see :py:meth:`_getFullComponentName`
+        :param fullURL: incoming request path
         """
-        if not cls.SYSTEM:
-            raise Exception("System name must be defined.")
-        return "/".join([cls.SYSTEM, cls.__name__])
+        return {}
 
     @classmethod
-    def _getServiceAuthSection(cls, endpointName):
+    def _getCSAuthorizarionSection(cls, apiName):
         """Search endpoint auth section.
 
-        :param str endpointName: endpoint name
+        :param str apiName: API name, see :py:meth:`_getFullComponentName`
 
         :return: str
         """
-        return "%s/Authorization" % PathFinder.getAPISection(endpointName)
+        return "%s/Authorization" % PathFinder.getAPISection(apiName)
 
     def _getMethodName(self):
         """Parse method name. By default we read the first section in the path
@@ -104,16 +96,19 @@ def _getMethodName(self):
 
         :return: str
         """
+        # Read target method name from request
         method = self.request.path.replace(self.LOCATION, "", 1).strip("/").split("/")[0]
+
+        # If handler has target method use it
         if method and hasattr(self, "".join([self.METHOD_PREFIX, method])):
             return method
-        elif hasattr(self, "%sindex" % self.METHOD_PREFIX):
-            gLogger.warn("%s method not implemented. Use the index method to handle this." % method)
+
+        # Otherwise, the request can be handled by the `<prefix>index` method
+        if hasattr(self, "%sindex" % self.METHOD_PREFIX):
+            self.log.warn(f"{method} method not implemented. Use the index method to handle this.")
             return "index"
-        else:
-            raise NotImplementedError(
-                "%s method not implemented. You can use the index method to handle this." % method
-            )
+
+        raise NotImplementedError(f"{method} method not implemented. You can use the index method to handle this.")
 
     def _getMethodArgs(self, args):
         """Search method arguments.
@@ -183,22 +178,3 @@ def _getMethodArgs(self, args):
                 keywordArguments[name] = value
 
         return (positionalArguments, keywordArguments)
-
-    auth_echo = ["all"]
-
-    @staticmethod
-    def web_echo(data):
-        """
-        This method used for testing the performance of a service
-        """
-        return S_OK(data)
-
-    auth_whoami = ["authenticated"]
-
-    def web_whoami(self):
-        """A simple whoami, returns all credential dictionary, except certificate chain object."""
-        credDict = self.srv_getRemoteCredentials()
-        if "x509Chain" in credDict:
-            # Not serializable
-            del credDict["x509Chain"]
-        return S_OK(credDict)

src/DIRAC/Core/Tornado/Server/TornadoService.py

@@ -27,64 +27,59 @@
 class TornadoService(BaseRequestHandler):  # pylint: disable=abstract-method
     """
     Base class for all the sevices handlers.
-    It directly inherits from :py:class:`DIRAC.Core.Tornado.Server.BaseRequestHandler.BaseRequestHandler`
 
-    Each HTTP request is served by a new instance of this class.
+    For compatibility with the existing :py:class:`DIRAC.Core.DISET.TransferClient.TransferClient`,
+    the handler can define a method ``export_streamToClient``. This is the method that will be called
+    whenever ``TransferClient.receiveFile`` is called. It is the equivalent of the DISET ``transfer_toClient``.
+    Note that this is here only for compatibility, and we discourage using it for new purposes, as it is
+    bound to disappear.
 
-    In order to create a handler for your service, it has to
-    follow a certain skeleton::
+    In order to create a handler for your service, it has to follow a certain skeleton.
 
-      from DIRAC.Core.Tornado.Server.TornadoService import TornadoService
-      class yourServiceHandler(TornadoService):
+    .. code-block:: python
 
-        # Called only once when the first
-        # request for this handler arrives
-        # Useful for initializing DB or so.
-        # You don't need to use super or to call any parents method, it's managed by the server
-        @classmethod
-        def initializeHandler(cls, infosDict):
-          '''Called only once when the first
-             request for this handler arrives
-             Useful for initializing DB or so.
-             You don't need to use super or to call any parents method, it's managed by the server
-          '''
-          pass
 
+        from DIRAC.Core.Tornado.Server.TornadoService import TornadoService
+        class yourServiceHandler(TornadoService):
 
-        def initializeRequest(self):
-          '''
-             Called at the beginning of each request
-          '''
-          pass
+            @classmethod
+            def initializeHandler(cls, infosDict):
+                '''Called only once when the first request for this handler arrives.
+                Useful for initializing DB or so.
+                You don't need to use super or to call any parents method, it's managed by the server
+                '''
+                pass
 
-        # Specify the default permission for the method
-        # See :py:class:`DIRAC.Core.DISET.AuthManager.AuthManager`
-        auth_someMethod = ['authenticated']
+            def initializeRequest(self):
+                '''Called at the beginning of each request
+                '''
+                pass
 
+            # Specify the default permission for the method
+            # See :py:class:`DIRAC.Core.DISET.AuthManager.AuthManager`
+            auth_someMethod = ['authenticated']
 
-        def export_someMethod(self):
-          '''The method you want to export.
-           It must start with ``export_``
-           and it must return an S_OK/S_ERROR structure
-          '''
-          return S_ERROR()
+            def export_someMethod(self):
+                '''The method you want to export. It must start with ``export_``
+                and it must return an S_OK/S_ERROR structure
+                '''
+                return S_ERROR()
 
+            def export_streamToClient(self, myDataToSend, token):
+                ''' Automatically called when ``Transfer.receiveFile`` is called.
+                Contrary to the other ``export_`` methods, it does not need to return a DIRAC structure.
+                '''
 
-        def export_streamToClient(self, myDataToSend, token):
-          ''' Automatically called when ``Transfer.receiveFile`` is called.
-              Contrary to the other ``export_`` methods, it does not need
-              to return a DIRAC structure.
-          '''
+                # Do whatever with the token
 
-          # Do whatever with the token
-
-          with open(myFileToSend, 'r') as fd:
-            return fd.read()
+                with open(myFileToSend, 'r') as fd:
+                    return fd.read()
 
 
     Note that because we inherit from :py:class:`tornado.web.RequestHandler`
     and we are running using executors, the methods you export cannot write
-    back directly to the client. Please see inline comments for more details.
+    back directly to the client. Please see inline comments in
+    :py:class:`BaseRequestHandler <DIRAC.Core.Tornado.Server.private.BaseRequestHandler.BaseRequestHandler>` for more details.
 
     In order to pass information around and keep some states, we use instance attributes.
     These are initialized in the :py:meth:`.initialize` method.
@@ -132,41 +127,34 @@ def export_streamToClient(self, myDataToSend, token):
 
     """
 
-    # To access DIRAC services, RPC requests are used only through the HTTP POST method
-    SUPPORTED_METHODS = ["POST"]
-
     @classmethod
-    def _getServiceName(cls, request):
-        """Search service name in request.
-
-        :param object request: tornado Request
-
-        :return: str
-        """
+    def _initializeHandler(cls):
+        """Pre-initialization"""
         # Expected path: ``/<System>/<Component>``
-        return request.path[1:]
+        cls._serviceName = cls._fullComponentName
 
     @classmethod
-    def _getServiceInfo(cls, serviceName, request):
+    def _getComponentInfoDict(cls, serviceName, fullURL):
         """Fill service information.
 
-        :param str serviceName: service name
-        :param object request: tornado Request
-
+        :param str serviceName: service name, see :py:meth:`_getFullComponentName`
+        :param str fullURL: incoming request path
         :return: dict
         """
-        return {
+        path = PathFinder.getServiceSection(serviceName)
+        cls._serviceInfoDict = {
             "serviceName": serviceName,
-            "serviceSectionPath": PathFinder.getServiceSection(serviceName),
-            "csPaths": [PathFinder.getServiceSection(serviceName)],
-            "URL": request.full_url(),
+            "serviceSectionPath": path,
+            "csPaths": [path],
+            "URL": fullURL,
         }
+        return cls._serviceInfoDict
 
     @classmethod
-    def _getServiceAuthSection(cls, serviceName):
+    def _getCSAuthorizarionSection(cls, serviceName):
         """Search service auth section.
 
-        :param str serviceName: service name
+        :param str serviceName: service name, see :py:meth:`_getFullComponentName`
 
         :return: str
         """