Drop 3.6, simplify code, and add prettify terse Callable typehint (#23)

Author: flying-sheep

.readthedocs.yml

@@ -1,7 +1,12 @@
+version: 2
 build:
   image: latest
-
+sphinx:
+  configuration: docs/conf.py
 python:
-  version: 3.6
-
-requirements_file: docs/requirements.txt
+  version: 3.8
+  install:
+  - method: pip
+    path: .
+    extra_requirements:
+    - doc

.travis.yml

@@ -5,13 +5,13 @@ branches:
   only:
   - master  # use PR builder only for other branches
 python:
-- '3.6'
 # Travis uses old versions if you specify 3.x,
 # and elegant_typehints trigger a Python bug in those.
 # There seems to be no way to specify the newest patch version,
 # so I’ll just use the newest available at the time of writing.
 - '3.7.9'
 - '3.8.5'
+- '3.9'
 
 install:
 - pip install flit codecov

docs/requirements.txt

@@ -1,6 +1,6 @@
 [build-system]
-requires = ['flit>=1.3']
-build-backend = 'flit.buildapi'
+requires = ['flit_core >=2,<4']
+build-backend = 'flit_core.buildapi'
 
 [tool.flit.metadata]
 module = 'scanpydoc'
@@ -17,7 +17,7 @@ classifiers = [
     'Topic :: Software Development :: Libraries :: Python Modules',
     'Framework :: Sphinx :: Extension',
 ]
-requires-python = '>=3.6'
+requires-python = '>=3.7'
 requires = [
     'sphinx>=3.0',
     'get_version',
@@ -39,12 +39,12 @@ doc = [
 scanpydoc = 'scanpydoc.theme'
 
 [tool.black]
-target-version = ['py36']
+target-version = ['py37']
 
 [tool.tox]
 legacy_tox_ini = """
 [tox]
-envlist = py36,py37,py38
+envlist = py37,py38,py39
 skipsdist = True
 
 [testenv]

pyproject.toml

@@ -1,18 +1,14 @@
 import inspect
-from collections import abc
+import collections.abc as cabc
+from functools import partial
 from typing import Any, Union  # Meta
-from typing import Type, Mapping, Sequence, Iterable  # ABC
+from typing import Type, Sequence, Iterable  # ABC
 from typing import Dict, List, Tuple  # Concrete
 
-from scanpydoc import elegant_typehints
-
-try:
-    from typing import Literal
+try:  # 3.8 additions
+    from typing import Literal, get_args, get_origin
 except ImportError:
-    try:
-        from typing_extensions import Literal
-    except ImportError:
-        Literal = object()
+    from typing_extensions import Literal, get_args, get_origin
 
 import sphinx_autodoc_typehints
 from sphinx_autodoc_typehints import format_annotation as _format_orig
@@ -22,12 +18,14 @@
 from docutils.parsers.rst.states import Inliner, Struct
 from docutils.utils import SystemMessage, unescape
 
+from scanpydoc import elegant_typehints
+
 
 def _format_full(annotation: Type[Any], fully_qualified: bool = False):
     if inspect.isclass(annotation) and annotation.__module__ == "builtins":
         return _format_orig(annotation, fully_qualified)
 
-    origin = getattr(annotation, "__origin__", None)
+    origin = get_origin(annotation)
     tilde = "" if fully_qualified else "~"
 
     annotation_cls = annotation if inspect.isclass(annotation) else type(annotation)
@@ -46,31 +44,35 @@ def _format_full(annotation: Type[Any], fully_qualified: bool = False):
 
 
 def _format_terse(annotation: Type[Any], fully_qualified: bool = False) -> str:
-    origin = getattr(annotation, "__origin__", None)
+    origin = get_origin(annotation)
+    args = get_args(annotation)
+    tilde = "" if fully_qualified else "~"
+    fmt = partial(_format_terse, fully_qualified=fully_qualified)
 
-    union_params = getattr(annotation, "__union_params__", None)
     # display `Union[A, B]` as `A, B`
-    if origin is Union or union_params:
-        params = union_params or getattr(annotation, "__args__", None)
+    if origin is Union:
         # Never use the `Optional` keyword in the displayed docs.
-        # Use the more verbose `, None` instead,
-        # as is the convention in the other large numerical packages
-        # if len(params or []) == 2 and getattr(params[1], '__qualname__', None) == 'NoneType':
-        #     return fa_orig(annotation)  # Optional[...]
-        return ", ".join(_format_terse(p, fully_qualified) for p in params)
+        # Use the more verbose `, None` instead, like other numerical packages.
+        return ", ".join(map(fmt, args))
 
     # do not show the arguments of Mapping
-    if origin in (abc.Mapping, Mapping):
-        return f":py:class:`{'' if fully_qualified else '~'}typing.Mapping`"
+    if origin is cabc.Mapping:
+        return f":py:class:`{tilde}typing.Mapping`"
 
     # display dict as {k: v}
-    if origin in (dict, Dict):
-        k, v = annotation.__args__
-        return f"{{{_format_terse(k, fully_qualified)}: {_format_terse(v, fully_qualified)}}}"
-
-    if origin is Literal or hasattr(annotation, "__values__"):
-        values = getattr(annotation, "__args__", ()) or annotation.__values__
-        return f"{{{', '.join(map(repr, values))}}}"
+    if origin is dict:
+        k, v = get_args(annotation)
+        return f"{{{fmt(k)}: {fmt(v)}}}"
+
+    # display Callable[[a1, a2], r] as (a1, a2) -> r
+    if origin is cabc.Callable and len(args) == 2:
+        params, ret = args
+        params = ["…"] if params is Ellipsis else map(fmt, params)
+        return f"({', '.join(params)}) → {fmt(ret)}"
+
+    # display Literal as {'a', 'b', ...}
+    if origin is Literal:
+        return f"{{{', '.join(map(repr, args))}}}"
 
     return _format_full(annotation, fully_qualified)
 

scanpydoc/elegant_typehints/formatting.py

@@ -3,6 +3,11 @@
 from logging import getLogger
 from typing import get_type_hints, Any, Union, Optional, Type, Tuple, List
 
+try:  # 3.8 additions
+    from typing import get_args, get_origin
+except ImportError:
+    from typing_extensions import get_args, get_origin
+
 from sphinx.application import Sphinx
 from sphinx.ext.autodoc import Options
 
@@ -16,17 +21,17 @@
 def get_tuple_annot(annotation: Optional[Type]) -> Optional[Tuple[Type, ...]]:
     if annotation is None:
         return None
-    origin = getattr(annotation, "__origin__", None)
+    origin = get_origin(annotation)
     if not origin:
         return None
     if origin is Union:
-        for annotation in annotation.__args__:
-            origin = getattr(annotation, "__origin__", None)
+        for annotation in get_args(annotation):
+            origin = get_origin(annotation)
             if origin in (tuple, Tuple):
                 break
         else:
             return None
-    return annotation.__args__
+    return get_args(annotation)
 
 
 def process_docstring(

scanpydoc/elegant_typehints/return_tuple.py

@@ -4,10 +4,10 @@
 import typing as t
 from pathlib import Path
 
-try:
-    from typing import Literal
+try:  # 3.8 additions
+    from typing import Literal, get_args, get_origin
 except ImportError:
-    from typing_extensions import Literal
+    from typing_extensions import Literal, get_args, get_origin
 
 import pytest
 import sphinx_autodoc_typehints as sat
@@ -148,6 +148,20 @@ def test_dict(app):
     )
 
 
+@pytest.mark.parametrize(
+    "annotation,expected",
+    [
+        (t.Callable[..., t.Any], "(…) → :py:data:`~typing.Any`"),
+        (
+            t.Callable[[str, int], None],
+            "(:py:class:`str`, :py:class:`int`) → :py:obj:`None`",
+        ),
+    ],
+)
+def test_callable_terse(app, annotation, expected):
+    assert _format_terse(annotation) == expected
+
+
 def test_literal(app):
     assert _format_terse(Literal["str", 1, None]) == "{'str', 1, None}"
     assert _format_full(Literal["str", 1, None]) == (
@@ -208,22 +222,23 @@ def test_classes_get_added(app, parse):
         t.Tuple[int, str],
         t.Tuple[float, ...],
         t.Union[int, str],
+        t.Union[int, str, None],
     ],
     ids=lambda p: str(p).replace("typing.", ""),
 )
 def test_typing_classes(app, annotation, formatter):
     name = (
         getattr(annotation, "_name", None)
         or getattr(annotation, "__name__", None)
-        or getattr(getattr(annotation, "__origin__", None), "_name", None)
+        or getattr(get_origin(annotation), "_name", None)
         # 3.6 _Any and _Union
         or annotation.__class__.__name__[1:]
     )
-    if name == "Union":
-        if formatter is _format_terse:
-            pytest.skip("Tested elsewhere")
-        elif len(annotation.__args__) == 2 and type(None) in annotation.__args__:
-            name = "Optional"
+    if formatter is _format_terse and name in {"Union", "Callable"}:
+        pytest.skip("Tested elsewhere")
+    args = get_args(annotation)
+    if name == "Union" and len(args) == 2 and type(None) in args:
+        name = "Optional"
     assert formatter(annotation, True).startswith(f":py:data:`typing.{name}")