[FEATURE][API] Add flexible framework for custom "validity checks"

Adds a new interface QgsAbstractValidityCheck which defines a single "check" which can be performed on a given QgsValidityCheckContext. A new application-wide QgsValidityCheckRegistry registers and manages instances of all known checks, and allows running of all registered checks of a specific type at once. Initially the framework is focused toward print layout validity checks, but the interface has been designed to be generic enough to allow alternative types of validity checks (e.g. project save validity checks, processing model validity checks, etc.). The API is designed to be used both by internal validity checks and also to be extended by custom, organisation-specific validity checks. E.g., for print layout validity checks we could have:
qgis · Jan 2, 2019 · 7ccaa3d · 7ccaa3d
1 parent ac6e674
commit 7ccaa3d
Show file tree

Hide file tree

Showing 25 changed files with 1,397 additions and 0 deletions.
diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
@@ -78,6 +78,7 @@ IF(WITH_APIDOC)
       ${CMAKE_SOURCE_DIR}/src/core/raster
       ${CMAKE_SOURCE_DIR}/src/core/scalebar
       ${CMAKE_SOURCE_DIR}/src/core/symbology
+      ${CMAKE_SOURCE_DIR}/src/core/validity
       ${CMAKE_SOURCE_DIR}/src/gui
       ${CMAKE_SOURCE_DIR}/src/gui/auth
       ${CMAKE_SOURCE_DIR}/src/gui/attributetable

diff --git a/python/CMakeLists.txt b/python/CMakeLists.txt
@@ -116,6 +116,7 @@ INCLUDE_DIRECTORIES(
   ${CMAKE_SOURCE_DIR}/src/core/raster
   ${CMAKE_SOURCE_DIR}/src/core/scalebar
   ${CMAKE_SOURCE_DIR}/src/core/symbology
+  ${CMAKE_SOURCE_DIR}/src/core/validity
   ${CMAKE_SOURCE_DIR}/src/plugins
 
   ${CMAKE_BINARY_DIR}  # qgsconfig.h, qgsversion.h

diff --git a/python/core/auto_generated/qgsapplication.sip.in b/python/core/auto_generated/qgsapplication.sip.in
@@ -668,6 +668,13 @@ Returns the application's image cache, used for caching resampled versions of ra
 Returns the application's network content registry used for fetching temporary files during QGIS session
 
 .. versionadded:: 3.2
+%End
+
+    static QgsValidityCheckRegistry *validityCheckRegistry();
+%Docstring
+Returns the application's validity check registry, used for managing validity checks.
+
+.. versionadded:: 3.6
 %End
 
     static QgsSymbolLayerRegistry *symbolLayerRegistry();

diff --git a/python/core/auto_generated/validity/qgsabstractvaliditycheck.sip.in b/python/core/auto_generated/validity/qgsabstractvaliditycheck.sip.in
@@ -0,0 +1,114 @@
+/************************************************************************
+ * This file has been generated automatically from                      *
+ *                                                                      *
+ * src/core/validity/qgsabstractvaliditycheck.h                         *
+ *                                                                      *
+ * Do not edit manually ! Edit header and run scripts/sipify.pl again   *
+ ************************************************************************/
+
+
+
+class QgsValidityCheckResult
+{
+%Docstring
+Represents an individual result from a validity check run by a QgsAbstractValidityCheck subclass.
+
+Results can either be warnings or critical errors, as dictated by the type member. Critical error
+are errors which are serious enough to prevent an operation from proceeding, while a warning
+result will be communicated to users, but not prevent them from proceeding.
+
+.. versionadded:: 3.6
+%End
+
+%TypeHeaderCode
+#include "qgsabstractvaliditycheck.h"
+%End
+  public:
+
+    enum Type
+    {
+      Warning,
+      Critical,
+    };
+
+    Type type;
+
+    QString title;
+
+    QString detailedDescription;
+
+    QString checkId;
+
+};
+
+
+class QgsAbstractValidityCheck : QObject
+{
+%Docstring
+Abstract base class for individual validity checks.
+
+Validity checks represent objects which can run a test using a :py:class:`QgsValidityCheckContext`, and return
+the results of the check via QgsValidityCheckResult objects.
+
+Checks can be used for many different use cases, e.g. validating a layout's contents before allowing
+an export to occur, or validating the contents of a Processing model (and warning if required plugin based
+providers are not available or if compulsory algorithm parameters have not been populated).
+
+Subclasses must indicate the type of check the represent via the checkType() method. When checks are performed,
+all the registered checks with a matching check type are performed sequentially. The check type also
+dictates the subclass of the QgsValidityCheckContext which is given to the subclass' runCheck method.
+
+Checks must be registered in the application's :py:class:`QgsValidityCheckRegistry`, which is accessible via
+:py:func:`QgsApplication.validityCheckRegistry()`
+
+.. seealso:: :py:class:`QgsValidityCheckRegistry`
+
+.. versionadded:: 3.6
+%End
+
+%TypeHeaderCode
+#include "qgsabstractvaliditycheck.h"
+%End
+  public:
+
+    enum Type
+    {
+      TypeLayoutCheck,
+      TypeUserCheck,
+    };
+
+    virtual QString id() const = 0;
+%Docstring
+Returns the unique ID of the check.
+%End
+
+    virtual int checkType() const = 0;
+%Docstring
+Returns the type of the check.
+%End
+
+    virtual QString name() const = 0;
+%Docstring
+Returns the name of the check.
+%End
+
+    virtual QList< QgsValidityCheckResult > runCheck( const QgsValidityCheckContext *context, QgsFeedback *feedback ) const = 0;
+%Docstring
+Runs the check and returns a list of results. If the check is "passed" and no warnings or errors are generated,
+then an empty list should be returned.
+
+The ``context`` argument gives the wider in which the check is being run.
+%End
+
+};
+
+
+
+
+/************************************************************************
+ * This file has been generated automatically from                      *
+ *                                                                      *
+ * src/core/validity/qgsabstractvaliditycheck.h                         *
+ *                                                                      *
+ * Do not edit manually ! Edit header and run scripts/sipify.pl again   *
+ ************************************************************************/
diff --git a/python/core/auto_generated/validity/qgsvaliditycheckcontext.sip.in b/python/core/auto_generated/validity/qgsvaliditycheckcontext.sip.in
@@ -0,0 +1,61 @@
+/************************************************************************
+ * This file has been generated automatically from                      *
+ *                                                                      *
+ * src/core/validity/qgsvaliditycheckcontext.h                          *
+ *                                                                      *
+ * Do not edit manually ! Edit header and run scripts/sipify.pl again   *
+ ************************************************************************/
+
+
+
+class QgsValidityCheckContext
+{
+%Docstring
+Base class for validity check contexts.
+
+QgsAbstractValidityCheck subclasses are passed a QgsValidityCheckContext subclass which
+encapsulates the context around that particular check type. For instance, a QgsAbstractValidityCheck
+of the QgsAbstractValidityCheck.TypeLayoutCheck type will be passed a QgsLayoutValidityCheckContext
+context, containing a reference to the QgsLayout to be checked.
+
+.. versionadded:: 3.6
+%End
+
+%TypeHeaderCode
+#include "qgsvaliditycheckcontext.h"
+%End
+  public:
+
+};
+
+class QgsLayoutValidityCheckContext : QgsValidityCheckContext
+{
+%Docstring
+Validity check context for print layout validation.
+
+QgsLayoutValidityCheckContext are passed to QgsAbstractValidityCheck subclasses which
+indicate they are of the QgsAbstractValidityCheck.TypeLayoutCheck type.
+
+.. versionadded:: 3.6
+%End
+
+%TypeHeaderCode
+#include "qgsvaliditycheckcontext.h"
+%End
+  public:
+
+    QgsLayoutValidityCheckContext( QgsLayout *layout );
+%Docstring
+Constructor for QgsLayoutValidityCheckContext for the specified ``layout``.
+%End
+
+    QgsLayout *layout;
+
+};
+/************************************************************************
+ * This file has been generated automatically from                      *
+ *                                                                      *
+ * src/core/validity/qgsvaliditycheckcontext.h                          *
+ *                                                                      *
+ * Do not edit manually ! Edit header and run scripts/sipify.pl again   *
+ ************************************************************************/
diff --git a/python/core/auto_generated/validity/qgsvaliditycheckregistry.sip.in b/python/core/auto_generated/validity/qgsvaliditycheckregistry.sip.in
@@ -0,0 +1,77 @@
+/************************************************************************
+ * This file has been generated automatically from                      *
+ *                                                                      *
+ * src/core/validity/qgsvaliditycheckregistry.h                         *
+ *                                                                      *
+ * Do not edit manually ! Edit header and run scripts/sipify.pl again   *
+ ************************************************************************/
+
+
+class QgsValidityCheckRegistry
+{
+%Docstring
+This class keeps a list of QgsAbstractValidityCheck checks which can be used when
+performing validity checks.
+
+QgsValidityCheckRegistry is not usually directly created, but rather accessed through
+:py:func:`QgsApplication.validityCheckRegistry()`
+
+.. versionadded:: 3.6
+%End
+
+%TypeHeaderCode
+#include "qgsvaliditycheckregistry.h"
+%End
+  public:
+
+    QgsValidityCheckRegistry();
+
+    ~QgsValidityCheckRegistry();
+
+
+    QList<QgsAbstractValidityCheck *> checks() const;
+%Docstring
+Returns the list of available checks.
+%End
+
+    QList<QgsAbstractValidityCheck *> checks( int type ) const;
+%Docstring
+Returns the list of all available checks of the matching ``type``.
+%End
+
+    void addCheck( QgsAbstractValidityCheck *check /Transfer/ );
+%Docstring
+Adds a ``check`` to the registry. Ownership of the check
+is transferred to the registry.
+%End
+
+    void removeCheck( QgsAbstractValidityCheck *check );
+%Docstring
+Removes a ``check`` from the registry.
+The check object is automatically deleted.
+%End
+
+    QList< QgsValidityCheckResult > runChecks( int type, const QgsValidityCheckContext *context, QgsFeedback *feedback ) const;
+%Docstring
+Runs all checks of the specified ``type`` and returns a list of results.
+
+If all checks are "passed" and no warnings or errors are generated, then
+an empty list will be returned.
+
+The ``context`` argument gives the wider in which the check is being run.
+
+The ``feedback`` argument is used to give progress reports and to support
+cancelation of long-running checks.
+%End
+
+  private:
+    QgsValidityCheckRegistry( const QgsValidityCheckRegistry &rh );
+};
+
+/************************************************************************
+ * This file has been generated automatically from                      *
+ *                                                                      *
+ * src/core/validity/qgsvaliditycheckregistry.h                         *
+ *                                                                      *
+ * Do not edit manually ! Edit header and run scripts/sipify.pl again   *
+ ************************************************************************/
diff --git a/python/core/core_auto.sip b/python/core/core_auto.sip
@@ -305,6 +305,8 @@
 %Include auto_generated/fieldformatter/qgsvaluemapfieldformatter.sip
 %Include auto_generated/fieldformatter/qgsvaluerelationfieldformatter.sip
 %Include auto_generated/geocms/geonode/qgsgeonodeconnection.sip
+%Include auto_generated/validity/qgsvaliditycheckcontext.sip
+%Include auto_generated/validity/qgsvaliditycheckregistry.sip
 %Include auto_generated/gps/qgsqtlocationconnection.sip
 %Include auto_generated/gps/qgsgpsconnectionregistry.sip
 %Include auto_generated/qgsabstractcontentcache.sip
@@ -452,6 +454,7 @@
 %Include auto_generated/layertree/qgslayertreemodellegendnode.sip
 %Include auto_generated/layertree/qgslayertreenode.sip
 %Include auto_generated/layertree/qgslayertreeregistrybridge.sip
+%Include auto_generated/validity/qgsabstractvaliditycheck.sip
 %Include auto_generated/qgsuserprofilemanager.sip
 %Include auto_generated/symbology/qgsarrowsymbollayer.sip
 %Include auto_generated/qgsuserprofile.sip