Basically, autodoc suppresses return value typehint for class
constructors. But it was unexpectedly shown if
`autodoc_docstring_signature` is enabled and docstring has multiple
signatures.
Since python-3.11, `typing.get_type_hints()` will not add Optional[t] to
type annotations even if a default value for function argument is None.
refs: https://github.com/python/cpython/pull/30304 (bpo-46195)
The default value of autodoc_typehints_format configuration is changed
to `'smart'`. It will suppress the leading module names of typehints
(ex. `io.StringIO` -> `StringIO`).
refs: #9075
If autodoc_unqualified_typehints feature enabled, autodoc suppresses the
leading module names of typehints of function signatures (ex.
`io.StringIO` -> `StringIO`)
The `MethodDocumenter.get_doc` method added by
51ae283a38 prevents
DocstringSignatureMixin from working correctly for __init__ and
__new__ methods. Additionally, the __new__ docstring was not obtained
correctly.
This commit checks for `self._new_docstrings` being set, and also
corrects the logic for obtaining the __new__ docstring.
There still remains the issue that when the class signature is
obtained from the signature of __init__ or __new__, only the real
signature is used, due to the use of `sphinx.util.inspect.signature`;
the autodoc_docstring_signature option does not have any effect.
Add new tests to exercise the new autodoc_typehint_undoc option. Where
an existing test would have a meaningful behavior change with the new
option set to False, that test is copied, the new option is set to False
in the copy, and the assertions reflect the new expected behavior.
The new test test_autodoc_typehints_description_with_documented_init
illustrates the problem reported in #7329, and the new test
test_autodoc_typehints_description_with_documented_init_no_undoc
illustrates that this issue no longer occurs when the new
autodoc_typehint_undoc option is set to False.
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.
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.
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.
