Python Binding Docstring Updates for Stub Generation

[geographika]

What does this PR do?

This pull request updates the Python SWIG binding docstrings to allow the docstub tool to generate stub files from Python docstrings. This approach was discussed at the recent OSGeo codesprint in Riga.

The longer-term aim is to use these stubs to allow type-checking within the GDAL Python bindings and for user code and scripts, by building on all the previous work on the Python interface and docstrings.

A summary of key changes is below. These were added using a mix of manual review, Notepad++ search/replace and regexes.

• add a space before : for parameters
• return values should not have a trailing :
• options : dict/list, optional should be options : dict or list, optional
• underlined headers needs to match the title length
• fixed a few typos
• replaced tabs with 4 spaces
• Example -> Examples
• any type added when unsure of parameter types (or 20-30 parameters without documented types) - these can be refined over time

To create the stubs:

> docstub run . --no-cache --config C:\docs\gdal\swig\python\pyproject.toml
1413 matched annotations
0 total errors

Finished in 21.914 s

For this to run successfully, I added a patch to the docstub library - scientific-python/docstub#89.

A few notes:

• some GDAL types were added to pyproject.toml as they returned errors in docstub such as Unknown name in doctype: 'Layer' when used as parameter types. However in other docstrings the same types didn't return errors. I believe this is related to import order and the location of the annotation in the files. Updating the .toml file gets rid of the warnings, and allows the type to be kept. The advantage of using GDAL types (rather than object or any) is that Sphinx generates a clickable link to the class in the Python API docs.
• I'm unsure where the PyCapsule type comes from
• a follow-up pull request will look at adding the stub generation to CI.

What are related issues/pull requests?

• See Adding Python Stubs or Type Hints to gdal #12919 for discussions on typing
• Related Expose argument names to Python bindings #13145

cc @dbaston

[coveralls]

coverage: 71.245% (-0.004%) from 71.249%
when pulling 18a9c2d on geographika:docstring-fixes
into 59f6276 on OSGeo:master.

[dbaston]

Wow, thanks for cleaning these up! I'm able to generate the stubs locally. Do we need to do anything to cause them to be imported? I notice the following is empty:

>>> from osgeo import gdal
>>> gdal.OpenEx.__annotations__
{}

[geographika]

Wow, thanks for cleaning these up! I'm able to generate the stubs locally. Do we need to do anything to cause them to be imported? I notice the following is empty:

>>> from osgeo import gdal
>>> gdal.OpenEx.__annotations__
{}

@dbaston - as I understand it, the above approach will only work with inline annotations (within the .py files). The .pyi stubs will work for IDEs with stub support, and type checkers such as mypy. I've yet to test though.

[dbaston]

with test.py:

from osgeo import gdal

ds : int
ds = gdal.OpenEx('test.shp')

running mypy test.py gives

test.py:4: error: Incompatible types in assignment (expression has type "Dataset | None", variable has type "int")  [assignment]
Found 1 error in 1 file (checked 1 source file)

So I'd say they're working as intended! Until we address #13145 I guess they'll only work for return types, though.