Add docstub checks to CI

.github/workflows/doc_checks.yml

@@ -37,6 +37,7 @@ jobs:
           python3 -m pip install -r doc/requirements.txt
           python3 -m pip install setuptools
           python3 -m pip install pytest
+          python3 -m pip install docstub
           echo PATH=$PATH >> $GITHUB_ENV
 
     - name: Build GDAL
@@ -94,6 +95,12 @@ jobs:
         ctest -V -R spelling --output-on-failure
       working-directory: build
 
+    - name: Docstub annotations
+      shell: bash -l {0}
+      run: |
+        ctest -V -R docstub-annotations --output-on-failure
+      working-directory: build
+
     # ReadTheDocs pull requests do not build PDF, but we can break it though,
     # so build it here
     - name: PDF build

CMakeLists.txt

@@ -240,6 +240,7 @@ endif()
 
 if (SWIG_FOUND AND (Python_Interpreter_FOUND OR Python_FOUND))
   option(BUILD_PYTHON_BINDINGS "Build Python bindings" ON)
+  option(BUILD_PYTHON_STUBS "Generate Python stub files for Python binding" OFF)
 else()
   option(BUILD_PYTHON_BINDINGS "Build Python bindings" OFF)
 endif()

doc/CMakeLists.txt

@@ -213,4 +213,11 @@ if (BUILD_DOCS)
                ${CMAKE_BINARY_DIR}/swig/python/osgeo/osr.py
              WORKING_DIRECTORY ${CMAKE_SOURCE_DIR})
 
+    # Check docstub annotations
+    add_test(NAME docstub-annotations
+             COMMAND ${CMAKE_COMMAND} -E env ${BUILD_RUN_ENV}
+             ${Python_EXECUTABLE} -m docstub run ${CMAKE_BINARY_DIR}/swig/python/osgeo
+             --config ${CMAKE_BINARY_DIR}/swig/python/pyproject.toml
+             WORKING_DIRECTORY ${CMAKE_SOURCE_DIR})
+
 endif ()

swig/include/python/gdal_python.i

@@ -2406,7 +2406,7 @@ def ReleaseResultSet(self, sql_lyr):
 
       Returns
       -------
-      datetime.datetime:
+      datetime
           Datetime value, or None if it is invalid
       """
 
@@ -2438,7 +2438,7 @@ def ReleaseResultSet(self, sql_lyr):
           The index of the row to read (starting at 0)
       iCol : int
           The index of the column to read (starting at 0)
-      dt : datetime.datetime | RATDateTime | None
+      dt : datetime | RATDateTime | None
           The datetime value
       """
 

swig/python/CMakeLists.txt

@@ -377,6 +377,18 @@ if __name__ == '__main__':
 
   add_custom_target(python_binding ALL DEPENDS ${PY_SO_LIST} ${PY_SO_LIST_WITH_RPATH} ${GDAL_PYTHON_PYSOURCES} ${GDAL_LIB_TARGET_NAME})
 
+  if (BUILD_PYTHON_STUBS)
+    add_custom_target(
+        python_stub_files
+        ALL
+        COMMAND ${Python_EXECUTABLE_CMAKE} -m docstub run
+                ${CMAKE_CURRENT_BINARY_DIR}/osgeo
+                --config ${CMAKE_CURRENT_BINARY_DIR}/pyproject.toml
+        WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+        DEPENDS ${GDAL_PYTHON_PYSOURCES}
+    )
+  endif ()
+
   # Generate wheel
   if (ONLY_GENERATE_FOR_NON_DEBUG)
     set(BUILD_BDIST_WHEEL_FILENAME ${CMAKE_CURRENT_BINARY_DIR}/build_bdist_wheel_$<CONFIG>.cmake)

swig/python/pyproject.toml

@@ -45,7 +45,9 @@ Changelog = "https://github.com/OSGeo/gdal/blob/master/NEWS.md"
 Issues = "https://github.com/OSGeo/gdal/issues"
 
 [tool.docstub.types]
+datetime = "datetime.datetime"
 CoordinateTransform = "osgeo.osr.CoordinateTransform"
+CoordinateTransformation = "osgeo.osr.CoordinateTransformation"
 Dataset = "osgeo.gdal.Dataset"
 Driver = "osgeo.gdal.Driver"
 Feature = "osgeo.ogr.Feature"

swig/python/pyproject.toml.setuptools_gte_77

@@ -42,3 +42,17 @@ Documentation = "https://gdal.org"
 Repository = "https://github.com/OSGeo/GDAL.git"
 Changelog = "https://github.com/OSGeo/gdal/blob/master/NEWS.md"
 Issues = "https://github.com/OSGeo/gdal/issues"
+
+[tool.docstub.types]
+datetime = "datetime.datetime"
+CoordinateTransform = "osgeo.osr.CoordinateTransform"
+CoordinateTransformation = "osgeo.osr.CoordinateTransformation"
+Dataset = "osgeo.gdal.Dataset"
+Driver = "osgeo.gdal.Driver"
+Feature = "osgeo.ogr.Feature"
+FieldDomain = "osgeo.ogr.FieldDomain"
+GeomFieldDefn = "osgeo.ogr.GeomFieldDefn"
+Layer = "osgeo.ogr.Layer"
+StyleTable = "osgeo.ogr.StyleTable"
+SpatialReference = "osgeo.osr.SpatialReference"
+Transformer = "osgeo.gdal.Transformer"