autodoc: The default of autodoc_typehints_format becomes to 'smart'

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: sphinx-doc#9075

CHANGES

@@ -25,6 +25,10 @@ Deprecated
 Features added
 --------------
 
+* #9075: autodoc: The default value of :confval:`autodoc_typehints_format` is
+  changed to ``'smart'``.  It will suppress the leading module names of
+  typehints (ex. ``io.StringIO`` -> ``StringIO``).
+
 Bugs fixed
 ----------
 

doc/usage/extensions/autodoc.rst

@@ -668,12 +668,15 @@ There are also config values that you can set:
    following values:
 
    * ``'fully-qualified'`` -- Show the module name and its name of typehints
-     (default)
    * ``'short'`` -- Suppress the leading module names of the typehints
-     (ex. ``io.StringIO`` -> ``StringIO``)
+     (ex. ``io.StringIO`` -> ``StringIO``)  (default)
 
    .. versionadded:: 4.4
 
+   .. versionchanged:: 5.0
+
+      The default setting was changed to ``'short'``
+
 .. confval:: autodoc_preserve_defaults
 
    If True, the default argument values of functions will be not evaluated on

sphinx/ext/autodoc/__init__.py

@@ -2850,7 +2850,7 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     app.add_config_value('autodoc_typehints_description_target', 'all', True,
                          ENUM('all', 'documented'))
     app.add_config_value('autodoc_type_aliases', {}, True)
-    app.add_config_value('autodoc_typehints_format', "fully-qualified", 'env',
+    app.add_config_value('autodoc_typehints_format', "short", 'env',
                          ENUM("fully-qualified", "short"))
     app.add_config_value('autodoc_warningiserror', True, True)
     app.add_config_value('autodoc_inherit_docstrings', True, True)

tests/test_ext_autodoc_autofunction.py

@@ -162,7 +162,7 @@ def test_wrapped_function_contextmanager(app):
     actual = do_autodoc(app, 'function', 'target.wrappedfunction.feeling_good')
     assert list(actual) == [
         '',
-        '.. py:function:: feeling_good(x: int, y: int) -> typing.Generator',
+        '.. py:function:: feeling_good(x: int, y: int) -> ~typing.Generator',
         '   :module: target.wrappedfunction',
         '',
         "   You'll feel better in this context!",

tests/test_ext_autodoc_automodule.py

@@ -130,4 +130,4 @@ def test_subclass_of_mocked_object(app):
 
     options = {'members': None}
     actual = do_autodoc(app, 'module', 'target.need_mocks', options)
-    assert '.. py:class:: Inherited(*args: typing.Any, **kwargs: typing.Any)' in actual
+    assert '.. py:class:: Inherited(*args: ~typing.Any, **kwargs: ~typing.Any)' in actual

tests/test_ext_autodoc_configs.py

@@ -612,7 +612,7 @@ def test_autodoc_typehints_signature(app):
         '   :type: int',
         '',
         '',
-        '.. py:class:: Math(s: str, o: typing.Optional[typing.Any] = None)',
+        '.. py:class:: Math(s: str, o: ~typing.Optional[~typing.Any] = None)',
         '   :module: target.typehints',
         '',
         '',
@@ -677,8 +677,8 @@ def test_autodoc_typehints_signature(app):
         '   :module: target.typehints',
         '',
         '',
-        '.. py:function:: tuple_args(x: typing.Tuple[int, typing.Union[int, str]]) '
-        '-> typing.Tuple[int, int]',
+        '.. py:function:: tuple_args(x: ~typing.Tuple[int, ~typing.Union[int, str]]) '
+        '-> ~typing.Tuple[int, int]',
         '   :module: target.typehints',
         '',
     ]
@@ -1028,7 +1028,7 @@ def test_autodoc_type_aliases(app):
         '   docstring',
         '',
         '',
-        '.. py:function:: read(r: _io.BytesIO) -> _io.StringIO',
+        '.. py:function:: read(r: ~_io.BytesIO) -> ~_io.StringIO',
         '   :module: target.autodoc_type_aliases',
         '',
         '   docstring',
@@ -1092,7 +1092,7 @@ def test_autodoc_type_aliases(app):
         '   docstring',
         '',
         '',
-        '.. py:function:: read(r: _io.BytesIO) -> my.module.StringIO',
+        '.. py:function:: read(r: ~_io.BytesIO) -> my.module.StringIO',
         '   :module: target.autodoc_type_aliases',
         '',
         '   docstring',
@@ -1144,8 +1144,8 @@ def test_autodoc_typehints_description_and_type_aliases(app):
 
 
 @pytest.mark.sphinx('html', testroot='ext-autodoc',
-                    confoverrides={'autodoc_typehints_format': "short"})
-def test_autodoc_typehints_format_short(app):
+                    confoverrides={'autodoc_typehints_format': "fully-qualified"})
+def test_autodoc_typehints_format_fully_qualified(app):
     options = {"members": None,
                "undoc-members": None}
     actual = do_autodoc(app, 'module', 'target.typehints', options)
@@ -1159,7 +1159,7 @@ def test_autodoc_typehints_format_short(app):
         '   :type: int',
         '',
         '',
-        '.. py:class:: Math(s: str, o: ~typing.Optional[~typing.Any] = None)',
+        '.. py:class:: Math(s: str, o: typing.Optional[typing.Any] = None)',
         '   :module: target.typehints',
         '',
         '',
@@ -1224,8 +1224,8 @@ def test_autodoc_typehints_format_short(app):
         '   :module: target.typehints',
         '',
         '',
-        '.. py:function:: tuple_args(x: ~typing.Tuple[int, ~typing.Union[int, str]]) '
-        '-> ~typing.Tuple[int, int]',
+        '.. py:function:: tuple_args(x: typing.Tuple[int, typing.Union[int, str]]) '
+        '-> typing.Tuple[int, int]',
         '   :module: target.typehints',
         '',
     ]

tests/test_ext_autodoc_preserve_defaults.py

@@ -36,15 +36,15 @@ def test_preserve_defaults(app):
         '   docstring',
         '',
         '',
-        '   .. py:method:: Class.meth(name: str = CONSTANT, sentinel: typing.Any = '
-        'SENTINEL, now: datetime.datetime = datetime.now(), color: int = %s) -> None' % color,
+        '   .. py:method:: Class.meth(name: str = CONSTANT, sentinel: ~typing.Any = '
+        'SENTINEL, now: ~datetime.datetime = datetime.now(), color: int = %s) -> None' % color,
         '      :module: target.preserve_defaults',
         '',
         '      docstring',
         '',
         '',
-        '.. py:function:: foo(name: str = CONSTANT, sentinel: typing.Any = SENTINEL, '
-        'now: datetime.datetime = datetime.now(), color: int = %s) -> None' % color,
+        '.. py:function:: foo(name: str = CONSTANT, sentinel: ~typing.Any = SENTINEL, '
+        'now: ~datetime.datetime = datetime.now(), color: int = %s) -> None' % color,
         '   :module: target.preserve_defaults',
         '',
         '   docstring',