Add capacity for storing additional metadata/properties in QgsField

nyalldawson · nyalldawson · commit a87db9c91c95 · 2023-03-24T11:11:46.000+10:00
This adds the API framework for storing additional, semi-structured properties inside QgsField objects. The intention is that strong field-type specific properties can be stored. Eg for a geometry field type coming from the postgres provider the metadata can be used to store the associated CRS and WKB types so that clients can be aware of the correct format required for geometries stored in that field. Instead of cluttering the QgsField API with specific getters/setters for properties like crs(), wkbType(), etc which only apply for a certain field type, the metadata map approach helps us keep the API nice and slim. The API has been designed to follow the approach used by various Qt objects (such as QTextFormat) where a preset set of keys are exposed as an enum, but additional ones can be used for custom property storage. This allows for a more structured use of properties with conventions which apply across different providers (as opposed to a free-form string key approach). Refs #49380
diff --git a/python/core/auto_additions/qgis.py b/python/core/auto_additions/qgis.py
@@ -1072,6 +1072,13 @@
 Qgis.SublayerPromptMode.__doc__ = 'Specifies how to handle layer sources with multiple sublayers.\n\n.. versionadded:: 3.22\n\n' + '* ``AlwaysAsk``: ' + Qgis.SublayerPromptMode.AlwaysAsk.__doc__ + '\n' + '* ``AskExcludingRasterBands``: ' + Qgis.SublayerPromptMode.AskExcludingRasterBands.__doc__ + '\n' + '* ``NeverAskSkip``: ' + Qgis.SublayerPromptMode.NeverAskSkip.__doc__ + '\n' + '* ``NeverAskLoadAll``: ' + Qgis.SublayerPromptMode.NeverAskLoadAll.__doc__
 # --
 Qgis.SublayerPromptMode.baseClass = Qgis
+# monkey patching scoped based enum
+Qgis.FieldMetadataProperty.GeometryCrs.__doc__ = "Available for geometry field types with a specific associated coordinate reference system (as a QgsCoordinateReferenceSystem value)"
+Qgis.FieldMetadataProperty.GeometryWkbType.__doc__ = "Available for geometry field types which accept geometries of a specific WKB type only (as a QgsWkbTypes.Type value)"
+Qgis.FieldMetadataProperty.CustomProperty.__doc__ = "Starting point for custom user set properties"
+Qgis.FieldMetadataProperty.__doc__ = 'Standard field metadata values.\n\n.. versionadded:: 3.30\n\n' + '* ``GeometryCrs``: ' + Qgis.FieldMetadataProperty.GeometryCrs.__doc__ + '\n' + '* ``GeometryWkbType``: ' + Qgis.FieldMetadataProperty.GeometryWkbType.__doc__ + '\n' + '* ``CustomProperty``: ' + Qgis.FieldMetadataProperty.CustomProperty.__doc__
+# --
+Qgis.FieldMetadataProperty.baseClass = Qgis
 QgsVectorLayer.SelectBehavior = Qgis.SelectBehavior
 # monkey patching scoped based enum
 QgsVectorLayer.SetSelection = Qgis.SelectBehavior.SetSelection
diff --git a/python/core/auto_generated/qgis.sip.in b/python/core/auto_generated/qgis.sip.in
@@ -623,6 +623,13 @@ The development version
       NeverAskLoadAll,
     };
 
+    enum class FieldMetadataProperty
+    {
+      GeometryCrs,
+      GeometryWkbType,
+      CustomProperty,
+    };
+
     enum class SelectBehavior
       {
       SetSelection,
diff --git a/python/core/auto_generated/qgsfield.sip.in b/python/core/auto_generated/qgsfield.sip.in
@@ -173,6 +173,46 @@ Gets the precision of the field. Not all field types have a related precision.
     QString comment() const;
 %Docstring
 Returns the field comment
+%End
+
+    QMap< int, QVariant > metadata() const;
+%Docstring
+Returns the map of field metadata.
+
+Map keys should match values from the Qgis.FieldMetadataProperty enum.
+
+.. seealso:: :py:func:`setMetadata`
+
+.. versionadded:: 3.30
+%End
+
+    QVariant metadata( Qgis::FieldMetadataProperty property ) const;
+%Docstring
+Returns a specific metadata ``property``.
+
+.. seealso:: :py:func:`setMetadata`
+
+.. versionadded:: 3.30
+%End
+
+    void setMetadata( const QMap< int, QVariant > metadata );
+%Docstring
+Sets the map of field ``metadata``.
+
+Map keys should match values from the Qgis.FieldMetadataProperty enum.
+
+.. seealso:: :py:func:`metadata`
+
+.. versionadded:: 3.30
+%End
+
+    void setMetadata( Qgis::FieldMetadataProperty property, const QVariant &value );
+%Docstring
+Sets a metadata ``property`` to ``value``.
+
+.. seealso:: :py:func:`metadata`
+
+.. versionadded:: 3.30
 %End
 
     bool isNumeric() const;
diff --git a/src/core/qgis.h b/src/core/qgis.h
@@ -1000,6 +1000,19 @@ class CORE_EXPORT Qgis
     };
     Q_ENUM( SublayerPromptMode )
 
+    /**
+     * Standard field metadata values.
+     *
+     * \since QGIS 3.30
+     */
+    enum class FieldMetadataProperty : int
+    {
+      GeometryCrs = 0x1000, //!< Available for geometry field types with a specific associated coordinate reference system (as a QgsCoordinateReferenceSystem value)
+      GeometryWkbType = 0x1001, //!< Available for geometry field types which accept geometries of a specific WKB type only (as a QgsWkbTypes::Type value)
+      CustomProperty = 0x100000, //!< Starting point for custom user set properties
+    };
+    Q_ENUM( FieldMetadataProperty )
+
     /**
      * Specifies how a selection should be applied.
      *
diff --git a/src/core/qgsfield.cpp b/src/core/qgsfield.cpp
@@ -167,6 +167,26 @@ QString QgsField::comment() const
   return d->comment;
 }
 
+QMap<int, QVariant> QgsField::metadata() const
+{
+  return d->metadata;
+}
+
+QVariant QgsField::metadata( Qgis::FieldMetadataProperty property ) const
+{
+  return d->metadata.value( static_cast< int >( property ) );
+}
+
+void QgsField::setMetadata( const QMap<int, QVariant> metadata )
+{
+  d->metadata = metadata;
+}
+
+void QgsField::setMetadata( Qgis::FieldMetadataProperty property, const QVariant &value )
+{
+  d->metadata[ static_cast< int >( property )] = value;
+}
+
 bool QgsField::isNumeric() const
 {
   return d->type == QVariant::Double || d->type == QVariant::Int || d->type == QVariant::UInt || d->type == QVariant::LongLong || d->type == QVariant::ULongLong;
@@ -374,7 +394,7 @@ QString QgsField::displayString( const QVariant &v ) const
   else if ( d->typeName.compare( QLatin1String( "json" ), Qt::CaseInsensitive ) == 0 || d->typeName == QLatin1String( "jsonb" ) )
   {
     const QJsonDocument doc = QJsonDocument::fromVariant( v );
-    return QString::fromUtf8( doc.toJson().data() );
+    return QString::fromUtf8( doc.toJson().constData() );
   }
   else if ( d->type == QVariant::ByteArray )
   {
@@ -722,6 +742,7 @@ QDataStream &operator<<( QDataStream &out, const QgsField &field )
   out << field.constraints().constraintDescription();
   out << static_cast< quint32 >( field.subType() );
   out << static_cast< int >( field.splitPolicy() );
+  out << field.metadata();
   return out;
 }
 
@@ -749,10 +770,11 @@ QDataStream &operator>>( QDataStream &in, QgsField &field )
   QString defaultValueExpression;
   QString constraintExpression;
   QString constraintDescription;
+  QMap< int, QVariant > metadata;
 
   in >> name >> type >> typeName >> length >> precision >> comment >> alias
      >> defaultValueExpression >> applyOnUpdate >> constraints >> originNotNull >> originUnique >> originExpression >> strengthNotNull >> strengthUnique >> strengthExpression >>
-     constraintExpression >> constraintDescription >> subType >> splitPolicy;
+     constraintExpression >> constraintDescription >> subType >> splitPolicy >> metadata;
   field.setName( name );
   field.setType( static_cast< QVariant::Type >( type ) );
   field.setTypeName( typeName );
@@ -787,5 +809,6 @@ QDataStream &operator>>( QDataStream &in, QgsField &field )
   fieldConstraints.setConstraintExpression( constraintExpression, constraintDescription );
   field.setConstraints( fieldConstraints );
   field.setSubType( static_cast< QVariant::Type >( subType ) );
+  field.setMetadata( metadata );
   return in;
 }
diff --git a/src/core/qgsfield.h b/src/core/qgsfield.h
@@ -22,6 +22,7 @@
 #include <QSharedDataPointer>
 #include "qgis_core.h"
 #include "qgis_sip.h"
+#include "qgis.h"
 
 typedef QList<int> QgsAttributeList SIP_SKIP;
 
@@ -216,6 +217,42 @@ class CORE_EXPORT QgsField
      */
     QString comment() const;
 
+    /**
+     * Returns the map of field metadata.
+     *
+     * Map keys should match values from the Qgis::FieldMetadataProperty enum.
+     *
+     * \see setMetadata()
+     * \since QGIS 3.30
+     */
+    QMap< int, QVariant > metadata() const;
+
+    /**
+     * Returns a specific metadata \a property.
+     *
+     * \see setMetadata()
+     * \since QGIS 3.30
+     */
+    QVariant metadata( Qgis::FieldMetadataProperty property ) const;
+
+    /**
+     * Sets the map of field \a metadata.
+     *
+     * Map keys should match values from the Qgis::FieldMetadataProperty enum.
+     *
+     * \see metadata()
+     * \since QGIS 3.30
+     */
+    void setMetadata( const QMap< int, QVariant > metadata );
+
+    /**
+     * Sets a metadata \a property to \a value.
+     *
+     * \see metadata()
+     * \since QGIS 3.30
+     */
+    void setMetadata( Qgis::FieldMetadataProperty property, const QVariant &value );
+
     /**
      * Returns if this field is numeric. Any integer or floating point type
      * will return TRUE for this.
diff --git a/src/core/qgsfield_p.h b/src/core/qgsfield_p.h
@@ -55,14 +55,16 @@ class QgsFieldPrivate : public QSharedData
                      const QString &typeName = QString(),
                      int len = 0,
                      int prec = 0,
-                     const QString &comment = QString() )
+                     const QString &comment = QString(),
+                     const QMap< int, QVariant > &metadata = QMap< int, QVariant >() )
       : name( name )
       , type( type )
       , subType( subType )
       , typeName( typeName )
       , length( len )
       , precision( prec )
       , comment( comment )
+      , metadata( metadata )
     {
     }
 
@@ -75,6 +77,7 @@ class QgsFieldPrivate : public QSharedData
       , length( other.length )
       , precision( other.precision )
       , comment( other.comment )
+      , metadata( other.metadata )
       , alias( other.alias )
       , flags( other.flags )
       , defaultValueDefinition( other.defaultValueDefinition )
@@ -91,6 +94,7 @@ class QgsFieldPrivate : public QSharedData
     {
       return ( ( name == other.name ) && ( type == other.type ) && ( subType == other.subType )
                && ( length == other.length ) && ( precision == other.precision )
+               && ( metadata == other.metadata )
                && ( alias == other.alias ) && ( defaultValueDefinition == other.defaultValueDefinition )
                && ( constraints == other.constraints )  && ( flags == other.flags )
                && ( splitPolicy == other.splitPolicy )
@@ -118,6 +122,9 @@ class QgsFieldPrivate : public QSharedData
     //! Comment
     QString comment;
 
+    //! Field metadata. Keys should match Qgis::FieldMetadataProperty values.
+    QMap< int, QVariant > metadata;
+
     //! Alias for field name (friendly name shown to users)
     QString alias;
 
diff --git a/tests/src/core/testqgsfield.cpp b/tests/src/core/testqgsfield.cpp
@@ -103,6 +103,7 @@ void TestQgsField::copy()
   original.setConstraints( constraints );
   original.setReadOnly( true );
   original.setSplitPolicy( Qgis::FieldDomainSplitPolicy::GeometryRatio );
+  original.setMetadata( {{ 1, QStringLiteral( "abc" )}, {2, 5 }} );
   QgsField copy( original );
   QVERIFY( copy == original );
 
@@ -121,6 +122,7 @@ void TestQgsField::assignment()
   original.setConstraints( constraints );
   original.setReadOnly( true );
   original.setSplitPolicy( Qgis::FieldDomainSplitPolicy::GeometryRatio );
+  original.setMetadata( {{ 1, QStringLiteral( "abc" )}, {2, 5 }} );
   QgsField copy;
   copy = original;
   QVERIFY( copy == original );
@@ -193,6 +195,19 @@ void TestQgsField::gettersSetters()
 
   field.setSplitPolicy( Qgis::FieldDomainSplitPolicy::GeometryRatio );
   QCOMPARE( field.splitPolicy(), Qgis::FieldDomainSplitPolicy::GeometryRatio );
+
+  field.setMetadata( {{ static_cast< int >( Qgis::FieldMetadataProperty::GeometryCrs ), QStringLiteral( "abc" )}, {2, 5 }} );
+  QMap< int, QVariant> expected {{ static_cast< int >( Qgis::FieldMetadataProperty::GeometryCrs ), QStringLiteral( "abc" )}, {2, 5 }};
+  QCOMPARE( field.metadata(), expected );
+  QVERIFY( !field.metadata( Qgis::FieldMetadataProperty::GeometryWkbType ).isValid() );
+  QCOMPARE( field.metadata( Qgis::FieldMetadataProperty::GeometryCrs ).toString(), QStringLiteral( "abc" ) );
+  field.setMetadata( Qgis::FieldMetadataProperty::GeometryWkbType, QStringLiteral( "def" ) );
+  QCOMPARE( field.metadata( Qgis::FieldMetadataProperty::GeometryWkbType ).toString(), QStringLiteral( "def" ) );
+
+  expected = QMap< int, QVariant> {{ static_cast< int >( Qgis::FieldMetadataProperty::GeometryCrs ), QStringLiteral( "abc" )}, {2, 5 }
+    , {static_cast<int>( Qgis::FieldMetadataProperty::GeometryWkbType ), QStringLiteral( "def" ) }
+  };
+  QCOMPARE( field.metadata(), expected );
 }
 
 void TestQgsField::isNumeric()
@@ -336,6 +351,13 @@ void TestQgsField::equality()
   field2.setSplitPolicy( Qgis::FieldDomainSplitPolicy::GeometryRatio );
   QVERIFY( field1 == field2 );
 
+  field1.setMetadata( {{ static_cast< int >( Qgis::FieldMetadataProperty::GeometryCrs ), QStringLiteral( "abc" )}, {2, 5 }} );
+  QVERIFY( !( field1 == field2 ) );
+  QVERIFY( field1 != field2 );
+  field2.setMetadata( {{ static_cast< int >( Qgis::FieldMetadataProperty::GeometryCrs ), QStringLiteral( "abc" )}, {2, 5 }} );
+  QVERIFY( field1 == field2 );
+  QVERIFY( !( field1 != field2 ) );
+
   QgsFieldConstraints constraints1;
   QgsFieldConstraints constraints2;
   constraints1.setDomainName( QStringLiteral( "d" ) );
@@ -856,6 +878,7 @@ void TestQgsField::dataStream()
   constraints.setConstraintExpression( QStringLiteral( "constraint expression" ), QStringLiteral( "description" ) );
   constraints.setConstraintStrength( QgsFieldConstraints::ConstraintExpression, QgsFieldConstraints::ConstraintStrengthSoft );
   original.setConstraints( constraints );
+  original.setMetadata( {{ static_cast< int >( Qgis::FieldMetadataProperty::GeometryCrs ), QStringLiteral( "abc" )}, {2, 5 }} );
 
   QByteArray ba;
   QDataStream ds( &ba, QIODevice::ReadWrite );
