From cc1f01f7a21ab9d47bae496063cf8237f30d7a17 Mon Sep 17 00:00:00 2001 From: "Takeshi Ikuma (LSUHSC)" Date: Sun, 16 Jun 2024 16:20:02 -0500 Subject: [PATCH 01/10] support autodoc_type_aliases configuration --- src/sphinx_autodoc_typehints/__init__.py | 11 +- .../test_integration_autodoc_type_aliases.py | 128 ++++++++++++++++++ 2 files changed, 135 insertions(+), 4 deletions(-) create mode 100644 tests/test_integration_autodoc_type_aliases.py diff --git a/src/sphinx_autodoc_typehints/__init__.py b/src/sphinx_autodoc_typehints/__init__.py index 7cf8edd..8b36a01 100644 --- a/src/sphinx_autodoc_typehints/__init__.py +++ b/src/sphinx_autodoc_typehints/__init__.py @@ -345,7 +345,7 @@ def process_signature( # noqa: C901, PLR0913, PLR0917 return None obj = inspect.unwrap(obj) - sph_signature = sphinx_signature(obj) + sph_signature = sphinx_signature(obj, type_aliases=app.config.autodoc_type_aliases) if app.config.typehints_use_signature: parameters = list(sph_signature.parameters.values()) @@ -642,7 +642,7 @@ def process_docstring( # noqa: PLR0913, PLR0917 obj = inspect.unwrap(obj) try: - signature = sphinx_signature(obj) + signature = sphinx_signature(obj, type_aliases=app.config.autodoc_type_aliases) except (ValueError, TypeError): signature = None type_hints = get_all_type_hints(app.config.autodoc_mock_imports, obj, name) @@ -715,8 +715,11 @@ def _inject_signature( # noqa: C901 app: Sphinx, lines: list[str], ) -> None: - for arg_name in signature.parameters: - annotation = type_hints.get(arg_name) + + type_aliases = app.config.autodoc_type_aliases + + for arg_name, arg_type in signature.parameters.items(): + annotation = arg_type._annotation if arg_type._annotation in type_aliases else type_hints.get(arg_name) default = signature.parameters[arg_name].default diff --git a/tests/test_integration_autodoc_type_aliases.py b/tests/test_integration_autodoc_type_aliases.py new file mode 100644 index 0000000..843d4ca --- /dev/null +++ b/tests/test_integration_autodoc_type_aliases.py @@ -0,0 +1,128 @@ +from __future__ import annotations + +import re +import sys +from pathlib import Path +from textwrap import dedent, indent +from typing import TYPE_CHECKING, Any, Callable, NewType, TypeVar # no type comments + +from numpy.typing import ArrayLike + +import pytest + +if TYPE_CHECKING: + from io import StringIO + + from sphinx.testing.util import SphinxTestApp + +T = TypeVar("T") +W = NewType("W", str) + + +def expected(expected: str, **options: dict[str, Any]) -> Callable[[T], T]: + def dec(val: T) -> T: + val.EXPECTED = expected + val.OPTIONS = options + return val + + return dec + + +def warns(pattern: str) -> Callable[[T], T]: + def dec(val: T) -> T: + val.WARNING = pattern + return val + + return dec + + +@expected( + """\ +mod.function(x) + + Function docstring. + + Parameters: + **x** (ArrayLike) -- foo + + Returns: + something + + Return type: + bytes +""", +) +def function(x: ArrayLike) -> str: # noqa: ARG001, UP007 + """ + Function docstring. + + :param x: foo + :return: something + :rtype: bytes + """ + + +AUTO_FUNCTION = ".. autofunction:: mod.{}" + +LT_PY310 = sys.version_info < (3, 10) + + +prolog = """ +.. |test_node_start| replace:: {test_node_start} +""".format( + test_node_start="test_start" +) + + +epilog = """ +.. |test_node_end| replace:: {test_node_end} +""".format( + test_node_end="test_end" +) + + +# Config settings for each test run. +# Config Name: Sphinx Options as Dict. +configs = { + "default_conf": { + "autodoc_type_aliases": { + "ArrayLike": "ArrayLike", + } + } +} + + +@pytest.mark.parametrize("val", [x for x in globals().values() if hasattr(x, "EXPECTED")]) +@pytest.mark.parametrize("conf_run", list(configs.keys())) +@pytest.mark.sphinx("text", testroot="integration") +def test_integration( + app: SphinxTestApp, status: StringIO, warning: StringIO, monkeypatch: pytest.MonkeyPatch, val: Any, conf_run: str +) -> None: + template = AUTO_FUNCTION + + (Path(app.srcdir) / "index.rst").write_text(template.format(val.__name__)) + app.config.__dict__.update(configs[conf_run]) + app.config.__dict__.update(val.OPTIONS) + monkeypatch.setitem(sys.modules, "mod", sys.modules[__name__]) + app.build() + assert "build succeeded" in status.getvalue() # Build succeeded + + regexp = getattr(val, "WARNING", None) + value = warning.getvalue().strip() + if regexp: + msg = f"Regex pattern did not match.\n Regex: {regexp!r}\n Input: {value!r}" + assert re.search(regexp, value), msg + else: + assert not value + + result = (Path(app.srcdir) / "_build/text/index.txt").read_text() + + expected = val.EXPECTED + if LT_PY310: + expected = expected.replace("NewType", "NewType()") + try: + assert result.strip() == dedent(expected).strip() + except Exception: + indented = indent(f'"""\n{result}\n"""', " " * 4) + print(f"@expected(\n{indented}\n)\n") # noqa: T201 + raise From 054e5578dab7ededa9ed07b9b098c4ee447354d1 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Sun, 16 Jun 2024 21:41:55 +0000 Subject: [PATCH 02/10] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- src/sphinx_autodoc_typehints/__init__.py | 3 +-- tests/test_integration_autodoc_type_aliases.py | 13 ++++--------- 2 files changed, 5 insertions(+), 11 deletions(-) diff --git a/src/sphinx_autodoc_typehints/__init__.py b/src/sphinx_autodoc_typehints/__init__.py index 8b36a01..6b323c7 100644 --- a/src/sphinx_autodoc_typehints/__init__.py +++ b/src/sphinx_autodoc_typehints/__init__.py @@ -715,9 +715,8 @@ def _inject_signature( # noqa: C901 app: Sphinx, lines: list[str], ) -> None: - type_aliases = app.config.autodoc_type_aliases - + for arg_name, arg_type in signature.parameters.items(): annotation = arg_type._annotation if arg_type._annotation in type_aliases else type_hints.get(arg_name) diff --git a/tests/test_integration_autodoc_type_aliases.py b/tests/test_integration_autodoc_type_aliases.py index 843d4ca..4097646 100644 --- a/tests/test_integration_autodoc_type_aliases.py +++ b/tests/test_integration_autodoc_type_aliases.py @@ -6,13 +6,12 @@ from textwrap import dedent, indent from typing import TYPE_CHECKING, Any, Callable, NewType, TypeVar # no type comments -from numpy.typing import ArrayLike - import pytest if TYPE_CHECKING: from io import StringIO + from numpy.typing import ArrayLike from sphinx.testing.util import SphinxTestApp T = TypeVar("T") @@ -52,7 +51,7 @@ def dec(val: T) -> T: bytes """, ) -def function(x: ArrayLike) -> str: # noqa: ARG001, UP007 +def function(x: ArrayLike) -> str: # noqa: ARG001 """ Function docstring. @@ -69,16 +68,12 @@ def function(x: ArrayLike) -> str: # noqa: ARG001, UP007 prolog = """ .. |test_node_start| replace:: {test_node_start} -""".format( - test_node_start="test_start" -) +""".format(test_node_start="test_start") epilog = """ .. |test_node_end| replace:: {test_node_end} -""".format( - test_node_end="test_end" -) +""".format(test_node_end="test_end") # Config settings for each test run. From e5cbe9c4325cad6df471620b0f18af60a9ceb61a Mon Sep 17 00:00:00 2001 From: "Takeshi Ikuma (LSUHSC)" Date: Sun, 16 Jun 2024 17:38:05 -0500 Subject: [PATCH 03/10] fixed app.config access --- src/sphinx_autodoc_typehints/__init__.py | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/src/sphinx_autodoc_typehints/__init__.py b/src/sphinx_autodoc_typehints/__init__.py index 6b323c7..1417da6 100644 --- a/src/sphinx_autodoc_typehints/__init__.py +++ b/src/sphinx_autodoc_typehints/__init__.py @@ -345,7 +345,7 @@ def process_signature( # noqa: C901, PLR0913, PLR0917 return None obj = inspect.unwrap(obj) - sph_signature = sphinx_signature(obj, type_aliases=app.config.autodoc_type_aliases) + sph_signature = sphinx_signature(obj, type_aliases=app.config['autodoc_type_aliases']) if app.config.typehints_use_signature: parameters = list(sph_signature.parameters.values()) @@ -642,7 +642,7 @@ def process_docstring( # noqa: PLR0913, PLR0917 obj = inspect.unwrap(obj) try: - signature = sphinx_signature(obj, type_aliases=app.config.autodoc_type_aliases) + signature = sphinx_signature(obj, type_aliases=app.config['autodoc_type_aliases']) except (ValueError, TypeError): signature = None type_hints = get_all_type_hints(app.config.autodoc_mock_imports, obj, name) @@ -715,8 +715,9 @@ def _inject_signature( # noqa: C901 app: Sphinx, lines: list[str], ) -> None: - type_aliases = app.config.autodoc_type_aliases - + + type_aliases = app.config['autodoc_type_aliases'] + for arg_name, arg_type in signature.parameters.items(): annotation = arg_type._annotation if arg_type._annotation in type_aliases else type_hints.get(arg_name) From 0f409ec8b60ab6d91aaa1644058f1b66b9dc417d Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Sun, 16 Jun 2024 22:38:14 +0000 Subject: [PATCH 04/10] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- src/sphinx_autodoc_typehints/__init__.py | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/src/sphinx_autodoc_typehints/__init__.py b/src/sphinx_autodoc_typehints/__init__.py index 1417da6..dcdef1b 100644 --- a/src/sphinx_autodoc_typehints/__init__.py +++ b/src/sphinx_autodoc_typehints/__init__.py @@ -345,7 +345,7 @@ def process_signature( # noqa: C901, PLR0913, PLR0917 return None obj = inspect.unwrap(obj) - sph_signature = sphinx_signature(obj, type_aliases=app.config['autodoc_type_aliases']) + sph_signature = sphinx_signature(obj, type_aliases=app.config["autodoc_type_aliases"]) if app.config.typehints_use_signature: parameters = list(sph_signature.parameters.values()) @@ -642,7 +642,7 @@ def process_docstring( # noqa: PLR0913, PLR0917 obj = inspect.unwrap(obj) try: - signature = sphinx_signature(obj, type_aliases=app.config['autodoc_type_aliases']) + signature = sphinx_signature(obj, type_aliases=app.config["autodoc_type_aliases"]) except (ValueError, TypeError): signature = None type_hints = get_all_type_hints(app.config.autodoc_mock_imports, obj, name) @@ -715,9 +715,8 @@ def _inject_signature( # noqa: C901 app: Sphinx, lines: list[str], ) -> None: - - type_aliases = app.config['autodoc_type_aliases'] - + type_aliases = app.config["autodoc_type_aliases"] + for arg_name, arg_type in signature.parameters.items(): annotation = arg_type._annotation if arg_type._annotation in type_aliases else type_hints.get(arg_name) From 7b34a24d596ab94231c91ce8b4aba4a58d5008e9 Mon Sep 17 00:00:00 2001 From: "Takeshi Ikuma (LSUHSC)" Date: Sun, 16 Jun 2024 17:48:49 -0500 Subject: [PATCH 05/10] removed numpy dependency for 3.12 compatibility --- tests/test_integration_autodoc_type_aliases.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tests/test_integration_autodoc_type_aliases.py b/tests/test_integration_autodoc_type_aliases.py index 4097646..e60182d 100644 --- a/tests/test_integration_autodoc_type_aliases.py +++ b/tests/test_integration_autodoc_type_aliases.py @@ -4,14 +4,13 @@ import sys from pathlib import Path from textwrap import dedent, indent -from typing import TYPE_CHECKING, Any, Callable, NewType, TypeVar # no type comments +from typing import TYPE_CHECKING, Any, Callable, NewType, TypeVar, Literal # no type comments import pytest if TYPE_CHECKING: from io import StringIO - from numpy.typing import ArrayLike from sphinx.testing.util import SphinxTestApp T = TypeVar("T") @@ -34,6 +33,7 @@ def dec(val: T) -> T: return dec +ArrayLike = Literal['test'] @expected( """\ From 0aab83d3d9b966b4fcbc9f67037523e33dbeba41 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Sun, 16 Jun 2024 22:48:58 +0000 Subject: [PATCH 06/10] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- tests/test_integration_autodoc_type_aliases.py | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/tests/test_integration_autodoc_type_aliases.py b/tests/test_integration_autodoc_type_aliases.py index e60182d..9d290c7 100644 --- a/tests/test_integration_autodoc_type_aliases.py +++ b/tests/test_integration_autodoc_type_aliases.py @@ -4,7 +4,7 @@ import sys from pathlib import Path from textwrap import dedent, indent -from typing import TYPE_CHECKING, Any, Callable, NewType, TypeVar, Literal # no type comments +from typing import TYPE_CHECKING, Any, Callable, Literal, NewType, TypeVar # no type comments import pytest @@ -33,7 +33,9 @@ def dec(val: T) -> T: return dec -ArrayLike = Literal['test'] + +ArrayLike = Literal["test"] + @expected( """\ From a06a1fc5983148a6b729da8739b9226ff622ba59 Mon Sep 17 00:00:00 2001 From: "Takeshi Ikuma (LSUHSC)" Date: Sun, 16 Jun 2024 18:00:37 -0500 Subject: [PATCH 07/10] use arg_type.annotation instead of arg_type._annotation --- src/sphinx_autodoc_typehints/__init__.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/sphinx_autodoc_typehints/__init__.py b/src/sphinx_autodoc_typehints/__init__.py index dcdef1b..0c02ad9 100644 --- a/src/sphinx_autodoc_typehints/__init__.py +++ b/src/sphinx_autodoc_typehints/__init__.py @@ -718,7 +718,7 @@ def _inject_signature( # noqa: C901 type_aliases = app.config["autodoc_type_aliases"] for arg_name, arg_type in signature.parameters.items(): - annotation = arg_type._annotation if arg_type._annotation in type_aliases else type_hints.get(arg_name) + annotation = arg_type.annotation if arg_type.annotation in type_aliases else type_hints.get(arg_name) default = signature.parameters[arg_name].default From ff0d700aff869d696c3b87374e3a24de473628c4 Mon Sep 17 00:00:00 2001 From: "Takeshi Ikuma (LSUHSC)" Date: Mon, 17 Jun 2024 19:27:32 -0500 Subject: [PATCH 08/10] skip mypy test on all test_integration* files --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index 0665011..2fa8f7b 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -145,7 +145,7 @@ run.plugins = [ [tool.mypy] python_version = "3.10" strict = true -exclude = "^(.*/roots/.*)|(tests/test_integration.py)$" +exclude = "^(.*/roots/.*)|(tests/test_integration*.py)$" overrides = [ { module = [ "sphobjinv.*", From 1de28e8a8a8bbaa037f00eb946da749b5c5bcf6a Mon Sep 17 00:00:00 2001 From: "Takeshi Ikuma (LSUHSC)" Date: Tue, 18 Jun 2024 19:05:36 -0500 Subject: [PATCH 09/10] removed extreneous lines --- .../test_integration_autodoc_type_aliases.py | 19 ++----------------- 1 file changed, 2 insertions(+), 17 deletions(-) diff --git a/tests/test_integration_autodoc_type_aliases.py b/tests/test_integration_autodoc_type_aliases.py index 9d290c7..8e88507 100644 --- a/tests/test_integration_autodoc_type_aliases.py +++ b/tests/test_integration_autodoc_type_aliases.py @@ -63,21 +63,6 @@ def function(x: ArrayLike) -> str: # noqa: ARG001 """ -AUTO_FUNCTION = ".. autofunction:: mod.{}" - -LT_PY310 = sys.version_info < (3, 10) - - -prolog = """ -.. |test_node_start| replace:: {test_node_start} -""".format(test_node_start="test_start") - - -epilog = """ -.. |test_node_end| replace:: {test_node_end} -""".format(test_node_end="test_end") - - # Config settings for each test run. # Config Name: Sphinx Options as Dict. configs = { @@ -95,7 +80,7 @@ def function(x: ArrayLike) -> str: # noqa: ARG001 def test_integration( app: SphinxTestApp, status: StringIO, warning: StringIO, monkeypatch: pytest.MonkeyPatch, val: Any, conf_run: str ) -> None: - template = AUTO_FUNCTION + template = ".. autofunction:: mod.{}" (Path(app.srcdir) / "index.rst").write_text(template.format(val.__name__)) app.config.__dict__.update(configs[conf_run]) @@ -115,7 +100,7 @@ def test_integration( result = (Path(app.srcdir) / "_build/text/index.txt").read_text() expected = val.EXPECTED - if LT_PY310: + if sys.version_info < (3, 10): expected = expected.replace("NewType", "NewType()") try: assert result.strip() == dedent(expected).strip() From c31d03fac099ebacd774b536be482d581ac9512d Mon Sep 17 00:00:00 2001 From: "Takeshi Ikuma (LSUHSC)" Date: Tue, 18 Jun 2024 19:15:01 -0500 Subject: [PATCH 10/10] fixed the mypy exclude regexp --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index 2fa8f7b..945866c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -145,7 +145,7 @@ run.plugins = [ [tool.mypy] python_version = "3.10" strict = true -exclude = "^(.*/roots/.*)|(tests/test_integration*.py)$" +exclude = "^(.*/roots/.*)|(tests/test_integration.*.py)$" overrides = [ { module = [ "sphobjinv.*",