[api] Add framework for setting field comments/aliases via

QgsAbstractDatabaseProviderConnection When implemented by providers, will provide a method for permanently setting field aliases/comments within a database Here we have no choice but to create a new Capability2 enum, as the original Capability has now consumed the entire range of values for data types permitted by QFlag
qgis · Apr 17, 2023 · 9aac2b8 · 9aac2b8
1 parent 0cd25fb
commit 9aac2b8
Show file tree

Hide file tree

Showing 6 changed files with 154 additions and 4 deletions.
diff --git a/python/core/auto_additions/qgis.py b/python/core/auto_additions/qgis.py
@@ -3450,3 +3450,11 @@
 Qgis.PostgresRelKind.__doc__ = 'Postgres database relkind options.\n\n.. versionadded:: 3.32\n\n' + '* ``NotSet``: ' + Qgis.PostgresRelKind.NotSet.__doc__ + '\n' + '* ``Unknown``: ' + Qgis.PostgresRelKind.Unknown.__doc__ + '\n' + '* ``OrdinaryTable``: ' + Qgis.PostgresRelKind.OrdinaryTable.__doc__ + '\n' + '* ``Index``: ' + Qgis.PostgresRelKind.Index.__doc__ + '\n' + '* ``Sequence``: ' + Qgis.PostgresRelKind.Sequence.__doc__ + '\n' + '* ``View``: ' + Qgis.PostgresRelKind.View.__doc__ + '\n' + '* ``MaterializedView``: ' + Qgis.PostgresRelKind.MaterializedView.__doc__ + '\n' + '* ``CompositeType``: ' + Qgis.PostgresRelKind.CompositeType.__doc__ + '\n' + '* ``ToastTable``: ' + Qgis.PostgresRelKind.ToastTable.__doc__ + '\n' + '* ``ForeignTable``: ' + Qgis.PostgresRelKind.ForeignTable.__doc__ + '\n' + '* ``PartitionedTable``: ' + Qgis.PostgresRelKind.PartitionedTable.__doc__
 # --
 Qgis.PostgresRelKind.baseClass = Qgis
+# monkey patching scoped based enum
+Qgis.DatabaseProviderConnectionCapability2.SetFieldComment.__doc__ = "Can set comments for fields via setFieldComment()"
+Qgis.DatabaseProviderConnectionCapability2.SetFieldAlias.__doc__ = "Can set aliases for fields via setFieldAlias()"
+Qgis.DatabaseProviderConnectionCapability2.__doc__ = 'The Capability enum represents the extended operations supported by the connection.\n\n.. versionadded:: 3.32\n\n' + '* ``SetFieldComment``: ' + Qgis.DatabaseProviderConnectionCapability2.SetFieldComment.__doc__ + '\n' + '* ``SetFieldAlias``: ' + Qgis.DatabaseProviderConnectionCapability2.SetFieldAlias.__doc__
+# --
+Qgis.DatabaseProviderConnectionCapability2.baseClass = Qgis
+Qgis.DatabaseProviderConnectionCapabilities2.baseClass = Qgis
+DatabaseProviderConnectionCapabilities2 = Qgis  # dirty hack since SIP seems to introduce the flags in module
diff --git a/python/core/auto_generated/providers/qgsabstractdatabaseproviderconnection.sip.in b/python/core/auto_generated/providers/qgsabstractdatabaseproviderconnection.sip.in
@@ -398,7 +398,18 @@ The connection is not automatically stored in the settings.
 
     Capabilities capabilities() const;
 %Docstring
-Returns connection capabilities
+Returns connection capabilities.
+
+.. seealso:: :py:func:`capabilities2`
+%End
+
+    Qgis::DatabaseProviderConnectionCapabilities2 capabilities2() const;
+%Docstring
+Returns extended connection capabilities.
+
+.. seealso:: :py:func:`capabilities`
+
+.. versionadded:: 3.32
 %End
 
     virtual GeometryColumnCapabilities geometryColumnCapabilities();
@@ -793,6 +804,34 @@ Adds a new field ``domain`` to the database.
 :raises QgsProviderConnectionException: if any errors are encountered.
 
 .. versionadded:: 3.26
+%End
+
+    virtual void setFieldAlias( const QString &fieldName, const QString &schema, const QString &tableName, const QString &alias ) const throw( QgsProviderConnectionException );
+%Docstring
+Sets the ``alias`` for the existing field with the specified name.
+
+:param fieldName: name of the field to be modified
+:param schema: name of the schema (schema is ignored if not supported by the backend).
+:param tableName: name of the table
+:param alias: alias to set for the field. Set to an empty string to remove a previously set alias.
+
+:raises QgsProviderConnectionException: if any errors are encountered.
+
+.. versionadded:: 3.32
+%End
+
+    virtual void setFieldComment( const QString &fieldName, const QString &schema, const QString &tableName, const QString &comment ) const throw( QgsProviderConnectionException );
+%Docstring
+Sets the ``comment`` for the existing field with the specified name.
+
+:param fieldName: name of the field to be modified
+:param schema: name of the schema (schema is ignored if not supported by the backend).
+:param tableName: name of the table
+:param comment: comment to set for the field. Set to an empty string to remove a previously set comment.
+
+:raises QgsProviderConnectionException: if any errors are encountered.
+
+.. versionadded:: 3.32
 %End
 
     SIP_PYOBJECT supportedRelationshipCardinalities() const /TypeHint="List[Qgis.RelationshipCardinality]"/;
@@ -981,6 +1020,14 @@ Checks if ``capability`` is supported.
 :raises QgsProviderConnectionException: if the capability is not supported
 %End
 
+    void checkCapability( Qgis::DatabaseProviderConnectionCapability2 capability ) const;
+%Docstring
+Checks if ``capability`` is supported.
+
+:raises QgsProviderConnectionException: if the capability is not supported
+%End
+
+
 
 };
 

diff --git a/python/core/auto_generated/qgis.sip.in b/python/core/auto_generated/qgis.sip.in
@@ -1953,6 +1953,14 @@ The development version
       PartitionedTable,
     };
 
+    enum class DatabaseProviderConnectionCapability2
+    {
+      SetFieldComment,
+      SetFieldAlias,
+    };
+    typedef QFlags<Qgis::DatabaseProviderConnectionCapability2> DatabaseProviderConnectionCapabilities2;
+
+
     static const double DEFAULT_SEARCH_RADIUS_MM;
 
     static const float DEFAULT_MAPTOPIXEL_THRESHOLD;
@@ -2103,6 +2111,8 @@ QFlags<Qgis::LabelLinePlacementFlag> operator|(Qgis::LabelLinePlacementFlag f1,
 
 QFlags<Qgis::LabelPolygonPlacementFlag> operator|(Qgis::LabelPolygonPlacementFlag f1, QFlags<Qgis::LabelPolygonPlacementFlag> f2);
 
+QFlags<Qgis::DatabaseProviderConnectionCapability2> operator|(Qgis::DatabaseProviderConnectionCapability2 f1, QFlags<Qgis::DatabaseProviderConnectionCapability2> f2);
+
 
 
 

diff --git a/src/core/providers/qgsabstractdatabaseproviderconnection.cpp b/src/core/providers/qgsabstractdatabaseproviderconnection.cpp
@@ -34,11 +34,17 @@ QgsAbstractDatabaseProviderConnection::QgsAbstractDatabaseProviderConnection( co
 {
 
 }
+
 QgsAbstractDatabaseProviderConnection::Capabilities QgsAbstractDatabaseProviderConnection::capabilities() const
 {
   return mCapabilities;
 }
 
+Qgis::DatabaseProviderConnectionCapabilities2 QgsAbstractDatabaseProviderConnection::capabilities2() const
+{
+  return mCapabilities2;
+}
+
 QgsAbstractDatabaseProviderConnection::GeometryColumnCapabilities QgsAbstractDatabaseProviderConnection::geometryColumnCapabilities()
 {
   return mGeometryColumnCapabilities;
@@ -69,13 +75,20 @@ void QgsAbstractDatabaseProviderConnection::checkCapability( QgsAbstractDatabase
   }
 }
 
-QString QgsAbstractDatabaseProviderConnection::providerKey() const
+void QgsAbstractDatabaseProviderConnection::checkCapability( Qgis::DatabaseProviderConnectionCapability2 capability ) const
 {
-  return mProviderKey;
+  if ( ! mCapabilities2.testFlag( capability ) )
+  {
+    throw QgsProviderConnectionException( QObject::tr( "Operation '%1' is not supported for this connection" ).arg( qgsEnumValueToKey( capability ) ) );
+  }
 }
 
 ///@endcond
 
+QString QgsAbstractDatabaseProviderConnection::providerKey() const
+{
+  return mProviderKey;
+}
 
 QMultiMap<Qgis::SqlKeywordCategory, QStringList> QgsAbstractDatabaseProviderConnection::sqlDictionary()
 {
@@ -1359,6 +1372,16 @@ void QgsAbstractDatabaseProviderConnection::addFieldDomain( const QgsFieldDomain
   checkCapability( Capability::AddFieldDomain );
 }
 
+void QgsAbstractDatabaseProviderConnection::setFieldAlias( const QString &, const QString &, const QString &, const QString & ) const
+{
+  checkCapability( Qgis::DatabaseProviderConnectionCapability2::SetFieldAlias );
+}
+
+void QgsAbstractDatabaseProviderConnection::setFieldComment( const QString &, const QString &, const QString &, const QString & ) const
+{
+  checkCapability( Qgis::DatabaseProviderConnectionCapability2::SetFieldComment );
+}
+
 QList< QgsWeakRelation > QgsAbstractDatabaseProviderConnection::relationships( const QString &, const QString & ) const
 {
   checkCapability( Capability::RetrieveRelationships );

diff --git a/src/core/providers/qgsabstractdatabaseproviderconnection.h b/src/core/providers/qgsabstractdatabaseproviderconnection.h
@@ -479,6 +479,8 @@ class CORE_EXPORT QgsAbstractDatabaseProviderConnection : public QgsAbstractProv
 
     /**
      * The Capability enum represents the operations supported by the connection.
+     *
+     * \see Qgis::DatabaseProviderConnectionCapability2
      */
     enum Capability
     {
@@ -557,10 +559,20 @@ class CORE_EXPORT QgsAbstractDatabaseProviderConnection : public QgsAbstractProv
     // Public interface
 
     /**
-     * Returns connection capabilities
+     * Returns connection capabilities.
+     *
+     * \see capabilities2()
      */
     Capabilities capabilities() const;
 
+    /**
+     * Returns extended connection capabilities.
+     *
+     * \see capabilities()
+     * \since QGIS 3.32
+     */
+    Qgis::DatabaseProviderConnectionCapabilities2 capabilities2() const;
+
     /**
      * Returns connection geometry column capabilities (Z, M, SinglePart, Curves).
      *
@@ -904,6 +916,32 @@ class CORE_EXPORT QgsAbstractDatabaseProviderConnection : public QgsAbstractProv
      */
     virtual void addFieldDomain( const QgsFieldDomain &domain, const QString &schema ) const SIP_THROW( QgsProviderConnectionException );
 
+    /**
+     * Sets the \a alias for the existing field with the specified name.
+     *
+     * \param fieldName name of the field to be modified
+     * \param schema name of the schema (schema is ignored if not supported by the backend).
+     * \param tableName name of the table
+     * \param alias alias to set for the field. Set to an empty string to remove a previously set alias.
+     *
+     * \throws QgsProviderConnectionException if any errors are encountered.
+     * \since QGIS 3.32
+     */
+    virtual void setFieldAlias( const QString &fieldName, const QString &schema, const QString &tableName, const QString &alias ) const SIP_THROW( QgsProviderConnectionException );
+
+    /**
+     * Sets the \a comment for the existing field with the specified name.
+     *
+     * \param fieldName name of the field to be modified
+     * \param schema name of the schema (schema is ignored if not supported by the backend).
+     * \param tableName name of the table
+     * \param comment comment to set for the field. Set to an empty string to remove a previously set comment.
+     *
+     * \throws QgsProviderConnectionException if any errors are encountered.
+     * \since QGIS 3.32
+     */
+    virtual void setFieldComment( const QString &fieldName, const QString &schema, const QString &tableName, const QString &comment ) const SIP_THROW( QgsProviderConnectionException );
+
     /**
      * Returns a list of relationship cardinalities which are supported by the provider.
      *
@@ -1092,9 +1130,18 @@ class CORE_EXPORT QgsAbstractDatabaseProviderConnection : public QgsAbstractProv
      * \throws QgsProviderConnectionException if the capability is not supported
      */
     void checkCapability( Capability capability ) const;
+
+    /**
+     * Checks if \a capability is supported.
+     *
+     * \throws QgsProviderConnectionException if the capability is not supported
+     */
+    void checkCapability( Qgis::DatabaseProviderConnectionCapability2 capability ) const;
 ///@endcond
 
     Capabilities mCapabilities = Capabilities() SIP_SKIP;
+    Qgis::DatabaseProviderConnectionCapabilities2 mCapabilities2 = Qgis::DatabaseProviderConnectionCapabilities2() SIP_SKIP;
+
     GeometryColumnCapabilities mGeometryColumnCapabilities = GeometryColumnCapabilities() SIP_SKIP;
     Qgis::SqlLayerDefinitionCapabilities mSqlLayerDefinitionCapabilities = Qgis::SqlLayerDefinitionCapabilities() SIP_SKIP;
     QString mProviderKey;

diff --git a/src/core/qgis.h b/src/core/qgis.h
@@ -3381,6 +3381,20 @@ class CORE_EXPORT Qgis
     };
     Q_ENUM( PostgresRelKind )
 
+    /**
+     * The Capability enum represents the extended operations supported by the connection.
+     *
+     * \since QGIS 3.32
+     */
+    enum class DatabaseProviderConnectionCapability2 : int
+    {
+      SetFieldComment = 1 << 0, //!< Can set comments for fields via setFieldComment()
+      SetFieldAlias = 1 << 1, //!< Can set aliases for fields via setFieldAlias()
+    };
+    Q_ENUM( DatabaseProviderConnectionCapability2 )
+    Q_DECLARE_FLAGS( DatabaseProviderConnectionCapabilities2, DatabaseProviderConnectionCapability2 )
+    Q_FLAG( DatabaseProviderConnectionCapabilities2 )
+
     /**
      * Identify search radius in mm
      * \since QGIS 2.3
@@ -3539,6 +3553,7 @@ Q_DECLARE_OPERATORS_FOR_FLAGS( Qgis::ScriptLanguageCapabilities )
 Q_DECLARE_OPERATORS_FOR_FLAGS( Qgis::LayerTreeFilterFlags )
 Q_DECLARE_OPERATORS_FOR_FLAGS( Qgis::LabelLinePlacementFlags )
 Q_DECLARE_OPERATORS_FOR_FLAGS( Qgis::LabelPolygonPlacementFlags )
+Q_DECLARE_OPERATORS_FOR_FLAGS( Qgis::DatabaseProviderConnectionCapabilities2 )
 
 // hack to workaround warnings when casting void pointers
 // retrieved from QLibrary::resolve to function pointers.