Use TypeHint annotation to indicate correct return type when sip code returns SIP_PYOBJECT

Provides correct return type hints to IDEs (and hopefully PyQGIS docs too!)

Author: nyalldawson

python/core/auto_generated/geometry/qgsabstractgeometry.sip.in

@@ -816,7 +816,7 @@ Returns next vertex of the geometry (undefined behavior if hasNext() returns fal
     sipRes = sipCpp;
 %End
 
-    SIP_PYOBJECT __next__();
+    SIP_PYOBJECT __next__() /TypeHint="QgsPoint"/;
 %MethodCode
     if ( sipCpp->hasNext() )
       sipRes = sipConvertFromType( new QgsPoint( sipCpp->next() ), sipType_QgsPoint, Py_None );
@@ -863,7 +863,7 @@ Returns next part of the geometry (undefined behavior if hasNext() returns false
     sipRes = sipCpp;
 %End
 
-    SIP_PYOBJECT __next__();
+    SIP_PYOBJECT __next__() /TypeHint="QgsAbstractGeometry"/;
 %MethodCode
     if ( sipCpp->hasNext() )
       sipRes = sipConvertFromType( sipCpp->next(), sipType_QgsAbstractGeometry, NULL );
@@ -911,7 +911,7 @@ Returns next part of the geometry (undefined behavior if hasNext() returns false
     sipRes = sipCpp;
 %End
 
-    SIP_PYOBJECT __next__();
+    SIP_PYOBJECT __next__() /TypeHint="QgsAbstractGeometry"/;
 %MethodCode
     if ( sipCpp->hasNext() )
       sipRes = sipConvertFromType( const_cast< QgsAbstractGeometry * >( sipCpp->next() ), sipType_QgsAbstractGeometry, NULL );

python/core/auto_generated/geometry/qgsgeometrycollection.sip.in

@@ -58,7 +58,7 @@ Returns the number of geometries within the collection.
 
 
 
-    SIP_PYOBJECT geometryN( int n );
+    SIP_PYOBJECT geometryN( int n ) /TypeHint="QgsAbstractGeometry"/;
 %Docstring
 Returns a geometry from within the collection.
 
@@ -222,7 +222,7 @@ Returns a geometry without curves. Caller takes ownership
 
 
 
-    SIP_PYOBJECT __getitem__( int index );
+    SIP_PYOBJECT __getitem__( int index ) /TypeHint="QgsAbstractGeometry"/;
 %Docstring
 Returns the geometry at the specified ``index``. An IndexError will be raised if no geometry with the specified ``index`` exists.
 

python/core/auto_generated/geometry/qgslinestring.sip.in

@@ -82,7 +82,7 @@ Construct a linestring from a single 2d line segment.
 
 
 
-    SIP_PYOBJECT pointN( int i ) const;
+    SIP_PYOBJECT pointN( int i ) const /TypeHint="QgsPoint"/;
 %Docstring
 Returns the point at the specified index. An IndexError will be raised if no point with the specified index exists.
 
@@ -505,7 +505,7 @@ of the curve.
     sipRes = PyUnicode_FromString( str.toUtf8().constData() );
 %End
 
-    SIP_PYOBJECT __getitem__( int index );
+    SIP_PYOBJECT __getitem__( int index ) /TypeHint="QgsPoint"/;
 %Docstring
 Returns the point at the specified ``index``. An IndexError will be raised if no point with the specified ``index`` exists.
 

python/core/auto_generated/qgsfeatureiterator.sip.in

@@ -206,7 +206,7 @@ Wrapper for iterator of features from vector data provider or vector layer
     sipRes = sipCpp;
 %End
 
-    SIP_PYOBJECT __next__();
+    SIP_PYOBJECT __next__() /TypeHint="QgsFeature"/;
 %MethodCode
     std::unique_ptr< QgsFeature > f = qgis::make_unique< QgsFeature >();
     bool result = false;

scripts/sipify.pl

@@ -393,6 +393,7 @@ sub fix_annotations {
     $line =~ s/\bSIP_TRANSFERTHIS\b/\/TransferThis\//;
 
     $line =~ s/SIP_PYNAME\(\s*(\w+)\s*\)/\/PyName=$1\//;
+    $line =~ s/SIP_TYPEHINT\(\s*(\w+)\s*\)/\/TypeHint="$1"\//;
     $line =~ s/SIP_VIRTUALERRORHANDLER\(\s*(\w+)\s*\)/\/VirtualErrorHandler=$1\//;
     $line =~ s/SIP_THROW\(\s*(\w+)\s*\)/throw\( $1 \)/;
 

src/core/geometry/qgsabstractgeometry.h

@@ -1039,7 +1039,7 @@ class CORE_EXPORT QgsVertexIterator
     sipRes = sipCpp;
     % End
 
-    SIP_PYOBJECT __next__();
+    SIP_PYOBJECT __next__() SIP_TYPEHINT( QgsPoint );
     % MethodCode
     if ( sipCpp->hasNext() )
       sipRes = sipConvertFromType( new QgsPoint( sipCpp->next() ), sipType_QgsPoint, Py_None );
@@ -1088,7 +1088,7 @@ class CORE_EXPORT QgsGeometryPartIterator
     sipRes = sipCpp;
     % End
 
-    SIP_PYOBJECT __next__();
+    SIP_PYOBJECT __next__() SIP_TYPEHINT( QgsAbstractGeometry );
     % MethodCode
     if ( sipCpp->hasNext() )
       sipRes = sipConvertFromType( sipCpp->next(), sipType_QgsAbstractGeometry, NULL );
@@ -1138,7 +1138,7 @@ class CORE_EXPORT QgsGeometryConstPartIterator
     sipRes = sipCpp;
     % End
 
-    SIP_PYOBJECT __next__();
+    SIP_PYOBJECT __next__() SIP_TYPEHINT( QgsAbstractGeometry );
     % MethodCode
     if ( sipCpp->hasNext() )
       sipRes = sipConvertFromType( const_cast< QgsAbstractGeometry * >( sipCpp->next() ), sipType_QgsAbstractGeometry, NULL );

src/core/geometry/qgsgeometrycollection.h

@@ -88,7 +88,7 @@ class CORE_EXPORT QgsGeometryCollection: public QgsAbstractGeometry
 #ifndef SIP_RUN
     QgsAbstractGeometry *geometryN( int n );
 #else
-    SIP_PYOBJECT geometryN( int n );
+    SIP_PYOBJECT geometryN( int n ) SIP_TYPEHINT( QgsAbstractGeometry );
     % MethodCode
     if ( a0 < 0 || a0 >= sipCpp->numGeometries() )
     {
@@ -238,7 +238,7 @@ class CORE_EXPORT QgsGeometryCollection: public QgsAbstractGeometry
     *
     * \since QGIS 3.6
     */
-    SIP_PYOBJECT __getitem__( int index );
+    SIP_PYOBJECT __getitem__( int index ) SIP_TYPEHINT( QgsAbstractGeometry );
     % MethodCode
     const int count = sipCpp->numGeometries();
     if ( a0 < -count || a0 >= count )

src/core/geometry/qgslinestring.h

@@ -109,7 +109,7 @@ class CORE_EXPORT QgsLineString: public QgsCurve
      * Indexes can be less than 0, in which case they correspond to positions from the end of the line. E.g. an index of -1
      * corresponds to the last point in the line.
      */
-    SIP_PYOBJECT pointN( int i ) const;
+    SIP_PYOBJECT pointN( int i ) const SIP_TYPEHINT( QgsPoint );
     % MethodCode
     const int count = sipCpp->numPoints();
     if ( a0 < -count || a0 >= count )
@@ -647,7 +647,7 @@ class CORE_EXPORT QgsLineString: public QgsCurve
     *
     * \since QGIS 3.6
     */
-    SIP_PYOBJECT __getitem__( int index );
+    SIP_PYOBJECT __getitem__( int index ) SIP_TYPEHINT( QgsPoint );
     % MethodCode
     const int count = sipCpp->numPoints();
     if ( a0 < -count || a0 >= count )

src/core/qgis_sip.h

@@ -197,6 +197,14 @@
  */
 #define SIP_DOC_TEMPLATE
 
+/*
+ * Specifies the type of the value returned by the function as it will appear in any
+ * generated docstrings and PEP 484 type hints. It is usually used with results of type
+ * SIP_PYOBJECT to provide a more specific type.
+ * Available for SIP 4.18+
+ */
+#define SIP_TYPEHINT(type)
+
 /*
  * Sip supports the final keyword since version 4.19.0, earlier than that
  * we will have build issues because it tries to override final methods.

src/core/qgsfeatureiterator.h

@@ -270,7 +270,7 @@ class CORE_EXPORT QgsFeatureIterator
     sipRes = sipCpp;
     % End
 
-    SIP_PYOBJECT __next__();
+    SIP_PYOBJECT __next__() SIP_TYPEHINT( QgsFeature );
     % MethodCode
     std::unique_ptr< QgsFeature > f = qgis::make_unique< QgsFeature >();
     bool result = false;