pytkdocs

pytkdocs copied to clipboard

Describe the bug When collecting type-alias attributes, pytkdocs in some cases incorrectly collects a path under the typing module. This seems to happen when the type alias is an alias to a type in the typing module, and not for example an alias for a user defined type.

To Reproduce When defining a type alias in my_module.py

from typing import Union


IntOrStr = Union[str, int]
"""
A type alias that I wish to document with mkdocstrings.
"""

running the following:

$ echo '{"objects": [{"path": "my_module.IntOrStr"}]}' | pytkdocs

Produces

{"loading_errors": [], "parsing_errors": {}, "objects": [{"name": "IntOrStr", "path": "typing.IntOrStr", "category": "attribute", "file_path": "/Users/sune/.pyenv/versions/3.7.5/lib/python3.7/typing.py", "relative_file_path": "python3.7/typing.py", "properties": [], "parent_path": "typing", "has_contents": true, "docstring": "", "docstring_sections": [], "source": {}, "children": {}, "attributes": [], "methods": [], "functions": [], "modules": [], "classes": [], "type": "None"}]}

Expected behavior Since the type-alias is just a module level attribute, I expect pytkdocs to collect the path as my_module.IntOrStr, and to collect the appropriate docstring as well in order that I can document it with mkdocstrings

Screenshots An example from a project using mkdocstrings to document a type alias of Union[...]

System (please complete the following information):

• pytkdocs 0.6.0
• Python version: 3.7
• OS: macos 10.15.4

As a work-around, you can manually set the module name on your alias:

from typing import Union


IntOrStr = Union[int, str]
IntOrStr.__module__ = __name__

Hello @suned, thank you for the detailed bug report and the workaround :slightly_smiling_face:

This behavior is indeed quite surprising. Just by looking at it, I have no idea why the module becomes typing.

I'll try to investigate later.

I'll try to investigate later.

Brilliant 😃 As far as I can tell, the __module__ attribute (which I assume is what pytkdocs uses) doesn't work the same way for type-aliases as for any other attributes. So it may not be possible to support this without special casing it 😞

As an upside, it doesn't seem like the workaround affects type-checking at all (at least not with mypy, haven't tested with other type checkers)