Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

autodoc uses a wrapper's signature for a decorated class #8105

Closed
harupy opened this issue Aug 12, 2020 · 7 comments
Closed

autodoc uses a wrapper's signature for a decorated class #8105

harupy opened this issue Aug 12, 2020 · 7 comments

Comments

@harupy
Copy link
Contributor

harupy commented Aug 12, 2020

Describe the bug

autodoc uses a wrapper's signature for a decorated class.

To Reproduce

Branch: https://github.com/harupy/sphinx/tree/decorated-class

Steps to reproduce the behavior:

In tests/roots/test-ext-autodoc/target/decorator.py, add:.

def deco(cls):
    _original_init = cls.__init__

    @wraps(_original_init)
    def wrapped(self, *args, **kwargs):
        _original_init(self, *args, **kwargs)

    cls.__init__ = wrapped
    return cls

@deco
class Bar2:
    def __init__(self, name=None, age=None):
        pass

In tests/test_ext_autodoc.py, add:

@pytest.mark.sphinx('html', testroot='ext-autodoc')
def test_decorated_class(app):
    print(do_autodoc(app, 'class', 'target.decorator.Bar2'))
    raise Exception  # fails this test to see stdout

Then, run:

tox -e py37 tests/test_ext_autodoc.py::test_decorated_class

This outputs:

--- Captured stdout call ---
['', '.. py:class:: Bar2(*args, **kwargs)', '   :module: target.decorator', '']

Expected behavior
A clear and concise description of what you expected to happen.

--- Captured stdout call ---
['', '.. py:class:: Bar2(self, name=None, age=None)', '   :module: target.decorator', '']

Your project
Link to your sphinx project, or attach zipped small project sample.

Screenshots
If applicable, add screenshots to help explain your problem.

Environment info

  • OS: [e.g. Unix/Linux/Mac/Win/other with version]
  • Python version: [e.g. 3.7.1]
  • Sphinx version: [e.g. 1.8.2]
  • Sphinx extensions: [e.g. sphinx.ext.autodoc, recommonmark]
  • Extra tools: [e.g. Browser, tex or something else]

Additional context
Add any other context about the problem here.

  • [e.g. URL or Ticket]
@harupy
Copy link
Contributor Author

harupy commented Aug 12, 2020

ClassDocumenter doesn't seem to set follow_wrapped to True when extracting a signature.

sig = inspect.signature(init, bound_method=True)

@harupy
Copy link
Contributor Author

harupy commented Aug 12, 2020

The same thing occurs here:

type_sig = get_type_comment(obj, bound_method)
if type_sig:
sig = inspect.signature(obj, bound_method)

This causes type_sig and sig to have different parameters and throw KeyError here:

annotation = type_sig.parameters[param.name].annotation

@harupy
Copy link
Contributor Author

harupy commented Aug 13, 2020

@tk0miya Correct me if I'm wrong. It looks like just specifying follow_wrapped=True solves the issue. If so, I'd be happy to open a PR (that makes the change and adds some tests to verify it).

@tk0miya
Copy link
Member

tk0miya commented Aug 13, 2020

@harupy You're right! Could you make a PR, please? Additionally, cases of __call__ and __new__ are also needed to add follow_wrapped=True, I think. Could you check them too if possible?

@harupy
Copy link
Contributor Author

harupy commented Aug 13, 2020

@tk0miya Created a PR: #8115 😄

@untitaker
Copy link

This issue prevents me from upgrading from 3.0 to 3.2.1, the bugfix by @harupy works perfectly.

@harupy
Copy link
Contributor Author

harupy commented Sep 6, 2020

@tk0miya Could you review #8115?

@tk0miya tk0miya modified the milestones: 3.3.0, 3.4.0 Nov 1, 2020
tk0miya added a commit to tk0miya/sphinx that referenced this issue Nov 3, 2020
…orrect

In sphinx-doc#7651, autodoc stops to undecorate the functions on getting the
signature from the callables.  But some kinds of decorators conceals
the correct signature because they pass through their arguments via
`(*args, **kwargs)`.

This restarts to undecorate the functions again as before sphinx-doc#7651.
@tk0miya tk0miya closed this as completed in 6d05b1a Nov 8, 2020
tk0miya added a commit that referenced this issue Nov 8, 2020
Fix #8105: autodoc: the signature of decorated class is incorrect
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Jul 18, 2021
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants