diff --git a/.github/workflows/doc_checks.yml b/.github/workflows/doc_checks.yml index a0685ebd5091..6d2be8d9cc25 100644 --- a/.github/workflows/doc_checks.yml +++ b/.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 diff --git a/CMakeLists.txt b/CMakeLists.txt index d856303b5c3c..b1d555119a58 100644 --- 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 index 2562f4d66c1e..3b9fab606bd9 100644 --- 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/swig/include/python/gdal_python.i b/swig/include/python/gdal_python.i index 49a7808c733f..b4771236007f 100644 --- 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 index 9355d979ac90..d7d44ebb8128 100644 --- a/swig/python/CMakeLists.txt +++ b/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_$.cmake) diff --git a/swig/python/pyproject.toml b/swig/python/pyproject.toml index dcd09d668e91..ccec3a3fe074 100644 --- 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 index 28c41a2bf2fa..04a8d0977087 100644 --- 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"