Added the simplify_optional_unions config option (#141)

Author: tillhainbach

README.rst

@@ -65,7 +65,13 @@ The following configuration options are accepted:
   be able to add type info.
 * ``typehints_document_rtype`` (default: ``True``): If ``False``, never add an ``:rtype:`` directive.
   If ``True``, add the ``:rtype:`` directive if no existing ``:rtype:`` is found.
-
+* ``simplify_optional_unions`` (default: ``True``): If ``True``, optional parameters of type "Union[...]"
+  are simplified as being of type Union[..., None] in the resulting documention
+  (e.g. Optional[Union[A, B]] -> Union[A, B, None]).
+  If ``False``, the "Optional"-type is kept.
+  Note: If ``False``, **any** Union containing ``None`` will be displayed as Optional!
+  Note: If an optional parameter has only a single type (e.g Optional[A] or Union[A, None]),
+  it will **always** be displayed as Optional!
 
 How it works
 ------------

sphinx_autodoc_typehints.py

@@ -95,7 +95,9 @@ def get_annotation_args(annotation, module: str, class_name: str) -> Tuple:
     return getattr(annotation, '__args__', ())
 
 
-def format_annotation(annotation, fully_qualified: bool = False) -> str:
+def format_annotation(annotation,
+                      fully_qualified: bool = False,
+                      simplify_optional_unions: bool = True) -> str:
     # Special cases
     if annotation is None or annotation is type(None):  # noqa: E721
         return ':py:obj:`None`'
@@ -130,18 +132,28 @@ def format_annotation(annotation, fully_qualified: bool = False) -> str:
     if full_name == 'typing.NewType':
         args_format = '\\(:py:data:`~{name}`, {{}})'.format(name=annotation.__name__)
         role = 'func'
-    elif full_name == 'typing.Union' and len(args) == 2 and type(None) in args:
-        full_name = 'typing.Optional'
-        args = tuple(x for x in args if x is not type(None))  # noqa: E721
+    elif full_name == 'typing.Union' and type(None) in args:
+        if len(args) == 2:
+            full_name = 'typing.Optional'
+            args = tuple(x for x in args if x is not type(None))  # noqa: E721
+        elif not simplify_optional_unions:
+            full_name = 'typing.Optional'
+            args_format = '\\[:py:data:`{prefix}typing.Union`\\[{{}}]]'.format(prefix=prefix)
+            args = tuple(x for x in args if x is not type(None))  # noqa: E721
     elif full_name == 'typing.Callable' and args and args[0] is not ...:
-        formatted_args = '\\[\\[' + ', '.join(format_annotation(arg) for arg in args[:-1]) + ']'
-        formatted_args += ', ' + format_annotation(args[-1]) + ']'
+        formatted_args = '\\[\\[' + ', '.join(
+            format_annotation(
+                arg, simplify_optional_unions=simplify_optional_unions)
+            for arg in args[:-1]) + ']'
+        formatted_args += ', ' + format_annotation(
+            args[-1], simplify_optional_unions=simplify_optional_unions) + ']'
     elif full_name == 'typing.Literal':
         formatted_args = '\\[' + ', '.join(repr(arg) for arg in args) + ']'
 
     if args and not formatted_args:
-        formatted_args = args_format.format(', '.join(format_annotation(arg, fully_qualified)
-                                                      for arg in args))
+        formatted_args = args_format.format(', '.join(
+            format_annotation(arg, fully_qualified, simplify_optional_unions)
+            for arg in args))
 
     return ':py:{role}:`{prefix}{full_name}`{formatted_args}'.format(
         role=role, prefix=prefix, full_name=full_name, formatted_args=formatted_args)
@@ -382,7 +394,9 @@ def process_docstring(app, what, name, obj, options, lines):
                 argname = '{}\\_'.format(argname[:-1])
 
             formatted_annotation = format_annotation(
-                annotation, fully_qualified=app.config.typehints_fully_qualified)
+                annotation,
+                fully_qualified=app.config.typehints_fully_qualified,
+                simplify_optional_unions=app.config.simplify_optional_unions)
 
             searchfor = [':{} {}:'.format(field, argname)
                          for field in ('param', 'parameter', 'arg', 'argument')]
@@ -409,7 +423,9 @@ def process_docstring(app, what, name, obj, options, lines):
                 return
 
             formatted_annotation = format_annotation(
-                type_hints['return'], fully_qualified=app.config.typehints_fully_qualified)
+                type_hints['return'], fully_qualified=app.config.typehints_fully_qualified,
+                simplify_optional_unions=app.config.simplify_optional_unions
+                )
 
             insert_index = len(lines)
             for i, line in enumerate(lines):
@@ -439,6 +455,7 @@ def setup(app):
     app.add_config_value('always_document_param_types', False, 'html')
     app.add_config_value('typehints_fully_qualified', False, 'env')
     app.add_config_value('typehints_document_rtype', True, 'env')
+    app.add_config_value('simplify_optional_unions', True, 'env')
     app.connect('builder-inited', builder_ready)
     app.connect('autodoc-process-signature', process_signature)
     app.connect('autodoc-process-docstring', process_docstring)

tests/test_sphinx_autodoc_typehints.py

@@ -126,11 +126,15 @@ def test_parse_annotation(annotation, module, class_name, args):
     (Union,                         ':py:data:`~typing.Union`'),
     (Union[str, bool],              ':py:data:`~typing.Union`\\[:py:class:`str`, '
                                     ':py:class:`bool`]'),
+    (Union[str, bool, None],        ':py:data:`~typing.Union`\\[:py:class:`str`, '
+                                    ':py:class:`bool`, ``None``]'),
     pytest.param(Union[str, Any],   ':py:data:`~typing.Union`\\[:py:class:`str`, '
                                     ':py:data:`~typing.Any`]',
                  marks=pytest.mark.skipif((3, 5, 0) <= sys.version_info[:3] <= (3, 5, 2),
                                           reason='Union erases the str on 3.5.0 -> 3.5.2')),
     (Optional[str],                 ':py:data:`~typing.Optional`\\[:py:class:`str`]'),
+    (Optional[Union[str, bool]],    ':py:data:`~typing.Union`\\[:py:class:`str`, '
+                                    ':py:class:`bool`, ``None``]'),
     (Callable,                      ':py:data:`~typing.Callable`'),
     (Callable[..., int],            ':py:data:`~typing.Callable`\\[..., :py:class:`int`]'),
     (Callable[[int], int],          ':py:data:`~typing.Callable`\\[\\[:py:class:`int`], '
@@ -158,6 +162,27 @@ def test_format_annotation(inv, annotation, expected_result):
     result = format_annotation(annotation)
     assert result == expected_result
 
+    # Test with the "simplify_optional_unions" flag turned off:
+    if re.match(r'^:py:data:`~typing\.Union`\\\[.*``None``.*\]', expected_result):
+        # strip None - argument and copy string to avoid conflicts with
+        # subsequent tests
+        expected_result_not_simplified = expected_result.replace(', ``None``', '')
+        # encapsulate Union in typing.Optional
+        expected_result_not_simplified = ':py:data:`~typing.Optional`\\[' + \
+            expected_result_not_simplified
+        expected_result_not_simplified += ']'
+        assert format_annotation(annotation, simplify_optional_unions=False) == \
+            expected_result_not_simplified
+
+        # Test with the "fully_qualified" flag turned on
+        if 'typing' in expected_result_not_simplified:
+            expected_result_not_simplified = expected_result_not_simplified.replace('~typing',
+                                                                                    'typing')
+            assert format_annotation(annotation,
+                                     fully_qualified=True,
+                                     simplify_optional_unions=False) == \
+                expected_result_not_simplified
+
     # Test with the "fully_qualified" flag turned on
     if 'typing' in expected_result or __name__ in expected_result:
         expected_result = expected_result.replace('~typing', 'typing')