Skip to content

Commit

Permalink
Ensure all public, stable API methods for Processing have nice docstr…
Browse files Browse the repository at this point in the history
…ings
  • Loading branch information
nyalldawson committed Mar 28, 2019
1 parent 7e80fc8 commit f758d8b
Show file tree
Hide file tree
Showing 2 changed files with 48 additions and 22 deletions.
19 changes: 9 additions & 10 deletions python/plugins/processing/tools/dataobjects.py
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -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]

Expand All @@ -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())
Expand Down Expand Up @@ -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():
Expand All @@ -155,7 +155,6 @@ def load(fileName, name=None, crs=None, style=None, isRaster=False):


def getRasterSublayer(path, param):

layer = QgsRasterLayer(path)

try:
Expand Down
51 changes: 39 additions & 12 deletions python/plugins/processing/tools/general.py
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -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:
Expand Down Expand Up @@ -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)
Expand All @@ -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
Expand All @@ -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()
Expand All @@ -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:
Expand Down

0 comments on commit f758d8b

Please sign in to comment.