Extension class method signatures don't surface in help(), IDE, Sphinx etc

[sgillies]

See for example from rasterio.io import DatasetReader; help(DatasetReader.read).

I don't see anything to be done other than A) nothing, or B) duplicate method definitions from cdef class DatasetReaderBase &c into DatasetReader and then delegate to the exension method using super().

Thoughts anyone?

[snowman2]

https://github.com/pyproj4/pyproj/blob/527462072036b6eb6ae228777cad9761aa57735c/setup.py#L94-L106

This might help:

"compiler_directives": {"embedsignature": True},

[sgillies]

@snowman2 I tried this but its intent is to embed the signature in a docstring if the docstring doesn't already exist. We have doctrings, the missing piece is introspect-able method definitions (the args and keyword args) to support IDEs.

[snowman2]

Makes sense. I would vote for something like option B as it is nice to be able to look up usage via the code.

[jdmcbr]

@sgillies I'm not expert enough to know whether this has undesirable consequences elsewhere, but there's a cython.binding directive that when set enables introspection (https://cython.readthedocs.io/en/latest/src/userguide/source_files_and_compilation.html#compiler-directives).

 139 cdef class DatasetReaderBase(DatasetBase):
 140 
 141     @cython.binding(True)
 142     def read(self, indexes=None, out=None, window=None, masked=False,
 143             out_shape=None, boundless=False, resampling=Resampling.nearest,
 144             fill_value=None, out_dtype=None):

Then the output of help(DatasetReader.read):

Help on cython_function_or_method in module rasterio._io:

read(self, indexes, out, window, masked, out_shape, boundless, resampling, fill_value, out_dtype)
    Read a dataset's raw pixels as an N-d array

[sgillies]

@jdmcbr binding=True as a global directive didn't have the effect I was expecting, so I didn't try decorating the methods. This almost works, but the keyword nature of the parameters and their default values are lost.

[jdmcbr]

@sgillies Right, that does limit its utility. For visibility here, there's an issue open for that (https://github.com/cython/cython/issues/1864), but that issue is now a couple years old.

[sgillies]

@jdmcbr ooh, thanks for digging that up. I think I'll see about fixing Cython and doing nothing here. I'll leave the issue open though, as a reminder.

[sgillies]

Going to look into this one again for 1.3.5.

[sgillies]

This is fixed in 3.0.0a11 (and maybe earlier).

With Cython 0.29.29 from rasterio.io import DatasetReader; help(DatasetReader.read) gives

Help on method_descriptor:

read(...)
    Read band data and, optionally, mask as an array.

...

With 3.0.0a11

Help on cython_function_or_method in module rasterio._io:

read(self, indexes=None, out=None, window=None, masked=False, out_shape=None, boundless=False, resampling=<Resampling.nearest: 0>, fill_value=None, out_dtype=None)
    Read band data and, optionally, mask as an array.

The next action is switch to Cython 3.0 alpha in the main branch? Yes?