Transfers: Make sure we have sphinx-friendly function docs. rucio#570

lib/rucio/client/rseclient.py

@@ -277,6 +277,7 @@ def lfns2pfns(self, rse, lfns, protocol_domain='ALL', operation=None, scheme=Non
         The PFNs are generated for the RSE *regardless* of whether a replica exists for the LFN.
 
         :param rse: the RSE name
+        :param lfns: A list of LFN strings to translate to PFNs.
         :param protocol_domain: The scope of the protocol. Supported are 'LAN', 'WAN', and 'ALL' (as default).
         :param operation: The name of the requested operation (read, write, or delete).
                           If None, all operations are queried.

lib/rucio/common/config.py

@@ -33,12 +33,22 @@ def config_get(section, option):
 
 
 def config_has_section(section):
-    """Indicates whether the named section is present in the configuration. The DEFAULT section is not acknowledged.)"""
+    """
+    Indicates whether the named section is present in the configuration. The DEFAULT section is not acknowledged.)
+
+    :param section: Name of section in the Rucio config to verify.
+    :returns: True if the section exists in the configuration; False otherwise
+    """
     return __CONFIG.has_section(section)
 
 
 def config_add_section(section):
-    """Add a new section to the configuration object.  Throws DuplicateSectionError if it already exists."""
+    """
+    Add a new section to the configuration object.  Throws DuplicateSectionError if it already exists.
+
+    :param section: Name of section in the Rucio config to add.
+    :returns: None
+    """
     return __CONFIG.add_section(section)
 
 
@@ -68,19 +78,27 @@ def config_get_items(section):
 
 
 def config_remove_option(section, option):
-    """Remove the specified option from a given section.
+    """
+    Remove the specified option from a given section.
 
-       If the option existed in the configuration, return True.
+    :param section: Name of section in the Rucio config.
+    :param option: Name of option to remove from Rucio configuration.
+    :returns: True if the option existed in the configuration, False otherwise.
 
-       If the section does not exist, throws NoSectionError.
+    :raises NoSectionError: If the section does not exist.
     """
     return __CONFIG.remove_option(section, option)
 
 
 def config_set(section, option, value):
-    """Set a configuration option in a given section.
+    """
+    Set a configuration option in a given section.
+
+    :param section: Name of section in the Rucio config.
+    :param option: Name of option to set in the Rucio configuration.
+    :param value: New value for the option.
 
-       If the section does not exist, throws a NoSectionError.
+    :raises NoSectionError: If the section does not exist.
     """
     return __CONFIG.set(section, option, value)
 

lib/rucio/rse/protocols/protocol.py

@@ -46,15 +46,22 @@ def __init__(self, rse=None, rse_attributes=None, protocol_attributes=None):
         """
         Initialize a translator object from the RSE, its attributes, and the protocol-specific
         attributes.
+
+        :param rse: Name of RSE for this translation.
+        :param rse_attributes: A dictionary of RSE-specific attributes for use in the translation.
+        :param protocol_attributes: A dictionary of RSE/protocol-specific attributes.
         """
         self.rse = rse
         self.rse_attributes = rse_attributes if rse_attributes else {}
         self.protocol_attributes = protocol_attributes if protocol_attributes else {}
 
     @classmethod
     def supports(cls, name):
-        """Returns True if `name` is an algorithm supported by the translator
-           class, False otherwise.
+        """
+        Check to see if a specific algorithm is supported.
+
+        :param name: Name of the deterministic algorithm.
+        :returns: True if `name` is an algorithm supported by the translator class, False otherwise.
         """
         return name in cls._LFN2PFN_ALGORITHMS
 
@@ -71,6 +78,9 @@ def register(lfn2pfn_callable, name=None):
          - protocol_attributes: Attributes of the RSE's protocol
         The return value should be the last part of the PFN - it will be appended to the
         rest of the URL.
+
+        :param lfn2pfn_callable: Callable function to use for generating paths.
+        :param name: Algorithm name used for registration.  If None, then `lfn2pfn_callable.__name__` is used.
         """
         if name is None:
             name = lfn2pfn_callable.__name__
@@ -80,6 +90,16 @@ def register(lfn2pfn_callable, name=None):
     def __hash(scope, name, rse, rse_attrs, protocol_attrs):
         """
         Given a LFN, turn it into a sub-directory structure using a hash function.
+
+        This takes the MD5 of the LFN and uses the first four characters as a subdirectory
+        name.
+
+        :param scope: Scope of the LFN.
+        :param name: File name of the LFN.
+        :param rse: RSE for PFN (ignored)
+        :param rse_attrs: RSE attributes for PFN (ignored)
+        :param protocol_attrs: RSE protocol attributes for PFN (ignored)
+        :returns: Path for use in the PFN generation.
         """
         del rse
         del rse_attrs
@@ -96,6 +116,12 @@ def __identity(scope, name, rse, rse_attrs, protocol_attrs):
 
             scope:path -> scope/path
 
+        :param scope: Scope of the LFN.
+        :param name: File name of the LFN.
+        :param rse: RSE for PFN (ignored)
+        :param rse_attrs: RSE attributes for PFN (ignored)
+        :param protocol_attrs: RSE protocol attributes for PFN (ignored)
+        :returns: Path for use in the PFN generation.
         """
         del rse
         del rse_attrs
@@ -220,8 +246,8 @@ def _get_path(self, scope, name):
             Suitable for sites implementing the RUCIO naming convention.
             This implementation is only invoked if the RSE is deterministic.
 
-            :param lfn: filename
             :param scope: scope
+            :param name: filename
 
             :returns: RSE specific URI of the physical file
         """

lib/rucio/web/rest/rse.py

@@ -338,7 +338,18 @@ class LFNS2PFNS(RucioController):
     """ Translate one-or-more LFNs to corresponding PFNs. """
 
     def GET(self, rse, scheme=None):
-        """ Return PFNs for a set of LFNs.
+        """
+        Return PFNs for a set of LFNs.  Formatted as a JSON object where the key is a LFN and the
+        value is the corresponding PFN.
+
+        - One or more LFN should be passed as the LFN arguments.
+        - A URL scheme (e.g., http / gsiftp / srm) can be passed to help with protocol selection using the
+          `scheme` query argument.
+        - The `domain` query argument is used to select protocol for wan or lan use cases.
+        - The `operation` query argument is used to select the protocol for read-vs-writes.
+
+        The `scheme`, `domain`, and `operation` options help with the selection of the protocol, in case
+        if that affects the possible PFN generation.
 
         HTTP Success:
             200 OK