The type union operator (PEP-604) causes autodoc crashed in python 3.9
or below because of the syntax is not suppoerted yet in the interpreters.
Internally, `typing.get_type_hints()` raises TypeError on evaluating the
annotation by BitOr operator for types.
To avoid the crash, this adds a fallback not to evaluate the annotations
and keep as is. As a side effect, `autodoc_type_aliases` will not work
for the modules and classes that uses type union operator for their
annotations.
As a well-known idiom, mypy recommends to use ellipsis ("...") for
default argument values as a elided style. This allows to write the
style and helps to document it with copying the default argument
values from actual implementation.
Note: This does not copy the default argument value when the argument
of overloaded function has its own default value.
The default values for overloaded functions are rendered as string
literal unexpectedly because autodoc extracts code snippets from
the source code, not actual value (ex. int, ellipsis, and so on).
This introduces a simple wrapper class; `DefaultValue` to render these
code snippets like actual values, not string literals.
autodata and autoattribute directives does not show right-hand value of
the variable if its docstring contains ``:meta hide-value:`` in
info-field-list.
The instance attributes on subclasses are shown on the document of
parent class unexpectedly because of autodoc modifies `__annotations__`
in place. This fix creates a copy of `__annotations__` attribute and
attach it to the subclass.
To avoid filtering __slots__ attributes having docstring at
filter_members(), this passes docstring captured at get_class_members()
to the filter_members() via ObjectMember.
So far, autodoc obtains type annotations of instance attributes by
ModuleAnalyzer directly. As a result, autodoc_type_aliases are ignored
for these variables.
This goes to merge type annotations from the class itself and
ModuleAnalyzer's, and get type annotations using `typing.get_type_hints()`
to apply autodoc_type_aliases.
So far, autoattribute uses "given class name" to fetch comments of
uninitialized instance attributes. But pycode expects to use "real"
class name on searching attribute comments.
This adds UninitializedInstanceAttributeMixin to handle it simply.
A custom type defined by typing.NewType was rendered as a function
because the generated type is a function having special attributes.
This renders it as a variable.
Note: The module name where the NewType object defined is lost on
generating it. So it is hard to make cross-reference for these custom
types.
Keep imports alphabetically sorted and their order homogeneous across
Python source files.
The isort project has more feature and is more active than the
flake8-import-order plugin.
Most issues caught were simply import ordering from the same module.
Where imports were purposefully placed out of order, tag with
isort:skip.
They are sometimes failed with python3.5 because the order of singledispatch
functions is not stable on python 3.5. This uses comparision via "in"
keyword to check the signature of singledispatch functions stably.
When documenting classes derived from typing.Generic (essentially all classes in the
typing module) the constructor signature would show an unhelpful (*args, **kwds).
typing.Generic has a __new__ method which was picked up by sphinx. With this patch it
is skipped and constructor signatures for generic classes are shown as they should.
