feat: add support for TypeAliasType (#237)

Author: flying-sheep

.github/workflows/ci.yml

@@ -18,31 +18,67 @@ env:
   FORCE_COLOR: "1"
 
 jobs:
-  build:
+  get-environments:
+    runs-on: ubuntu-latest
+    outputs:
+      envs: ${{ steps.get-envs.outputs.envs }}
+    steps:
+      - uses: actions/checkout@v5
+        with: { filter: "blob:none", fetch-depth: 0 }
+      - uses: astral-sh/setup-uv@v7
+        with: { enable-cache: false }
+      - id: get-envs
+        run: |
+          ENVS_JSON=$(NO_COLOR=1 uvx hatch env show --json | jq -c 'to_entries
+            | map(
+              select(.key | startswith("hatch-test"))
+              | { name: .key, python: .value.python }
+            )')
+          echo "envs=${ENVS_JSON}" | tee $GITHUB_OUTPUT
+
+  test:
+    needs: get-environments
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.10", "3.11", "3.12"]
+        env: ${{ fromJSON(needs.get-environments.outputs.envs) }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
+        with: { fetch-depth: 0, filter: "blob:none" }
+      - uses: astral-sh/setup-uv@v7
         with:
-          fetch-depth: 0
-          filter: blob:none
-      - uses: actions/setup-python@v5
-        with:
-          python-version: ${{ matrix.python-version }}
-      - uses: hynek/setup-cached-uv@v2
-        with:
-          cache-dependency-path: pyproject.toml
-      - name: dependencies
-        # TODO: remove typer constraint after fixing https://github.com/WaylonWalker/coverage-rich/issues/4
-        run: uv pip install --system .[test,typehints,myst] coverage-rich 'typer <0.14' 'anyconfig[toml] >=0.14'
-      - name: tests
-        run: coverage run -m pytest --verbose --color=yes
-      - name: show coverage
-        run: coverage-rich report
+          python-version: ${{ matrix.env.python-version }}
+      - name: Install dependencies
+        run: |
+          uv tool install hatch
+          hatch -v env create ${{ matrix.env.name }}
+      - name: Run tests
+        run: |
+          hatch run ${{ matrix.env.name }}:run-cov -v --color=yes -n auto --junitxml=test-data/test-results.xml
+          hatch run ${{ matrix.env.name }}:cov-combine
+          hatch run ${{ matrix.env.name }}:coverage xml
       - name: upload coverage
+        if: ${{ !cancelled() }}
         uses: codecov/codecov-action@v5
         with:
+          token: c66a2830-d3c7-4ae7-a230-21aef89dcf65
+          flags: ${{ matrix.env.name }}
           fail_ci_if_error: true
+      - name: Upload test results
+        if: ${{ !cancelled() }}
+        uses: codecov/test-results-action@v1
+        with:
           token: c66a2830-d3c7-4ae7-a230-21aef89dcf65
+          flags: ${{ matrix.env.name }}
+          fail_ci_if_error: true
+
+  check:
+    if: always()
+    needs:
+      - get-environments
+      - test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: re-actors/alls-green@release/v1
+        with:
+          jobs: ${{ toJSON(needs) }}

.pre-commit-config.yaml

@@ -26,3 +26,4 @@ repos:
           - types-docutils
           - legacy-api-wrap
           - myst-parser
+          - sphinx-autodoc-typehints

docs/conf.py

@@ -5,8 +5,7 @@
 import re
 from typing import TYPE_CHECKING
 from pathlib import PurePosixPath
-from datetime import datetime
-from datetime import timezone as tz
+from datetime import UTC, datetime
 from importlib.metadata import metadata
 
 from jinja2.tests import TESTS
@@ -42,7 +41,7 @@
 meta = metadata("scanpydoc")
 project = meta["name"]
 author = meta["author-email"].split(" <")[0]
-copyright = f"{datetime.now(tz=tz.utc):%Y}, {author}."  # noqa: A001
+copyright = f"{datetime.now(tz=UTC):%Y}, {author}."  # noqa: A001
 version = release = meta["version"]
 
 master_doc = "index"

pyproject.toml

@@ -17,7 +17,7 @@ classifiers = [
     'Framework :: Sphinx :: Extension',
     'Typing :: Typed',
 ]
-requires-python = '>=3.10'
+requires-python = '>=3.12'
 dependencies = [
     'sphinx>=7.0',
 ]
@@ -94,14 +94,16 @@ version-file = 'src/scanpydoc/_version.py'
 [tool.hatch.envs.default]
 dependencies = ['types-docutils']
 [tool.hatch.envs.docs]
-python = '3.11'
+python = '3.13'
 features = ['doc']
 [tool.hatch.envs.docs.scripts]
 build = 'sphinx-build -M html docs docs/_build'
 clean = 'git clean -fdX docs'
 
 [tool.hatch.envs.hatch-test]
 features = ['test', 'typehints', 'myst']
+[[tool.hatch.envs.hatch-test.matrix]]
+python = ['3.12', '3.14']
 
 [tool.pytest.ini_options]
 addopts = [
@@ -115,8 +117,10 @@ filterwarnings = [
 
 [tool.coverage.run]
 source_pkgs = ['scanpydoc']
+concurrency = ['multiprocessing']
+patch = ['subprocess']
 [tool.coverage.paths]
-scanpydoc = ['src/scanpydoc']
+source = ['src']
 [tool.coverage.report]
 exclude_lines = [
   'no cov',

src/scanpydoc/__init__.py

@@ -5,7 +5,7 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any, TypeVar
+from typing import TYPE_CHECKING, Any
 from textwrap import indent
 from collections.abc import Callable
 
@@ -31,10 +31,8 @@
 :ref:`Metadata <sphinx:ext-metadata>` for this extension.
 """
 
-C = TypeVar("C", bound=Callable[..., Any])
 
-
-def _setup_sig(fn: C) -> C:
+def _setup_sig[C: Callable[..., Any]](fn: C) -> C:
     fn.__doc__ = f"{fn.__doc__ or ''}\n\n{indent(setup_sig_str, ' ' * 4)}"
     return fn
 

src/scanpydoc/autosummary_generate_imported.py

@@ -13,12 +13,7 @@
 
 
 if TYPE_CHECKING:
-    import sys
-
-    if sys.version_info >= (3, 11):
-        from typing import Never
-    else:  # pragma: no cover
-        from typing import NoReturn as Never
+    from typing import Never
 
     from sphinx.application import Sphinx
 

src/scanpydoc/definition_list_typed_field.py

@@ -20,13 +20,13 @@
 
 
 if TYPE_CHECKING:
-    from typing import Any, TypeAlias
+    from typing import Any
     from collections.abc import Iterable
 
     from sphinx.application import Sphinx
     from sphinx.environment import BuildEnvironment
 
-    TextLikeNode: TypeAlias = nodes.Text | nodes.TextElement
+    type TextLikeNode = nodes.Text | nodes.TextElement
 
 
 class DLTypedField(PyTypedField):
@@ -98,12 +98,10 @@ def handle_item(
 @_setup_sig
 def setup(app: Sphinx) -> dict[str, Any]:
     """Replace :class:`~sphinx.domains.python.PyTypedField` with ours."""
-    napoleon_requested = "sphinx.ext.napoleon" in app.config.extensions
-    napoleon_loaded = next(
-        (True for ft in PyObject.doc_field_types if ft.name == "keyword"),
-        False,
-    )
-    if napoleon_requested and not napoleon_loaded:
+    if (
+        "sphinx.ext.napoleon" in app.config.extensions
+        and "sphinx.ext.napoleon" not in app.extensions
+    ):
         msg = f"Please load sphinx.ext.napoleon before {__name__}"
         raise RuntimeError(msg)
 

src/scanpydoc/elegant_typehints/_formatting.py

@@ -2,7 +2,7 @@
 
 import inspect
 from types import GenericAlias
-from typing import TYPE_CHECKING, cast, get_args, get_origin
+from typing import TYPE_CHECKING, TypeAliasType, cast, get_args, get_origin
 
 from sphinx_autodoc_typehints import format_annotation
 
@@ -16,7 +16,7 @@
     from sphinx.config import Config
 
 
-def typehints_formatter(annotation: type[Any], config: Config) -> str | None:
+def typehints_formatter(annotation: object, config: Config) -> str | None:
     """Generate reStructuredText containing links to the types.
 
     Can be used as ``typehints_formatter`` for :mod:`sphinx_autodoc_typehints`,
@@ -33,6 +33,9 @@ def typehints_formatter(annotation: type[Any], config: Config) -> str | None:
     -------
     reStructuredText describing the type
     """
+    if isinstance(annotation, TypeAliasType):
+        return format_annotation(annotation.__value__, config)
+
     if inspect.isclass(annotation) and annotation.__module__ == "builtins":
         return None
 

src/scanpydoc/elegant_typehints/_role_mapping.py

@@ -50,7 +50,7 @@ def __getitem__(self, key: tuple[str | None, str]) -> tuple[str | None, str]:
         for known_role in chain([None], {r for r, _ in self}):
             try:
                 return self.data[known_role, key[1]]
-            except KeyError:  # noqa: PERF203
+            except KeyError:
                 pass
         raise KeyError(key)
 

src/scanpydoc/rtd_github_links/__init__.py

@@ -75,10 +75,10 @@
 
 if TYPE_CHECKING:
     from types import CodeType, FrameType, MethodType, FunctionType, TracebackType
-    from typing import Any, TypeAlias
+    from typing import Any
     from collections.abc import Callable
 
-    _SourceObjectType: TypeAlias = (
+    type _SourceObjectType = (
         ModuleType
         | type[Any]
         | MethodType
@@ -211,8 +211,7 @@ def github_url(qualname: str) -> str:
     try:
         obj, module = _get_obj_module(qualname)
     except Exception as e:
-        if sys.version_info >= (3, 11):
-            e.add_note(f"Qualname: {qualname!r}")
+        e.add_note(f"Qualname: {qualname!r}")
         raise
     assert rtd_links_prefix is not None  # noqa: S101
     path = rtd_links_prefix / _module_path(obj, module)