Merge pull request #4401 from nyalldawson/processing_params

c++ framework for parameters and running algorithms

Author: nyalldawson

python/core/core.sip

@@ -284,6 +284,7 @@
 %Include processing/qgsprocessingalgorithm.sip
 %Include processing/qgsprocessingcontext.sip
 %Include processing/qgsprocessingfeedback.sip
+%Include processing/qgsprocessingparameters.sip
 %Include processing/qgsprocessingprovider.sip
 %Include processing/qgsprocessingregistry.sip
 %Include processing/qgsprocessingutils.sip

python/core/processing/qgsprocessingalgorithm.sip

@@ -112,6 +112,171 @@ class QgsProcessingAlgorithm
 
     void setProvider( QgsProcessingProvider *provider );
 
+    QgsProcessingParameterDefinitions parameterDefinitions() const;
+%Docstring
+ Returns an ordered list of parameter definitions utilized by the algorithm.
+.. seealso:: addParameter()
+.. seealso:: parameterDefinition()
+ :rtype: QgsProcessingParameterDefinitions
+%End
+
+    const QgsProcessingParameterDefinition *parameterDefinition( const QString &name ) const;
+%Docstring
+ Returns a matching parameter by ``name``. Matching is done in a case-insensitive
+ manner.
+.. seealso:: parameterDefinitions()
+ :rtype: QgsProcessingParameterDefinition
+%End
+
+    virtual QVariantMap run( const QVariantMap &parameters,
+                             QgsProcessingContext &context, QgsProcessingFeedback *feedback ) const;
+%Docstring
+ Runs the algorithm using the specified ``parameters``. Algorithms should implement
+ their custom processing logic here.
+
+ The ``context`` argument specifies the context in which the algorithm is being run.
+
+ Algorithm progress should be reported using the supplied ``feedback`` object. Additionally,
+ well-behaved algorithms should periodically check ``feedback`` to determine whether the
+ algorithm should be canceled and exited early.
+
+ :return: A map of algorithm outputs. These may be output layer references, or calculated
+ values such as statistical calculations.
+ :rtype: QVariantMap
+%End
+
+  protected:
+
+    bool addParameter( QgsProcessingParameterDefinition *parameterDefinition /Transfer/ );
+%Docstring
+ Adds a parameter ``definition`` to the algorithm. Ownership of the definition is transferred to the algorithm.
+ Returns true if parameter could be successfully added, or false if the parameter could not be added (e.g.
+ as a result of a duplicate name).
+ :rtype: bool
+%End
+
+    QString parameterAsString( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;
+%Docstring
+ Evaluates the parameter with matching ``name`` to a static string value.
+ :rtype: str
+%End
+
+    QString parameterAsExpression( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;
+%Docstring
+ Evaluates the parameter with matching ``name`` to an expression.
+ :rtype: str
+%End
+
+    double parameterAsDouble( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;
+%Docstring
+ Evaluates the parameter with matching ``name`` to a static double value.
+ :rtype: float
+%End
+
+    int parameterAsInt( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;
+%Docstring
+ Evaluates the parameter with matching ``name`` to a static integer value.
+ :rtype: int
+%End
+
+    int parameterAsEnum( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;
+%Docstring
+ Evaluates the parameter with matching ``name`` to a enum value.
+ :rtype: int
+%End
+
+    QList<int> parameterAsEnums( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;
+%Docstring
+ Evaluates the parameter with matching ``name`` to list of enum values.
+ :rtype: list of int
+%End
+
+    bool parameterAsBool( const QVariantMap &parameters, const QString &name, const QgsProcessingContext &context ) const;
+%Docstring
+ Evaluates the parameter with matching ``name`` to a static boolean value.
+ :rtype: bool
+%End
+
+    QgsMapLayer *parameterAsLayer( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
+%Docstring
+ Evaluates the parameter with matching ``name`` to a map layer.
+
+ Layers will either be taken from ``context``'s active project, or loaded from external
+ sources and stored temporarily in the ``context``. In either case, callers do not
+ need to handle deletion of the returned layer.
+ :rtype: QgsMapLayer
+%End
+
+    QgsRasterLayer *parameterAsRasterLayer( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
+%Docstring
+ Evaluates the parameter with matching ``name`` to a raster layer.
+
+ Layers will either be taken from ``context``'s active project, or loaded from external
+ sources and stored temporarily in the ``context``. In either case, callers do not
+ need to handle deletion of the returned layer.
+ :rtype: QgsRasterLayer
+%End
+
+    QgsVectorLayer *parameterAsVectorLayer( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
+%Docstring
+ Evaluates the parameter with matching ``name`` to a vector layer.
+
+ Layers will either be taken from ``context``'s active project, or loaded from external
+ sources and stored temporarily in the ``context``. In either case, callers do not
+ need to handle deletion of the returned layer.
+ :rtype: QgsVectorLayer
+%End
+
+    QgsCoordinateReferenceSystem parameterAsCrs( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
+%Docstring
+ Evaluates the parameter with matching ``name`` to a coordinate reference system.
+ :rtype: QgsCoordinateReferenceSystem
+%End
+
+    QgsRectangle parameterAsExtent( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
+%Docstring
+ Evaluates the parameter with matching ``name`` to a rectangular extent.
+ :rtype: QgsRectangle
+%End
+
+    QgsPoint parameterAsPoint( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
+%Docstring
+ Evaluates the parameter with matching ``name`` to a point.
+ :rtype: QgsPoint
+%End
+
+    QString parameterAsFile( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
+%Docstring
+ Evaluates the parameter with matching ``name`` to a file/folder name.
+ :rtype: str
+%End
+
+    QVariantList parameterAsMatrix( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
+%Docstring
+ Evaluates the parameter with matching ``name`` to a matrix/table of values.
+ Tables are collapsed to a 1 dimensional list.
+ :rtype: QVariantList
+%End
+
+    QList< QgsMapLayer *> parameterAsLayerList( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
+%Docstring
+ Evaluates the parameter with matching ``name`` to a list of map layers.
+ :rtype: list of QgsMapLayer
+%End
+
+    QList<double> parameterAsRange( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
+%Docstring
+ Evaluates the parameter with matching ``name`` to a range of values.
+ :rtype: list of float
+%End
+
+    QStringList parameterAsFields( const QVariantMap &parameters, const QString &name, QgsProcessingContext &context ) const;
+%Docstring
+ Evaluates the parameter with matching ``name`` to a list of fields.
+ :rtype: list of str
+%End
+
+
   private:
     QgsProcessingAlgorithm( const QgsProcessingAlgorithm &other );
 };

python/core/processing/qgsprocessingcontext.sip

@@ -64,12 +64,13 @@ class QgsProcessingContext
 .. seealso:: project()
 %End
 
-    QgsExpressionContext expressionContext() const;
+    QgsExpressionContext &expressionContext();
 %Docstring
  Returns the expression context.
  :rtype: QgsExpressionContext
 %End
 
+
     void setExpressionContext( const QgsExpressionContext &context );
 %Docstring
  Sets the expression ``context``.
@@ -82,6 +83,7 @@ class QgsProcessingContext
  :rtype: QgsMapLayerStore
 %End
 
+
     QgsFeatureRequest::InvalidGeometryCheck invalidGeometryCheck() const;
 %Docstring
  Returns the behavior used for checking invalid geometries in input layers.