search

pdoc3 / pdoc

:snake: :arrow_right: :scroll: Auto-generate API documentation for Python projects
https://pdoc3.github.io/pdoc/
GNU Affero General Public License v3.0
1.12k stars 145 forks source link

Optional[Type] is shown as Union[Type, NoneType] #324

Closed hhoppe closed 3 years ago

hhoppe commented 3 years ago

In the doc I maintain, https://google.github.io/mediapy/, the functions have many typing attributes. These generally look great in the pdoc3 output, except that Optional[Type] is replaced by the more confusing Union[Type, NoneType]. Perhaps it would be possible to recognize this pattern and somehow change it back?

hhoppe commented 3 years ago

Also, the return type -> None is shown using the lengthier -> NoneType.

kernc commented 3 years ago

except that Optional[Type] is replaced by the more confusing Union[Type, NoneType]

I'm afraid that's what the values are resolved as by typing internals:

>>> import typing
>>> def foo() -> typing.Optional[int]: pass
>>> typing.get_type_hints(foo)
{'return': typing.Union[int, NoneType]}

If you can think of a good matching/replacement scheme, this would be the place to override it: https://github.com/pdoc3/pdoc/blob/aef1917a668ca9f3cd26373d1d69bcb5001108cc/pdoc/__init__.py#L1243-L1258

hhoppe commented 3 years ago

Thanks for the pointers. Handling the general case looks difficult. It seems that inspect uses repr to create a string from an annotation, which can be arbitrarily nested. One could try to recognize the pattern(s) in the resulting string, but that would require a parser rather than a regular expression.