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!) (cherry picked from commit e23527b)
qgis · Jan 6, 2019 · 3dc7665 · 3dc7665
1 parent 2edb434
commit 3dc7665
Show file tree

Hide file tree

Showing 10 changed files with 25 additions and 16 deletions.
diff --git a/python/core/auto_generated/geometry/qgsabstractgeometry.sip.in b/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 );

diff --git a/python/core/auto_generated/geometry/qgsgeometrycollection.sip.in b/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.
 

diff --git a/python/core/auto_generated/geometry/qgslinestring.sip.in b/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.
 
@@ -508,7 +508,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.
 

diff --git a/python/core/auto_generated/qgsfeatureiterator.sip.in b/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;

diff --git a/scripts/sipify.pl b/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 \)/;
 

diff --git a/src/core/geometry/qgsabstractgeometry.h b/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 );

diff --git a/src/core/geometry/qgsgeometrycollection.h b/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 )

diff --git a/src/core/geometry/qgslinestring.h b/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 )
@@ -650,7 +650,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 )

diff --git a/src/core/qgis_sip.h b/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.

diff --git a/src/core/qgsfeatureiterator.h b/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;