autodoc raises an exception if a Python class inherits from io.BufferedReader

[ralhei]

Describe the bug
sphinx.ext.autodoc raises an exception if a Python class inherits from io.BufferedReader. Same with io.BufferedWriter. No problem with io.BytesIO or others.

To Reproduce
Steps to reproduce the behavior:

$ pip install sphinx  # obtained version 3.4.3
$ sphinx-quickstart

... answer the questions about version, author,...

Add extensions = ['sphinx.ext.autodoc'] to source/conf.py
Add into index.rst:

.. automodule:: bufferedreader
     :members:

The create a small python module:

$cat > source/bufferedreader.py <<EOF
import io

class MyBufferedReader(io.BufferedReader): 
    """buffer reader class."""

and finally export PYTHONPATH=<path/to/sphinx/source-dir>

Running sphinx-build -E -n -v -b html . ../build from inside the source directory produces the following ouput

WARNING: error while formatting arguments for bufferedreader.MyBufferedReader:
WARNING: error while formatting signature for bufferedreader.MyBufferedReader: Handler <function record_typehints at 0x7f0d3e2c8f28> for event 'autodoc-process-signature' threw an exception (exception: )

Due to this bug the documentation for class MyBufferedReader is not contained in the HTML.

Environment info

• OS: suse sles 15.1
• Python version: 3.7.1
• Sphinx version: 3.4.3
• Sphinx extensions: sphinx.ext.autodoc

Additional Note
There is no problem for old sphinx 1.8.2 with this issue.

[tk0miya]

inspect.signature() raises RuntimeError for your class. I think this is a bug of python itself.

$ python
Python 3.9.1 (default, Dec 12 2020, 22:52:49)
[Clang 11.0.3 (clang-1103.0.32.62)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import inspect
>>> import bufferedreader
>>> inspect.signature(bufferedreader.MyBufferedReader)
Traceback (most recent call last):
  File "/Users/tkomiya/.pyenv/versions/3.9.1/lib/python3.9/inspect.py", line 2042, in wrap_value
    value = eval(s, module_dict)
  File "<string>", line 1, in <module>
NameError: name 'DEFAULT_BUFFER_SIZE' is not defined

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/Users/tkomiya/.pyenv/versions/3.9.1/lib/python3.9/inspect.py", line 2045, in wrap_value
    value = eval(s, sys_module_dict)
  File "<string>", line 1, in <module>
NameError: name 'DEFAULT_BUFFER_SIZE' is not defined

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/Users/tkomiya/.pyenv/versions/3.9.1/lib/python3.9/inspect.py", line 3130, in signature
    return Signature.from_callable(obj, follow_wrapped=follow_wrapped)
  File "/Users/tkomiya/.pyenv/versions/3.9.1/lib/python3.9/inspect.py", line 2879, in from_callable
    return _signature_from_callable(obj, sigcls=cls,
  File "/Users/tkomiya/.pyenv/versions/3.9.1/lib/python3.9/inspect.py", line 2397, in _signature_from_callable
    return _signature_fromstr(sigcls, obj, text_sig)
  File "/Users/tkomiya/.pyenv/versions/3.9.1/lib/python3.9/inspect.py", line 2095, in _signature_fromstr
    p(name, default)
  File "/Users/tkomiya/.pyenv/versions/3.9.1/lib/python3.9/inspect.py", line 2077, in p
    default_node = RewriteSymbolics().visit(default_node)
  File "/Users/tkomiya/.pyenv/versions/3.9.1/lib/python3.9/ast.py", line 407, in visit
    return visitor(node)
  File "/Users/tkomiya/.pyenv/versions/3.9.1/lib/python3.9/inspect.py", line 2069, in visit_Name
    return wrap_value(node.id)
  File "/Users/tkomiya/.pyenv/versions/3.9.1/lib/python3.9/inspect.py", line 2047, in wrap_value
    raise RuntimeError()
RuntimeError
>>>

[tk0miya]

It seems inspect.signature() tries to evaluate the default argument of bufferedreader.MyBufferedReader and failed to do it on DEFAULT_BUFFER_SIZE. As a workaround, you can avoid the error by importing io.DEFAULT_BUFFER_SIZE on your module:

from io import DEFAULT_BUFFER_SIZE

[tk0miya]

Note: I posted the issue to the bugs.python.org: https://bugs.python.org/issue43118

[ralhei]

Cool, thanks for taking care of this. And for the bug report on python.org

[picnixz]

Closing as it is fixed in 3.9 (python/cpython#87284 (comment)), which is now the Python minimal version for Sphinx.