Clarification on links for chained methods

[scottyhq]

Thanks for this very useful extension!

I'm wondering if it's possible in general to have multiple links to methods in docs for chained code. Here is a simple example:

# I'd love two links here but only np.array linked not np.mean:
np.array([[1, 2], [3, 4]]).mean()

# Single line with multiple links w/o chaining
np.mean(np.array([[1, 2], [3, 4]]))

# Another workaround is to type hint and split on multiple lines
a: np.ndarray = np.array([[1, 2], [3, 4]])
a.mean()

I saw the caveats in the docs:

Only simple return type hints that consist of a single, possibly optional type are tracked through call and attribute access chains.

I'm not sure I totally understand the caveats w/o examples :), but if chained links are possible I think it'd be useful as a lot of code in numpy, pandas, and xarray among others often use chained syntax.

[felix-hilden]

Yes! We actually have an example of that in the documentation. The caveat is just that we don't consider true type unions because I didn't want to start guessing, and that we don't support tuple unpacking and such in our type resolver. But #132 is open though and could make things better 😄

As long as np.array returns the correct (single) type that has "mean" it all works 👌 I haven't checked the specifics though for all the numpy stack.

[scottyhq]

Yeah, I felt that it should work, but I haven't had luck. I put up an example on github pages here https://scottyhq.github.io/codeautolink/intro.html .

The build log includes

WARNING: Could not resolve mean on line 3 using path numpy.array().mean.
Unable to follow return annotation of numpy.array.`

But it returns an numpy.ndarray type that does have the mean method, so I'm guessing there is some issue with following the source code structure

In [1]: import numpy as np

In [2]: test = np.array([[1, 2], [3, 4]])

In [3]:  type(test)
Out[3]: numpy.ndarray

In [4]: test.mean?
Docstring:
a.mean(axis=None, dtype=None, out=None, keepdims=False, *, where=True)

Returns the average of the array elements along given axis.

Refer to `numpy.mean` for full documentation.

See Also
--------
numpy.mean : equivalent function
Type:      builtin_function_or_method

[felix-hilden]

I had a quick look, and np.array seems to be missing type annotations. I couldn't find it in the source with a quick search but

import numpy as np
assert "__annotations__" not in dir(np.array)

reveals that. Now, it may be that I've missed the memo on some part of the type hint machinery but at least this is what we currently support. We don't run code to resolve types 👍

[scottyhq]

Thanks for checking @felix-hilden ! Taking a step back I think I have a much simpler example to work with, which will avoid some of the potential complexities with larger libraries, but still illustrates the functionality I'm trying to achieve.

I've slightly modified the docs example to capture chaining methods on a class that returns a new or modified instance:

    def heal(self) -> Self:
        """creates a fresh Knight :)"""
        return Knight()

# how to link taunt() here since heal() returns a Knight?
print(knight.heal().taunt())

master...scottyhq:sphinx-codeautolink:chaining

[felix-hilden]

Oh that'd be a good feature to have, I've added #147, contributions very welcome if you're interested!