autodoc: Respect type annotations in `new`, `metacls.call`, and builtin types #7384

eric-wieser · 2020-03-26T15:33:06Z

Feature or Bugfix

Bugfix

Purpose

None of the following work correctly before this patch

Signatures defined by __new__
Signatures defined by metaclasses
Signatures defined by builtin base classes

Patch includes a test showing that these now all work.

It's possible other tests will have been affected, will update if needed.

Ping @tk0miya, since you recently looked at annotation stuff.

eric-wieser · 2020-03-26T16:27:12Z

Failures are all of the form

E         -  '.. py:class:: DocstringSig()',
E         ?                             --
E         +  '.. py:class:: DocstringSig',

I think this change is correct - with it, these two classes are now documented identically:

class WithInit:
    def __init__(self):
        pass
class WithoutInit:
    pass

Whereas previously the former would have () but the latter would not.

The two classes give exactly the same result from inspect.signature, so I would consider this a bug.
I've added a second commit to fix this.

sphinx/ext/autodoc/__init__.py

tests/test_ext_autodoc_configs.py

tests/test_autodoc.py

tk0miya · 2020-03-28T06:30:30Z

Should we also modify get_doc() to obtain docstring in order of this sequence?

eric-wieser · 2020-03-30T11:23:19Z

Should we also modify get_doc() to obtain docstring in order of this sequence?

We could, but I don't think that matters so much, and would prefer not to do it in this PR.

eric-wieser · 2020-03-30T12:14:34Z

Comments addressed I think

tests/test_util_inspect.py

sphinx/ext/autodoc/__init__.py

tk0miya

Sorry for late. Let's go forward this.

sphinx/ext/autodoc/__init__.py

tk0miya

LGTM

sphinx/ext/autodoc/__init__.py

eric-wieser · 2020-05-03T11:17:17Z

Needs a rebase to pass tests it seems

eric-wieser · 2020-05-03T13:29:04Z

Rebased, hopefully CI will give me some hints this time.

sphinx/ext/autodoc/__init__.py

eric-wieser · 2020-05-07T11:03:06Z

CI looks like it will pass now.

tk0miya

LGTM with nits.

sphinx/ext/autodoc/__init__.py

tk0miya · 2020-05-07T17:06:46Z

sphinx/ext/autodoc/__init__.py

+                        pass
+
+                # retry without arguments for old documenters
+                args = self.format_args()


It seems format_args() is called twice.

I take it back, you're correct. Updated in my latest push.

eric-wieser · 2020-05-07T17:08:34Z

sphinx/ext/autodoc/__init__.py

-                try:
-                    args = self.format_args(**kwargs)
-                except TypeError:
-                    # retry without arguments for old documenters
-                    args = self.format_args()
+                if kwargs:
+                    try:
+                        args = self.format_args(**kwargs)
+                    except TypeError:
+                        # avoid chaining tracebacks, by putting nothing here
+                        pass
+
+                # retry without arguments for old documenters
+                args = self.format_args()


It was called twice before too - this way, we at least:

Do not call it twice with identical arguments

Do not chain the exception of the first call with the exception of the second

Does anything actually pass non-empty kwargs?

It was called twice before too

It's an unexpected result. The TypeError handler is added only for old Documener classes which does not accept keyword arguments. It implicitly expects format_args() method does not raise TypeError.

In this case, I think no reason to raise TypeError on format_args(). It should be handled inside it.

Does anything actually pass non-empty kwargs?

Yes. The autosummary extension gives keyword argument.

sphinx/sphinx/ext/autosummary/__init__.py

Line 345 in 62711bc

sig = documenter.format_signature(show_annotation=False)

Note: It's after 2 AM in Japan. So this is my last comment today. Good night!

eric-wieser · 2020-05-27T19:40:04Z

@tk0miya: Think you'll have time to look at this again before 3.1.0?

This fixes: * Signatures defined by __new__ * Signatures defined by metaclasses * Signatures defined by builtin base classes All of these changes bring the sphinx docs inline with the behavior of `inspect.signature`. Note that this changes autodoc to output `.. py:class: MyClass()` with parentheses even if no user-defined __init__ is present. This is quite deliberate, as if no user-defined `__init__` is present the default is `object.__init__`, which indeed does not take arguments.

tk0miya · 2020-05-28T16:53:13Z

Of course, Yes. But my request is not changed. Please catch a TypeError in format_args(). Then I'll merge this soon.

eric-wieser · 2020-05-28T17:00:18Z

Please catch a TypeError in format_args(). Then I'll merge this soon.

Would you mind adding a comment on the relevant lines? I've moved things around a bit now.

tk0miya

LGTM! Thank you for your patience and cooperation!

eric-wieser · 2020-05-29T14:17:04Z

I assume now #7613 and your todo comment from #3610 will be marginally easier.

tk0miya · 2020-05-29T14:38:37Z

Yes, I can improve #7716 now. I'm waiting for merging this :-)

eric-wieser force-pushed the property-annotation branch from cc3d7cd to 4a6b701 Compare March 26, 2020 16:18

eric-wieser changed the title ~~Add extended tests for type annotations.~~ Respect type annotations in __new__, metacls.__call__, and builtin types Mar 26, 2020

eric-wieser mentioned this pull request Mar 26, 2020

Split MultiVector.__init__ into three factory methods pygae/clifford#292

Draft

eric-wieser force-pushed the property-annotation branch 3 times, most recently from b73b2c1 to 92f6567 Compare March 26, 2020 17:18

eric-wieser commented Mar 26, 2020

View reviewed changes

sphinx/ext/autodoc/__init__.py Outdated Show resolved Hide resolved

eric-wieser force-pushed the property-annotation branch 2 times, most recently from fa12fb0 to b64a955 Compare March 26, 2020 17:38

eric-wieser changed the title ~~Respect type annotations in __new__, metacls.__call__, and builtin types~~ autodoc: Respect type annotations in __new__, metacls.__call__, and builtin types Mar 26, 2020

This was referenced Mar 27, 2020

autodoc does not render correct signatures for built-in functions #7362

Closed

Close #2755: autodoc: Support type_comment style annotation #6984

Merged

tk0miya reviewed Mar 28, 2020

View reviewed changes

eric-wieser force-pushed the property-annotation branch from b64a955 to 24cefc2 Compare March 30, 2020 12:12

tk0miya reviewed Apr 12, 2020

View reviewed changes

tests/test_util_inspect.py Show resolved Hide resolved

sphinx/ext/autodoc/__init__.py Outdated Show resolved Hide resolved

tk0miya requested changes Apr 12, 2020

View reviewed changes

eric-wieser commented Apr 12, 2020

View reviewed changes

sphinx/ext/autodoc/__init__.py Show resolved Hide resolved

tk0miya approved these changes May 3, 2020

View reviewed changes

sphinx/ext/autodoc/__init__.py Show resolved Hide resolved

eric-wieser changed the base branch from 3.0.x to 3.x May 3, 2020 11:18

eric-wieser force-pushed the property-annotation branch 2 times, most recently from 529ef19 to 50c3f3e Compare May 3, 2020 11:35

eric-wieser mentioned this pull request May 3, 2020

autodoc: Show full traceback and exception type in warnings #7601

Merged

eric-wieser force-pushed the property-annotation branch from 50c3f3e to 779acfe Compare May 3, 2020 13:28

eric-wieser force-pushed the property-annotation branch from 779acfe to 9adc963 Compare May 3, 2020 13:49

tk0miya reviewed May 6, 2020

View reviewed changes

sphinx/ext/autodoc/__init__.py Outdated Show resolved Hide resolved

eric-wieser force-pushed the property-annotation branch 2 times, most recently from 6e67041 to f3a9203 Compare May 7, 2020 10:55

tk0miya reviewed May 7, 2020

View reviewed changes

sphinx/ext/autodoc/__init__.py Outdated Show resolved Hide resolved

sphinx/ext/autodoc/__init__.py Outdated Show resolved Hide resolved

tk0miya reviewed May 7, 2020

View reviewed changes

eric-wieser commented May 7, 2020

View reviewed changes

tk0miya mentioned this pull request May 10, 2020

Sphinx not respecting __signature__ #7613

Closed

eric-wieser force-pushed the property-annotation branch 2 times, most recently from 790e6da to b881a28 Compare May 27, 2020 19:38

eric-wieser force-pushed the property-annotation branch from b881a28 to 0c33bb3 Compare May 28, 2020 07:11

eric-wieser force-pushed the property-annotation branch from 0c33bb3 to 4c0e0af Compare May 28, 2020 07:38

Refactor to simplify format_args, catch TypeError

d558417

eric-wieser force-pushed the property-annotation branch from 4c0e0af to d558417 Compare May 28, 2020 17:28

tk0miya added extensions:autodoc type:proposal a feature suggestion labels May 29, 2020

tk0miya added this to the 3.1.0 milestone May 29, 2020

tk0miya approved these changes May 29, 2020

View reviewed changes

tk0miya merged commit 19ad8a4 into sphinx-doc:3.x May 29, 2020

tk0miya added a commit that referenced this pull request May 29, 2020

Update CHANGES for PR #7384

7b414d0

github-actions bot locked as resolved and limited conversation to collaborators Jul 28, 2021

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

autodoc: Respect type annotations in `new`, `metacls.call`, and builtin types #7384

autodoc: Respect type annotations in `new`, `metacls.call`, and builtin types #7384

eric-wieser commented Mar 26, 2020 •

edited

eric-wieser commented Mar 26, 2020 •

edited

tk0miya commented Mar 28, 2020

eric-wieser commented Mar 30, 2020

eric-wieser commented Mar 30, 2020

tk0miya left a comment

tk0miya left a comment

eric-wieser commented May 3, 2020

eric-wieser commented May 3, 2020

eric-wieser commented May 7, 2020

tk0miya left a comment

tk0miya May 7, 2020

eric-wieser May 27, 2020

eric-wieser May 7, 2020 •

edited

tk0miya May 7, 2020

eric-wieser commented May 27, 2020

tk0miya commented May 28, 2020

eric-wieser commented May 28, 2020

tk0miya left a comment

eric-wieser commented May 29, 2020

tk0miya commented May 29, 2020

autodoc: Respect type annotations in __new__, metacls.__call__, and builtin types #7384

autodoc: Respect type annotations in __new__, metacls.__call__, and builtin types #7384

Conversation

eric-wieser commented Mar 26, 2020 • edited

Feature or Bugfix

Purpose

eric-wieser commented Mar 26, 2020 • edited

tk0miya commented Mar 28, 2020

eric-wieser commented Mar 30, 2020

eric-wieser commented Mar 30, 2020

tk0miya left a comment

Choose a reason for hiding this comment

tk0miya left a comment

Choose a reason for hiding this comment

eric-wieser commented May 3, 2020

eric-wieser commented May 3, 2020

eric-wieser commented May 7, 2020

tk0miya left a comment

Choose a reason for hiding this comment

tk0miya May 7, 2020

Choose a reason for hiding this comment

eric-wieser May 27, 2020

Choose a reason for hiding this comment

eric-wieser May 7, 2020 • edited

Choose a reason for hiding this comment

tk0miya May 7, 2020

Choose a reason for hiding this comment

eric-wieser commented May 27, 2020

tk0miya commented May 28, 2020

eric-wieser commented May 28, 2020

tk0miya left a comment

Choose a reason for hiding this comment

eric-wieser commented May 29, 2020

tk0miya commented May 29, 2020

autodoc: Respect type annotations in `new`, `metacls.call`, and builtin types #7384

autodoc: Respect type annotations in `new`, `metacls.call`, and builtin types #7384

eric-wieser commented Mar 26, 2020 •

edited

eric-wieser commented Mar 26, 2020 •

edited

eric-wieser May 7, 2020 •

edited