Display Union[a, b] as a | b (PEP 604) (#22)

Author: flying-sheep

scanpydoc/elegant_typehints/__init__.py

@@ -56,6 +56,7 @@ def x() -> Tuple[int, float]:
 from sphinx.ext.autodoc import ClassDocumenter
 
 from .. import _setup_sig, metadata
+from .example import example_func
 
 
 HERE = Path(__file__).parent.resolve()
@@ -82,6 +83,9 @@ def _init_vars(app: Sphinx, config: Config):
     config.html_static_path.append(str(HERE / "static"))
 
 
+example_func.__module__ = "scanpydoc.elegant_typehints"  # Make it show up here
+
+
 @_setup_sig
 def setup(app: Sphinx) -> Dict[str, Any]:
     """Patches :mod:`sphinx_autodoc_typehints` for a more elegant display."""

scanpydoc/elegant_typehints/example.py

@@ -0,0 +1,15 @@
+from typing import Dict, Union, Optional
+
+
+def example_func(a: Optional[str], b: Union[str, int, None] = None) -> Dict[str, int]:
+    """Example function
+
+    Hover over the paramter and return type annotations to see the long versions.
+
+    Args:
+        a: An example parameter
+        b: Another, with a default
+    Returns:
+        An example return value
+    """
+    pass

scanpydoc/elegant_typehints/formatting.py

@@ -49,11 +49,11 @@ def _format_terse(annotation: Type[Any], fully_qualified: bool = False) -> str:
     tilde = "" if fully_qualified else "~"
     fmt = partial(_format_terse, fully_qualified=fully_qualified)
 
-    # display `Union[A, B]` as `A, B`
+    # display `Union[A, B]` as `A | B`
     if origin is Union:
         # Never use the `Optional` keyword in the displayed docs.
-        # Use the more verbose `, None` instead, like other numerical packages.
-        return ", ".join(map(fmt, args))
+        # Use `| None` instead, similar to other large numerical packages.
+        return " | ".join(map(fmt, args))
 
     # do not show the arguments of Mapping
     if origin is cabc.Mapping:

tests/test_elegant_typehints.py

@@ -181,7 +181,7 @@ def test_qualname_overrides_exception(app, _testmod):
 
 def test_qualname_overrides_recursive(app, _testmod):
     assert _format_terse(t.Union[_testmod.Class, str]) == (
-        r":py:class:`~test.Class`, :py:class:`str`"
+        r":py:class:`~test.Class` | :py:class:`str`"
     )
     assert _format_full(t.Union[_testmod.Class, str]) == (
         r":py:data:`~typing.Union`\["
@@ -193,7 +193,7 @@ def test_qualname_overrides_recursive(app, _testmod):
 
 def test_fully_qualified(app, _testmod):
     assert _format_terse(t.Union[_testmod.Class, str], True) == (
-        r":py:class:`test.Class`, :py:class:`str`"
+        r":py:class:`test.Class` | :py:class:`str`"
     )
     assert _format_full(t.Union[_testmod.Class, str], True) == (
         r":py:data:`typing.Union`\[" r":py:class:`test.Class`, " r":py:class:`str`" r"]"