Ensure all public, stable API methods for Processing have nice docstrings

nyalldawson · nyalldawson · commit 3e65d8ddb1ea · 2019-03-28T13:29:42.000+10:00
(cherry picked from commit f758d8b)
diff --git a/python/plugins/processing/tools/dataobjects.py b/python/plugins/processing/tools/dataobjects.py
@@ -28,16 +28,12 @@
 import os
 import re
 
-from qgis.core import (QgsVectorFileWriter,
-                       QgsMapLayer,
-                       QgsDataProvider,
+from qgis.core import (QgsDataProvider,
                        QgsRasterLayer,
                        QgsWkbTypes,
                        QgsVectorLayer,
                        QgsProject,
-                       QgsCoordinateReferenceSystem,
                        QgsSettings,
-                       QgsProcessingUtils,
                        QgsProcessingContext,
                        QgsFeatureRequest,
                        QgsExpressionContext,
@@ -48,9 +44,6 @@
 from qgis.utils import iface
 
 from processing.core.ProcessingConfig import ProcessingConfig
-from processing.algs.gdal.GdalUtils import GdalUtils
-from processing.tools.system import (getTempFilename,
-                                     removeInvalidChars)
 
 ALL_TYPES = [-1]
 
@@ -66,6 +59,12 @@
 def createContext(feedback=None):
     """
     Creates a default processing context
+
+    :param feedback: Optional existing QgsProcessingFeedback object, or None to use a default feedback object
+    :type feedback: Optional[QgsProcessingFeedback]
+
+    :returns: New QgsProcessingContext object
+    :rtype: QgsProcessingContext
     """
     context = QgsProcessingContext()
     context.setProject(QgsProject.instance())
@@ -132,7 +131,8 @@ def load(fileName, name=None, crs=None, style=None, isRaster=False):
             if prjSetting:
                 settings.setValue('/Projections/defaultBehavior', prjSetting)
             raise RuntimeError(QCoreApplication.translate('dataobject',
-                                                          'Could not load layer: {0}\nCheck the processing framework log to look for errors.').format(fileName))
+                                                          'Could not load layer: {0}\nCheck the processing framework log to look for errors.').format(
+                fileName))
     else:
         qgslayer = QgsVectorLayer(fileName, name, 'ogr')
         if qgslayer.isValid():
@@ -155,7 +155,6 @@ def load(fileName, name=None, crs=None, style=None, isRaster=False):
 
 
 def getRasterSublayer(path, param):
-
     layer = QgsRasterLayer(path)
 
     try:
diff --git a/python/plugins/processing/tools/general.py b/python/plugins/processing/tools/general.py
@@ -24,10 +24,6 @@
 # This will get replaced with a git SHA1 when you do a git archive
 
 __revision__ = '$Format:%H$'
-
-import os
-import configparser
-
 from qgis.core import (QgsApplication,
                        QgsProcessingAlgorithm,
                        QgsProcessingParameterEnum,
@@ -43,8 +39,13 @@
 
 
 def algorithmHelp(id):
-    """Prints algorithm parameters with their types. Also
-    provides information about options if any.
+    """
+    Prints algorithm parameters with their types. Also
+    provides information about parameters and outputs,
+    and their acceptable values.
+
+    :param id: An algorithm's ID
+    :type id: str
     """
     alg = QgsApplication.processingRegistry().algorithmById(id)
     if alg is not None:
@@ -100,6 +101,9 @@ def run(algOrName, parameters, onFinish=None, feedback=None, context=None, is_ch
     :param context: Processing context object
     :param is_child_algorithm: Set to True if this algorithm is being run as part of a larger algorithm,
     i.e. it is a sub-part of an algorithm which calls other Processing algorithms.
+
+    :returns algorithm results as a dictionary, or None if execution failed
+    :rtype: Union[dict, None]
     """
     if onFinish or not is_child_algorithm:
         return Processing.runAlgorithm(algOrName, parameters, onFinish, feedback, context)
@@ -114,8 +118,17 @@ def post_process(_alg, _context, _feedback):
 
 
 def runAndLoadResults(algOrName, parameters, feedback=None, context=None):
-    """Executes given algorithm and load its results into QGIS project
+    """
+    Executes given algorithm and load its results into the current QGIS project
     when possible.
+
+    :param algOrName: Either an instance of an algorithm, or an algorithm's ID
+    :param parameters: Algorithm parameters dictionary
+    :param feedback: Processing feedback object
+    :param context: Processing context object
+
+    :returns algorithm results as a dictionary, or None if execution failed
+    :rtype: Union[dict, None]
     """
     if isinstance(algOrName, QgsProcessingAlgorithm):
         alg = algOrName
@@ -127,21 +140,30 @@ def runAndLoadResults(algOrName, parameters, feedback=None, context=None):
         if not param.name() in parameters:
             continue
 
-        if isinstance(param, (QgsProcessingParameterFeatureSink, QgsProcessingParameterVectorDestination, QgsProcessingParameterRasterDestination)):
+        if isinstance(param, (QgsProcessingParameterFeatureSink, QgsProcessingParameterVectorDestination,
+                              QgsProcessingParameterRasterDestination)):
             p = parameters[param.name()]
             if not isinstance(p, QgsProcessingOutputLayerDefinition):
                 parameters[param.name()] = QgsProcessingOutputLayerDefinition(p, QgsProject.instance())
             else:
                 p.destinationProject = QgsProject.instance()
                 parameters[param.name()] = p
 
-    return Processing.runAlgorithm(alg, parameters=parameters, onFinish=handleAlgorithmResults, feedback=feedback, context=context)
+    return Processing.runAlgorithm(alg, parameters=parameters, onFinish=handleAlgorithmResults, feedback=feedback,
+                                   context=context)
 
 
 def createAlgorithmDialog(algOrName, parameters={}):
-    """Creates and returns an algorithm dialog for the specified algorithm, prepopulated
+    """
+    Creates and returns an algorithm dialog for the specified algorithm, prepopulated
     with a given set of parameters. It is the caller's responsibility to execute
     and delete this dialog.
+
+    :param algOrName: Either an instance of an algorithm, or an algorithm's ID
+    :param parameters: Initial algorithm parameters dictionary
+
+    :returns algorithm results as a dictionary, or None if execution failed
+    :rtype: Union[dict, None]
     """
     if isinstance(algOrName, QgsProcessingAlgorithm):
         alg = algOrName.create()
@@ -162,10 +184,15 @@ def createAlgorithmDialog(algOrName, parameters={}):
 
 
 def execAlgorithmDialog(algOrName, parameters={}):
-    """Executes an algorithm dialog for the specified algorithm, prepopulated
+    """
+    Executes an algorithm dialog for the specified algorithm, prepopulated
     with a given set of parameters.
 
-    Returns the algorithm's results.
+    :param algOrName: Either an instance of an algorithm, or an algorithm's ID
+    :param parameters: Initial algorithm parameters dictionary
+
+    :returns algorithm results as a dictionary, or None if execution failed
+    :rtype: Union[dict, None]
     """
     dlg = createAlgorithmDialog(algOrName, parameters)
     if dlg is None:
