OSGeo · geographika · Oct 22, 2025 · Oct 22, 2025 · Oct 22, 2025 · Oct 22, 2025
diff --git a/.github/workflows/cmake_builds.yml b/.github/workflows/cmake_builds.yml
@@ -462,7 +462,7 @@ jobs:
       # Build PDF driver as plugin due to the PDFium build including libopenjp2 symbols which would conflict with external libopenjp2
       run: |
         mkdir -p $GITHUB_WORKSPACE/build
-        cmake -G "${generator}" -Werror=dev "-DCMAKE_INSTALL_PREFIX=$GITHUB_WORKSPACE/install-gdal" "-DUSE_CCACHE=ON" "-DCMAKE_PREFIX_PATH=${CONDA}/envs/gdalenv" -DCMAKE_UNITY_BUILD=${CMAKE_UNITY_BUILD} -S "$GITHUB_WORKSPACE" -B "$GITHUB_WORKSPACE/build" -DGDAL_ENABLE_PLUGINS:BOOL=ON -DGDAL_ENABLE_PLUGINS_NO_DEPS:BOOL=ON -DGDAL_USE_PUBLICDECOMPWT:BOOL=ON -DPUBLICDECOMPWT_URL=https://github.com/rouault/PublicDecompWT -DBUILD_JAVA_BINDINGS=OFF -DBUILD_CSHARP_BINDINGS=ON -DGDAL_USE_MYSQL:BOOL=OFF -DCMAKE_C_FLAGS=" /WX" -DCMAKE_CXX_FLAGS=" /WX" -DWERROR_DEV_FLAG="-Werror=dev" -DCMAKE_BUILD_TYPE=Release -DPDFIUM_ROOT=$GITHUB_WORKSPACE/install-pdfium -DGDAL_ENABLE_DRIVER_PDF_PLUGIN:BOOL=ON -DCMAKE_UNITY_BUILD=ON -DOGR_ENABLE_DRIVER_TAB_PLUGIN=OFF -DOGR_ENABLE_DRIVER_GEOJSON_PLUGIN=OFF
+        cmake -G "${generator}" -Werror=dev "-DCMAKE_INSTALL_PREFIX=$GITHUB_WORKSPACE/install-gdal" "-DUSE_CCACHE=ON" "-DCMAKE_PREFIX_PATH=${CONDA}/envs/gdalenv" -DCMAKE_UNITY_BUILD=${CMAKE_UNITY_BUILD} -S "$GITHUB_WORKSPACE" -B "$GITHUB_WORKSPACE/build" -DGDAL_ENABLE_PLUGINS:BOOL=ON -DGDAL_ENABLE_PLUGINS_NO_DEPS:BOOL=ON -DGDAL_USE_PUBLICDECOMPWT:BOOL=ON -DPUBLICDECOMPWT_URL=https://github.com/rouault/PublicDecompWT -DBUILD_JAVA_BINDINGS=OFF -DBUILD_CSHARP_BINDINGS=ON -DGDAL_USE_MYSQL:BOOL=OFF -DCMAKE_C_FLAGS=" /WX" -DCMAKE_CXX_FLAGS=" /WX" -DWERROR_DEV_FLAG="-Werror=dev" -DCMAKE_BUILD_TYPE=Release -DPDFIUM_ROOT=$GITHUB_WORKSPACE/install-pdfium -DGDAL_ENABLE_DRIVER_PDF_PLUGIN:BOOL=ON -DCMAKE_UNITY_BUILD=ON -DOGR_ENABLE_DRIVER_TAB_PLUGIN=OFF -DOGR_ENABLE_DRIVER_GEOJSON_PLUGIN=OFF -DBUILD_PYTHON_STUBS=ON
     - name: Build
       shell: bash -l {0}
       run: cmake --build $GITHUB_WORKSPACE/build --config Release -j 2
@@ -471,6 +471,9 @@ jobs:
     - name: Build HTML pages
       shell: bash -l {0}
       run: cmake --build $GITHUB_WORKSPACE/build --config Release -j 2 --target html
+    - name: Build Python stubs
+      shell: bash -l {0}
+      run: cmake --build $GITHUB_WORKSPACE/build --config Release -j 2 --target python_stub_files
     - name: test
       shell: bash -l {0}
       run: |

diff --git a/.github/workflows/doc_checks.yml b/.github/workflows/doc_checks.yml
@@ -94,6 +94,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

diff --git a/CMakeLists.txt b/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()

diff --git a/doc/CMakeLists.txt b/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 ()
diff --git a/doc/requirements.txt b/doc/requirements.txt
@@ -1,6 +1,7 @@
 # This file may be used to create an environment using:
 # $ pip install --upgrade -r <this file>
 breathe
+docstub
 fsspec
 numpy
 sphinx

diff --git a/swig/include/python/gdal_python.i b/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
       """
 

diff --git a/swig/python/CMakeLists.txt b/swig/python/CMakeLists.txt
@@ -376,6 +376,17 @@ 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
+        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)

diff --git a/swig/python/pyproject.toml b/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"

diff --git a/swig/python/pyproject.toml.setuptools_gte_77 b/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"