Incorrect documentation for type aliases for `Callable`

[Carsten-Leue]

I have the following code using a type alias (https://docs.python.org/3/library/typing.html#type-aliases):

from typing import Callable
MyType = Callable[[str], str]
"""My function type"""

Expected Behavior

I would expect to see the documentation of MyType as a type alias, including the provided doc string

Actual Behavior

• the documentation shows the type as a class
• shows the name of the type as Callable instead of MyType
• shows the inherited documentation from Callable instead of the provided docstring

Refer to https://carsten-leue.github.io/pdoc-test/pdoc_test/#pdoc_test.Callable for an example

Steps to Reproduce

Refer to this example: https://github.com/Carsten-Leue/pdoc-test/blob/master/pdoc_test/init.py#L13

Additional info

• pdoc version: 0.8.3

[kernc]

On pdoc3 0.8.4, Python 3.7, I can't seem to reproduce above-described behavior: :thinking:

# foo.py:

from typing import Callable
MyType = Callable[[str], str]
"""My function type"""

import pdoc
mod = pdoc.Module(__name__)
print('Module contains:', mod.doc)

$ pdoc foo.py

Module contains: {'MyType': <Variable 'foo.MyType'>}

Module foo
==========

Variables
---------

`MyType`
:   My function type

[Carsten-Leue]

Thanks for having a look. Indeed there is a difference between the output for 3.6 and 3.7+.

I generated my sample for 3.6, 3.7 and 3.8 for testing (https://github.com/Carsten-Leue/pdoc-test/blob/master/doc3.6/pdoc_test/index.html, https://github.com/Carsten-Leue/pdoc-test/blob/master/doc3.7/pdoc_test/index.html and https://github.com/Carsten-Leue/pdoc-test/blob/master/doc3.8/pdoc_test/index.html)

There is no difference between the doc generated for 3.7 and 3.8, but there is one between 3.6 and 3.7. The documentation for 3.7+ shows the correct name and docstring, but it does not show any type information.

The source code is:

MyType = Callable[[str], str]
"""My function type"""

I would have expected to see the type information in the documentation. Is there any way to enable this?

Regarding the difference wrt. python versions. What versions does pdoc3 support?

[kernc]

We reasonably support Python 3.5+ while that remains viable and in major OSs supported LTS releases. :sweat_smile:

The reason type information is not shown is that MyType doesn't associate with any type hints: Callable[[str], str] is just some variable's value.

Type annotations in pdoc3 are fairly new and not so well field-tested. I guess there's still room for improvement. But with the amount of metaprogramming Python is capable of, it might not be trivial to catch all cases.

[Carsten-Leue]

The reason type information is not shown is that MyType doesn't associate with any type hints: Callable[[str], str] is just some variable's value.

True, still it's the officially documented way to define a type alias (https://docs.python.org/3/library/typing.html#type-aliases). While I agree that it's not feasible to cover the full amount of Python metaprogramming variations, it would be nice to cover the usecase that are officially covered by the python docs.

[kernc]

I wholly agree. But documenting MyType as:

var MyType

instead of:

var MyType: Callable[[str], str]

is really correct in Python terms, no?

We might document those as:

var MyType = Callable[[str], str]

for typing types, but that would make it a certain exception, and what about types types (such as types.ModuleType with no typing equivalent) etc. I fear this won't be pretty. :roll_eyes:

---

The discrepancy on Python 3.6 and below is in MyType matching the isclass() check in the following branch: https://github.com/pdoc3/pdoc/blob/04960e41b9bb598b664a50078f4c233817326170/pdoc/init.py#L622-L628

I guess this is currently a more rapidly changing part of the stdlib.

[Carsten-Leue]

I agree that var MyType: Callable[[str], str] is not the correct documentation. Type hinting is unfortunately sort of a mess in Python.

The best "guidance" I could find is this section from PEP613 (https://www.python.org/dev/peps/pep-0613/):

In PEP 484, the distinction between a valid type alias and a global variable was implicitly determined: if a top level assignment is unannotated, and the assigned value is a valid type, then the name being assigned to is a valid type alias. Otherwise, that name is simply a global value that cannot be used as a type hint.

This could be used to tell if a statement is meant to be a type or a value and document this accordingly, maybe document types as their own top level entities ...

[kernc]

Thank you, PEP 613 and TypeAlias annotation seems like the way to go. :+1:

As long as you PR it, :grin: I'm open to both:

var MyType: TypeAlias = aliased type

as well as a separate Types (akin to Variables) subsection, holding type aliases formatted thusly. :thinking:

[PasaOpasen]

Thank you, PEP 613 and TypeAlias annotation seems like the way to go. +1

As long as you PR it, grin I'm open to both:

var MyType: TypeAlias = aliased type

as well as a separate Types (akin to Variables) subsection, holding type aliases formatted thusly. thinking

Actually

But for types such as np.ndarray or pd.DataFrame it will copy a big part of its documentation!! How to disable it?