tox-dev-sphinx-autodoc-typehints-607-606

LICENSE
README.md
ignore-words.txt
pyproject.toml
src
tests
tox.toml
whitelist.txt
conftest.py
roots
test_integration.py
test_integration_autodoc_type_aliases.py

test_integration_issue_384.py
test_sphinx_autodoc_typehints.py
test_version.py

__init__.py
_parser.py
attributes_patch.py
patches.py
py.typed
version.py
 1108 /repo/src/sphinx_autodoc_typehints/__init__.py
   31 /repo/src/sphinx_autodoc_typehints/_parser.py
   63 /repo/src/sphinx_autodoc_typehints/attributes_patch.py
  162 /repo/src/sphinx_autodoc_typehints/patches.py
   24 /repo/src/sphinx_autodoc_typehints/version.py
 1388 total

"""Custom patches to make the world work."""

from __future__ import annotations

from functools import lru_cache
from typing import TYPE_CHECKING, Any

from docutils import nodes
from docutils.parsers.rst.directives.admonitions import BaseAdmonition
from docutils.parsers.rst.states import Body, Text
from sphinx.ext.napoleon.docstring import GoogleDocstring

from .attributes_patch import patch_attribute_handling

if TYPE_CHECKING:
    from sphinx.application import Sphinx
    from sphinx.ext.autodoc import Options


def napoleon_numpy_docstring_return_type_processor(  # noqa: PLR0913, PLR0917
    app: Sphinx,
    what: str,
    name: str,  # noqa: ARG001
    obj: Any,  # noqa: ARG001
    options: Options | None,  # noqa: ARG001
    lines: list[str],
) -> None:
    """Insert a : under Returns: to tell napoleon not to look for a return type."""
    if what not in {"function", "method"}:
…[3951 chars omitted]…
install_patches(app: Sphinx) -> None:
    """
    Install the patches.

    :param app: the Sphinx app
    """
    # For Sphinx 9+ directive-based architecture
    fix_directive_based_signature_formatting()
    patch_attribute_handling(app)
    _patch_google_docstring_lookup_annotation()
    fix_napoleon_numpy_docstring_return_type(app)
    _patch_line_numbers()


___all__ = [
    "install_patches",
]

"""Patch for attributes."""

from __future__ import annotations

from functools import partial
from typing import TYPE_CHECKING, Any
from unittest.mock import patch

import sphinx.domains.python
from sphinx.domains.python import PyAttribute

from ._parser import parse

if TYPE_CHECKING:
    from docutils.frontend import Values
    from sphinx.addnodes import desc_signature
    from sphinx.application import Sphinx

# Defensively check for the things we want to patch
_parse_annotation = getattr(sphinx.domains.python, "_parse_annotation", None)

# If we didn't locate the patch target, we will just do nothing.
OKAY_TO_PATCH = bool(_parse_annotation)

# A label we inject to the type string so we know not to try to treat it as a
# type annotation
TYPE_IS_RST_LABEL = "--is-rst--"

orig_handle_signature = PyAttribute.handle_signature


def rst_to_docutils(settings: Values, rst: str) -> Any:

…[2414 chars omitted]…
)
794:    signature: inspect.Signature | None,
809:    signature: inspect.Signature,
819:    signature: inspect.Signature,
988:    if inspect.isclass(original_obj) or inspect.isdatadescriptor(original_obj):
1092:    app.connect("autodoc-process-signature", process_signature)
1093:    app.connect("autodoc-process-docstring", process_docstring)
1106:    "process_docstring",
1107:    "process_signature",

aligned_suffix = [whitespace + remove_prefix(s, whitespace) for s in lines[idx + 1 :]]

    # Put it together again
    aligned_prefix.append(fn_def)
    return "\n".join(aligned_prefix + aligned_suffix)


def process_signature(  # noqa: C901, PLR0913, PLR0917
    app: Sphinx,
    what: str,
    name: str,
    obj: Any,

    options: Options,  # noqa: ARG001
    signature: str,  # noqa: ARG001
    return_annotation: str,  # noqa: ARG001
) -> tuple[str, None] | None:
    """
    Process the signature.

    :param app:
    :param what:
    :param name:
    :param obj:
    :param options:
    :param signature:
    :param return_annotation:
    :return:
    """
    if not callable(obj):
        return None

    original_obj = obj
    obj = getattr(obj, "__init__", getattr(obj, "__new__", None)) if inspect.isclass(obj) else obj
    if not getattr(obj, "__annotations__", None):  # when h
…[5091 chars omitted]…
d_argument(line: str) -> tuple[str, str | None] | None:
    """
    Extract a keyword, and its optional argument out of a sphinx field option line.

    For example
    >>> _get_sphinx_line_keyword_and_argument(":param parameter:")
    ("param", "parameter")
    >>> _get_sphinx_line_keyword_and_argument(":return:")
    ("return", None)
    >>> _get_sphinx_line_keyword_and_argument("some invalid line")

test-dummy
test-integration
test-resolve-typing-guard
test-resolve-typing-guard-tmp

cd56944 base

Traceback (most recent call last):
  File "<string>", line 4, in <module>
TypeError: Sphinx.__init__() got multiple values for argument 'confdir'

Traceback (most recent call last):
  File "<string>", line 4, in <module>
TypeError: Sphinx.__init__() missing 1 required positional argument: 'buildername'

File "<frozen importlib._bootstrap>", line 488, in _call_with_frames_removed
  File "/tmp/rep/mod.py", line 9, in <module>
    class Point(NamedTuple):
  File "/usr/local/lib/python3.12/typing.py", line 2841, in __new__
    raise AttributeError("Cannot overwrite NamedTuple attribute " + key)
AttributeError: Cannot overwrite NamedTuple attribute __new__

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/usr/local/lib/python3.12/site-packages/sphinx/ext/autodoc/_dynamic/_importer.py", line 131, in _import_from_module_and_path
    module = _import_module(module_name, try_reload=True)

             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.12/site-packages/sphinx/ext/autodoc/_dynamic/_importer.py", line 233, in _import_module
    raise ImportError(exc, traceback.format_exc()) from exc
Import
…[1987 chars omitted]…
00mdone
copying assets: done
writing output... [100%] index

generating indices... genindex done
writing additional pages... search done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 1 warning.

The HTML pages are in out.

WARNING: error while formatting arguments for mod.circular: wrapper loop when unwrapping <function <lambda> at 0x7542fbac6ac0> [autodoc]
Traceback (most recent call last):
    raise ValueError('wrapper loop when unwrapping {!r}'.format(f))
ValueError: wrapper loop when unwrapping <function <lambda> at 0x7542fbac6ac0>
Traceback (most recent call last):
    raise ExtensionError(
sphinx.errors.ExtensionError: Handler <function process_docstring at 0x7542fbaa28e0> for event 'autodoc-process-docstring' threw an exception (exception: wrapper loop when unwrapping <function <lambda> at 0x7542fbac6ac0>)

WARNING: error while formatting signature for mod.Point.__new__: Handler <function process_signature at 0x7bbcb52fa160> for event 'autodoc-process-signature' threw an exception (exception: 'NoneType' object has no attribute 'Point') [autodoc]
build succeeded, 1 warning.

src/sphinx_autodoc_typehints/__init__.py | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)

WARNING: error while formatting arguments for mod.circular: wrapper loop when unwrapping <function <lambda> at 0x7c735f8771a0> [autodoc]
build succeeded, 1 warning.
exit=0

36:    """Properties and assertion methods for warnings."""
51:    def assert_warning(self, message: str) -> None:
1537:    app: SphinxTestApp, status: StringIO, warning: StringIO, monkeypatch: pytest.MonkeyPatch, val: Any, conf_run: str
1554:    warning_info: Union[WarningInfo, None] = getattr(val, "WARNING", None)
1555:    value = warning.getvalue().strip()
1556:    if warning_info:
1557:        warning_info.assert_warning(value)
from __future__ import annotations

import re
import sys
from dataclasses import dataclass

from inspect import isclass
from pathlib import Path
from textwrap import dedent, indent
from typing import (  # no type comments
    TYPE_CHECKING,
    Any,
    Literal,
    NewType,
    Optional,
    TypeVar,
    Union,
    overload,
)

import pytest

if TYPE_CHECKING:
    from collections.abc import AsyncGenerator, Callable
    from io import StringIO
    from mail
…[618 chars omitted]…
 and subtype.\n Expected: {expected}\n Input: {message}"
        assert expected in message, msg

    def assert_warning(self, message: str) -> None:
        self.assert_regexp(message)
        self.assert_type(message)


def expected(expected: str, **options: dict[str, Any]) -> Callable[[T], T]:
    def dec(val: T) -> T:
        val.EXPECTED = expected
        val.OPTIONS = options
        return val

E               urllib.error.URLError: <urlopen error [Errno -3] Temporary failure in name resolution>

/usr/local/lib/python3.12/urllib/request.py:1347: URLError
=============================== warnings summary ===============================
tests/test_integration.py: 456 warnings
tests/test_integration_autodoc_type_aliases.py: 6 warnings
tests/test_integration_issue_384.py: 2 warnings
  /usr/local/lib/python3.12/site-packages/sphinx/ext/napoleon/docstring.py:361: RemovedInSphinx11Warning: The mapping interface for autodoc options objects is deprecated, and will be removed in Sphinx 11. Use attribute access instead.
    if options:

-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
=========================== short test summary info ============================

ERROR tests/test_sphinx_autodoc_typehints.py::test_format_annotation[str] - u...
!!!!!!!!!!!!!!!!!!!!!!!!!! stopping after 1 failures !!!!!!!!!!!!!!!!!!!!!!!!!!!
216 passed, 464 warnings, 1 error in 13.25s

ERROR tests/test_sphinx_autodoc_typehints.py::test_format_annotation[Tuple-p-Ellipsis]
ERROR tests/test_sphinx_autodoc_typehints.py::test_format_annotation[Annotated-metadata]
ERROR tests/test_sphinx_autodoc_typehints.py::test_format_annotation[Required]
ERROR tests/test_sphinx_autodoc_typehints.py::test_format_annotation[NotRequired]
264 passed, 1 deselected, 840 warnings, 79 errors in 35.55s

Saved working directory and index state WIP on master: cd56944 base
ERROR tests/test_sphinx_autodoc_typehints.py::test_format_annotation[Required]
ERROR tests/test_sphinx_autodoc_typehints.py::test_format_annotation[NotRequired]
83 passed, 376 warnings, 80 errors in 23.69s
On branch master
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
	modified:   src/sphinx_autodoc_typehints/__init__.py

no changes added to commit (use "git add" and/or "git commit -a")
Dropped refs/stash@{0} (c8779e6925fc32d4f01cca719a692db297e060c6)

diff --git a/src/sphinx_autodoc_typehints/__init__.py b/src/sphinx_autodoc_typehints/__init__.py
index a7a020b..40a4e24 100644
--- a/src/sphinx_autodoc_typehints/__init__.py
+++ b/src/sphinx_autodoc_typehints/__init__.py
@@ -393,8 +393,11 @@ def process_signature(  # noqa: C901, PLR0913, PLR0917
     if not getattr(obj, "__annotations__", None):  # when has no annotation we cannot autodoc typehints so bail
         return None
 
-    obj = inspect.unwrap(obj)
-    sph_signature = sphinx_signature(obj, type_aliases=app.config["autodoc_type_aliases"])
+    try:
+        obj = inspect.unwrap(obj)

+        sph_signature = sphinx_signature(obj, type_aliases=app.config["autodoc_type_aliases"])
+    except (ValueError, TypeError):  # cannot safely inspect the callable (e.g. circular __wrapped__)
+        return None
     typehints_formatter: Callable[..., str | None] | None = getattr(app.con
…[563 chars omitted]…
 process_docstring(  # noqa: PLR0913, PLR0917
     if not callable(obj):
         return
     obj = obj.__init__ if inspect.isclass(obj) else obj
-    obj = inspect.unwrap(obj)
+    try:
+        obj = inspect.unwrap(obj)
+    except ValueError:  # e.g. circular __wrapped__ reference
+        return
 
     try:
         signature = sphinx_signature(obj, type_aliases=app.config["autodoc_type_aliases"])

submitted.

LICENSE
README.md
ignore-words.txt
pyproject.toml
src
tests
tox.toml
whitelist.txt
conftest.py
roots
test_integration.py
test_integration_autodoc_type_aliases.py

test_integration_issue_384.py
test_sphinx_autodoc_typehints.py
test_version.py

__init__.py
_parser.py
attributes_patch.py
patches.py
py.typed
version.py
 1108 /repo/src/sphinx_autodoc_typehints/__init__.py
   31 /repo/src/sphinx_autodoc_typehints/_parser.py
   63 /repo/src/sphinx_autodoc_typehints/attributes_patch.py
  162 /repo/src/sphinx_autodoc_typehints/patches.py
   24 /repo/src/sphinx_autodoc_typehints/version.py
 1388 total

"""Custom patches to make the world work."""

from __future__ import annotations

from functools import lru_cache
from typing import TYPE_CHECKING, Any

from docutils import nodes
from docutils.parsers.rst.directives.admonitions import BaseAdmonition
from docutils.parsers.rst.states import Body, Text
from sphinx.ext.napoleon.docstring import GoogleDocstring

from .attributes_patch import patch_attribute_handling

if TYPE_CHECKING:
    from sphinx.application import Sphinx
    from sphinx.ext.autodoc import Options


def napoleon_numpy_docstring_return_type_processor(  # noqa: PLR0913, PLR0917
    app: Sphinx,
    what: str,
    name: str,  # noqa: ARG001
    obj: Any,  # noqa: ARG001
    options: Options | None,  # noqa: ARG001
    lines: list[str],
) -> None:
    """Insert a : under Returns: to tell napoleon not to look for a return type."""
    if what not in {"function", "method"}:
…[3951 chars omitted]…
install_patches(app: Sphinx) -> None:
    """
    Install the patches.

    :param app: the Sphinx app
    """
    # For Sphinx 9+ directive-based architecture
    fix_directive_based_signature_formatting()
    patch_attribute_handling(app)
    _patch_google_docstring_lookup_annotation()
    fix_napoleon_numpy_docstring_return_type(app)
    _patch_line_numbers()


___all__ = [
    "install_patches",
]

367:def process_signature(  # noqa: C901, PLR0913, PLR0917
711:def process_docstring(  # noqa: PLR0913, PLR0917
1092:    app.connect("autodoc-process-signature", process_signature)
1093:    app.connect("autodoc-process-docstring", process_docstring)
1106:    "process_docstring",
1107:    "process_signature",
b6ebb92 base

aligned_suffix = [whitespace + remove_prefix(s, whitespace) for s in lines[idx + 1 :]]

    # Put it together again
    aligned_prefix.append(fn_def)
    return "\n".join(aligned_prefix + aligned_suffix)


def process_signature(  # noqa: C901, PLR0913, PLR0917
    app: Sphinx,
    what: str,
    name: str,
    obj: Any,

    options: Options,  # noqa: ARG001
    signature: str,  # noqa: ARG001
    return_annotation: str,  # noqa: ARG001
) -> tuple[str, None] | None:
    """
    Process the signature.

    :param app:
    :param what:
    :param name:
    :param obj:
    :param options:
    :param signature:
    :param return_annotation:
    :return:
    """
    if not callable(obj):
        return None

    original_obj = obj
    obj = getattr(obj, "__init__", getattr(obj, "__new__", None)) if inspect.isclass(obj) else obj
    if not getattr(obj, "__annotations__", None):  # when h
…[5384 chars omitted]…
           exec(guarded_code, getattr(obj, "__globals__", obj.__dict__))  # noqa: S102
            except ImportError as exc:
                # ImportError might have occurred because the module has guarded code as well,
                # so we recurse on the module.
                if exc.name:
                    _resolve_type_guarded_imports(autodoc_mock_imports, importlib.import_module(exc.name))

formatted = repr(default).replace("\\", "\\\\")

    if is_annotated:
        if app.config.typehints_defaults.startswith("braces"):
            return f" (default: ``{formatted}``)"
        return f", default: ``{formatted}``"
    if app.config.typehints_defaults == "braces-after":
        return f" (default: ``{formatted}``)"
    return f"default: ``{formatted}``"


def process_docstring(  # noqa: PLR0913, PLR0917

    app: Sphinx,
    what: str,
    name: str,
    obj: Any,
    options: Options | None,  # noqa: ARG001
    lines: list[str],
) -> None:
    """
    Process the docstring for an entry.

    :param app: the Sphinx app
    :param what: the target
    :param name: the name
    :param obj: the object
    :param options: the options
    :param lines: the lines
    :return:
    """
    original_obj = obj
    obj = obj.fget if isinstance(obj, property) else obj
    if not c
…[4319 chars omitted]…
t_literals)
            )
            type_annotation = f":type {arg_name}: {formatted_annotation}"

        if app.config.typehints_defaults:
            formatted_default = format_default(app, default, annotation is not None or has_preexisting_annotation)
            if formatted_default:
                type_annotation = _append_default(app, lines, insert_index, type_annotation, formatted_default)

from __future__ import annotations

import re
import sys
from dataclasses import dataclass
from inspect import isclass
from pathlib import Path
from textwrap import dedent, indent
from typing import (  # no type comments
    TYPE_CHECKING,
    Any,
    Literal,

    NewType,
    Optional,
    TypeVar,
    Union,
    overload,
)

import pytest

if TYPE_CHECKING:
    from collections.abc import AsyncGenerator, Callable
    from io import StringIO
    from mailbox import Mailbox
    from types import CodeType, ModuleType

    from sphinx.testing.util import SphinxTestApp

T = TypeVar("T")
W = NewType("W", str)


@dataclass
class WarningInfo:
    """Properties and assertion methods for warnings."""

    regexp: str
    type: str

    def assert_regexp(self, message: str) -> None:
        regexp = self.regexp
        msg = f"Regex pattern did not match.\n Regex: {regexp!r}\n Input: {message
…[610 chars omitted]…
arns(info: WarningInfo) -> Callable[[T], T]:
    def dec(val: T) -> T:
        val.WARNING = info
        return val

    return dec


@expected("mod.get_local_function()")
def get_local_function():  # noqa: ANN201
    def wrapper(self) -> str:  # noqa: ANN001
        """
        Wrapper
        """

    return wrapper
test-dummy
test-integration
test-resolve-typing-guard
test-resolve-typing-guard-tmp

28:    from sphinx.testing.util import SphinxTestApp
1536:def test_integration(
1537:    app: SphinxTestApp, status: StringIO, warning: StringIO, monkeypatch: pytest.MonkeyPatch, val: Any, conf_run: str
from __future__ import annotations

import re
import shutil
import sys
from contextlib import suppress
from pathlib import Path
from typing import TYPE_CHECKING

import pytest
from sphobjinv import Inventory

if TYPE_CHECKING:
    from _pytest.config import Config

pytest_plugins = "sphinx.testing.fixtures"
collect_ignore = ["roots"]


@pytest.fixture(scope="session")
def inv(pytestconfig: Config) -> Inventory:
    cache_path = f"python{sys.version_info.major}.{sys.version_info.minor}/objects.inv"
    assert pytestconfig.cache is not None
    inv_dict = pytestconfig.cache.get(cache_path, None)
    if inv_dict is not None:
        return Inventory(inv_dict)

    url = f"https://docs.pyt
…[684 chars omitted]…
str(Path(__file__).parent) or ".").absolute() / "roots"


def pytest_ignore_collect(collection_path: Path, config: Config) -> bool | None:  # noqa: ARG001
    version_re = re.compile(r"_py(\d)(\d)\.py$")
    match = version_re.search(collection_path.name)
    if match:
        version = tuple(int(x) for x in match.groups())
        if sys.version_info < version:
            return True
    return None

""",
    typehints_use_signature=True,
    typehints_use_signature_return=True,
    typehints_formatter=lambda _, __=None: "Formatted",
)
def typehints_formatter_applied_to_signature[Unformatted](param: Unformatted) -> Unformatted:
    """
    Do nothing

    Args:
        param: A parameter

    Returns:
        The return value
    """
    return param


# Config settings for each test run.
# Config Name: Sphinx Options as Dict.
configs = {
    "default_conf": {},
    "prolog_conf": {"rst_prolog": prolog},
    "epilog_conf": {
        "rst_epilog": epilog,
    },
    "bothlog_conf": {
        "rst_prolog": prolog,
        "rst_epilog": epilog,
    },
}


@pytest.mark.parametrize("val", [x for x in globals().values() if hasattr(x, "EXPECTED")])
@pytest.mark.parametrize("conf_run", ["default_conf", "prolog_conf", "epilog_conf", "bothlog_conf"])
@pytest.mark.sphinx("text", testroot
…[861 chars omitted]…
      warning_info.assert_warning(value)
    else:
        assert not value

    result = (Path(app.srcdir) / "_build/text/index.txt").read_text()

    expected = val.EXPECTED
    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
conf.py

--- circular wrapped signature ---
None
--- circular wrapped docstring ---
FAIL: ValueError wrapper loop when unwrapping <function f at 0x78961ea96200>
Traceback (most recent call last):
  File "/tmp/repro.py", line 37, in <module>
    class Foo(NamedTuple):
  File "/usr/local/lib/python3.12/typing.py", line 2841, in __new__
    raise AttributeError("Cannot overwrite NamedTuple attribute " + key)
AttributeError: Cannot overwrite NamedTuple attribute __new__

--- circular wrapped signature ---
FAIL: ValueError wrapper loop when unwrapping <function f at 0x764d8acbe200>
--- circular wrapped docstring ---
FAIL: ValueError wrapper loop when unwrapping <function f at 0x764d8acbe200>
<staticmethod(<function Foo.__new__ at 0x764d88f03380>)> namedtuple_Foo Foo.__new__
--- namedtuple __new__ signature ---
FAIL: AttributeError 'NoneType' object has no attribute 'Foo'
--- namedtuple __new__ docstring ---
ok []

396:    obj = inspect.unwrap(obj)
434:            outer = inspect.getmodule(obj)
735:    obj = inspect.unwrap(obj)

--- circular wrapped signature ---
None
--- circular wrapped docstring ---
ok []
<staticmethod(<function Foo.__new__ at 0x7d04f4c9f4c0>)> namedtuple_Foo Foo.__new__
--- namedtuple __new__ signature ---
None
--- namedtuple __new__ docstring ---
ok []

/usr/local/lib/python3.12/site-packages/sphinx/ext/napoleon/docstring.py:361: RemovedInSphinx11Warning: The mapping interface for autodoc options objects is deprecated, and will be removed in Sphinx 11. Use attribute access instead.
    if options:

-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
176 passed, 456 warnings in 13.36s

ERROR tests/test_sphinx_autodoc_typehints.py::test_format_annotation[Required]
ERROR tests/test_sphinx_autodoc_typehints.py::test_format_annotation[NotRequired]
264 passed, 840 warnings, 80 errors in 40.91s
diff --git a/src/sphinx_autodoc_typehints/__init__.py b/src/sphinx_autodoc_typehints/__init__.py
index a7a020b..7e18807 100644
--- a/src/sphinx_autodoc_typehints/__init__.py
+++ b/src/sphinx_autodoc_typehints/__init__.py
@@ -393,7 +393,10 @@ def process_signature(  # noqa: C901, PLR0913, PLR0917
     if not getattr(obj, "__annotations__", None):  # when has no annotation we cannot autodoc typehints so bail
         return None
 
-    obj = inspect.unwrap(obj)

+    try:
+        obj = inspect.unwrap(obj)
+    except ValueError:  # circular __wrapped__ reference, cannot safely inspect
+        return None
     sph_signature = sphinx_signature(obj, type_aliases=app.config["autodoc_typ
…[602 chars omitted]…
(  # noqa: PLR0913, PLR0917
     if not callable(obj):
         return
     obj = obj.__init__ if inspect.isclass(obj) else obj
-    obj = inspect.unwrap(obj)
+    try:
+        obj = inspect.unwrap(obj)
+    except ValueError:  # circular __wrapped__ reference, cannot safely inspect
+        return
 
     try:
         signature = sphinx_signature(obj, type_aliases=app.config["autodoc_type_aliases"])

==================================== ERRORS ====================================
________________ ERROR at setup of test_format_annotation[str] _________________
            raise URLError('no host given')

submitted.

LICENSE
README.md
ignore-words.txt
pyproject.toml
src
tests
tox.toml
whitelist.txt
e4d09ce base

sphinx_autodoc_typehints

/repo/src/sphinx_autodoc_typehints:
__init__.py
_parser.py
attributes_patch.py
patches.py
py.typed
version.py

/repo/tests:
conftest.py
roots
test_integration.py

test_integration_autodoc_type_aliases.py
test_integration_issue_384.py
test_sphinx_autodoc_typehints.py
test_version.py
 1108 /repo/src/sphinx_autodoc_typehints/__init__.py
   31 /repo/src/sphinx_autodoc_typehints/_parser.py
   63 /repo/src/sphinx_autodoc_typehints/attributes_patch.py
  162 /repo/src/sphinx_autodoc_typehints/patches.py
   24 /repo/src/sphinx_autodoc_typehints/version.py
 1388 total

"""Custom patches to make the world work."""

from __future__ import annotations

from functools import lru_cache
from typing import TYPE_CHECKING, Any

from docutils import nodes
from docutils.parsers.rst.directives.admonitions import BaseAdmonition
from docutils.parsers.rst.states import Body, Text
from sphinx.ext.napoleon.docstring import GoogleDocstring

from .attributes_patch import patch_attribute_handling

if TYPE_CHECKING:
    from sphinx.application import Sphinx
    from sphinx.ext.autodoc import Options


def napoleon_numpy_docstring_return_type_processor(  # noqa: PLR0913, PLR0917
    app: Sphinx,
    what: str,
    name: str,  # noqa: ARG001
    obj: Any,  # noqa: ARG001
    options: Options | None,  # noqa: ARG001
    lines: list[str],
) -> None:
    """Insert a : under Returns: to tell napoleon not to look for a return type."""
    if what not in {"function", "method"}:
…[3951 chars omitted]…
install_patches(app: Sphinx) -> None:
    """
    Install the patches.

    :param app: the Sphinx app
    """
    # For Sphinx 9+ directive-based architecture
    fix_directive_based_signature_formatting()
    patch_attribute_handling(app)
    _patch_google_docstring_lookup_annotation()
    fix_napoleon_numpy_docstring_return_type(app)
    _patch_line_numbers()


___all__ = [
    "install_patches",
]

"""Patch for attributes."""

from __future__ import annotations

from functools import partial
from typing import TYPE_CHECKING, Any
from unittest.mock import patch

import sphinx.domains.python
from sphinx.domains.python import PyAttribute

from ._parser import parse

if TYPE_CHECKING:
    from docutils.frontend import Values
    from sphinx.addnodes import desc_signature
    from sphinx.application import Sphinx

# Defensively check for the things we want to patch
_parse_annotation = getattr(sphinx.domains.python, "_parse_annotation", None)

# If we didn't locate the patch target, we will just do nothing.
OKAY_TO_PATCH = bool(_parse_annotation)

# A label we inject to the type string so we know not to try to treat it as a
# type annotation
TYPE_IS_RST_LABEL = "--is-rst--"

orig_handle_signature = PyAttribute.handle_signature


def rst_to_docutils(settings: Values, rst: str) -> Any:

…[849 chars omitted]…
arget, new_func):
        return orig_handle_signature(self, sig, signode)


def patch_attribute_handling(app: Sphinx) -> None:  # noqa: ARG001
    """Patch PyAttribute.handle_signature to format class attribute type annotations."""
    if not OKAY_TO_PATCH:
        return
    PyAttribute.handle_signature = patched_handle_signature  # type:ignore[method-assign]


__all__ = ["patch_attribute_handling"]

20:from sphinx.util.inspect import TypeAliasForwardRef, stringify_signature
21:from sphinx.util.inspect import signature as sphinx_signature
367:def process_signature(  # noqa: C901, PLR0913, PLR0917
373:    signature: str,  # noqa: ARG001
377:    Process the signature.
384:    :param signature:
392:    obj = getattr(obj, "__init__", getattr(obj, "__new__", None)) if inspect.isclass(obj) else obj
396:    obj = inspect.unwrap(obj)
397:    sph_signature = sphinx_signature(obj, type_aliases=app.config["autodoc_type_aliases"])
406:    if app.config.typehints_use_signature_return:
407:        sph_signature = sph_signature.replace(
408:            return_annotation=_get_formatted_annotation(sph_signature.return_annotation)

411:    if app.config.typehints_use_signature:
414:            for param in sph_signature.parameters.values()
417:        parameters = [param.replace(annotation=inspect.P
…[1219 chars omitted]…
es the given arg name."""
1087:    app.add_config_value("typehints_use_signature", False, "env")  # noqa: FBT003
1088:    app.add_config_value("typehints_use_signature_return", False, "env")  # noqa: FBT003
1092:    app.connect("autodoc-process-signature", process_signature)
1093:    app.connect("autodoc-process-docstring", process_docstring)
1106:    "process_docstring",
1107:    "process_signature",

aligned_suffix = [whitespace + remove_prefix(s, whitespace) for s in lines[idx + 1 :]]

    # Put it together again
    aligned_prefix.append(fn_def)
    return "\n".join(aligned_prefix + aligned_suffix)


def process_signature(  # noqa: C901, PLR0913, PLR0917
    app: Sphinx,
    what: str,
    name: str,
    obj: Any,

    options: Options,  # noqa: ARG001
    signature: str,  # noqa: ARG001
    return_annotation: str,  # noqa: ARG001
) -> tuple[str, None] | None:
    """
    Process the signature.

    :param app:
    :param what:
    :param name:
    :param obj:
    :param options:
    :param signature:
    :param return_annotation:
    :return:
    """
    if not callable(obj):
        return None

    original_obj = obj
    obj = getattr(obj, "__init__", getattr(obj, "__new__", None)) if inspect.isclass(obj) else obj
    if not getattr(obj, "__annotations__", None):  # when h
…[5466 chars omitted]…
d_argument(line: str) -> tuple[str, str | None] | None:
    """
    Extract a keyword, and its optional argument out of a sphinx field option line.

    For example
    >>> _get_sphinx_line_keyword_and_argument(":param parameter:")
    ("param", "parameter")
    >>> _get_sphinx_line_keyword_and_argument(":return:")
    ("return", None)
    >>> _get_sphinx_line_keyword_and_argument("some invalid line")

9.1.0

File "<frozen importlib._bootstrap>", line 1331, in _find_and_load_unlocked
  File "<frozen importlib._bootstrap>", line 935, in _load_unlocked
  File "<frozen importlib._bootstrap_external>", line 999, in exec_module
  File "<frozen importlib._bootstrap>", line 488, in _call_with_frames_removed
  File "/tmp/repro/pkg.py", line 7, in <module>
    class Foo(NamedTuple):
  File "/usr/local/lib/python3.12/typing.py", line 2841, in __new__
    raise AttributeError("Cannot overwrite NamedTuple attribute " + key)
AttributeError: Cannot overwrite NamedTuple attribute __new__

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/usr/local/lib/python3.12/site-packages/sphinx/ext/autodoc/_dynamic/_importer.py", line 131, in _import_from_module_and_path
    module = _import_module(module_name, try_reload=True)
             ^^^^^^^^^^
…[1105 chars omitted]…
 exec_module\n  File "<frozen importlib._bootstrap>", line 488, in _call_with_frames_removed\n  File "/tmp/repro/pkg.py", line 7, in <module>\n    class Foo(NamedTuple):\n  File "/usr/local/lib/python3.12/typing.py", line 2841, in __new__\n    raise AttributeError("Cannot overwrite NamedTuple attribute " + key)\nAttributeError: Cannot overwrite NamedTuple attribute __new__\n')
 [autodoc.import_object]

Traceback (most recent call last):
  File "<stdin>", line 2, in <module>
  File "/usr/local/lib/python3.12/typing.py", line 2841, in __new__
    raise AttributeError("Cannot overwrite NamedTuple attribute " + key)
AttributeError: Cannot overwrite NamedTuple attribute __new__

WARNING: error while formatting signature for pkg.Foo.__new__: Handler <function process_signature at 0x73e469df0180> for event 'autodoc-process-signature' threw an exception (exception: 'NoneType' object has no attribute 'Foo') [autodoc]

1 added, 0 changed, 0 removed
    reading sources... [100%]
    index

Loaded Extensions
=================

* sphinx.ext.mathjax (9.1.0)
* alabaster (1.0.0)
* sphinxcontrib.applehelp (2.0.0)
* sphinxcontrib.devhelp (2.0.0)
* sphinxcontrib.htmlhelp (2.1.0)

* sphinxcontrib.serializinghtml (2.0.0)
* sphinxcontrib.qthelp (2.0.0)
* sphinx.ext.autodoc (9.1.0)
* sphinx_autodoc_typehints (unknown version)

Traceback
=========

      File "/usr/local/lib/python3.12/site-packages/sphinx/events.py", line 452, in emit
        raise ExtensionError(
    sphinx.errors.ExtensionError: Handler <function process_docstring at 0x7d74df7d4900> for event 'autodoc-process-docstring' threw an exception (exception: wrapper loop when unwrapping <function circular at 0x7d74df8109a0>)


The full traceback has been saved in:
/tmp/sphinx-err-bebu0p4i.log

To report this error to the developers, please open an issue at <https://github.com/sphinx-doc/sphinx/issues/>. Thanks!
Please also report this if it was a user error, so that a better error message can be provided next time.

WARNING: error while formatting arguments for pkg.circular: wrapper loop when unwrapping <function circular at 0x733704e28ae0> [autodoc]

grep: /usr/local/lib/python3.12/site-packages/sphinx/ext/autodoc/_dynamic/__pycache__/_loader.cpython-312.pyc: binary file matches
grep: /usr/local/lib/python3.12/site-packages/sphinx/ext/autodoc/_dynamic/__pycache__/_signatures.cpython-312.pyc: binary file matches
grep: /usr/local/lib/python3.12/site-packages/sphinx/ext/autodoc/_legacy_class_based/__pycache__/_documenters.cpython-312.pyc: binary file matches
/usr/local/lib/python3.12/site-packages/sphinx/ext/autodoc/_dynamic/_loader.py:144:        msg = __('error while formatting signature for %s: %s')
/usr/local/lib/python3.12/site-packages/sphinx/ext/autodoc/_dynamic/_signatures.py:102:            msg = __('error while formatting arguments for %s: %s')
/usr/local/lib/python3.12/site-packages/sphinx/ext/autodoc/_legacy_class_based/_documenters.py:358:                    __('error while formatting arguments for %s: %s'),
/usr/local/lib/python3.12/site-packages/sphinx/ext/autodoc/_legacy_class_based/_documenters.py:882:                __('error while formatting signature for %s: %s'),

and config.autodoc_docstring_signature
        and props.obj_type not in {'module', 'data', 'type'}
        and docstrings is not None
    ):
        # only act if a signature is not explicitly given already,
        # and if the feature is enabled
        signatures[:] = _extract_signatures_from_docstrings(
            docstrings, props=props, tab_width=options._tab_width
        )

    if not signatures:
        # try to introspect the signature

        try:
            signatures[:] = _extract_signature_from_object(
                config=config,
                events=events,
                get_attr=get_attr,
                parent=parent,
                props=props,
                **kwargs,
            )
        except Exception as exc:
            msg = __('error while formatting arguments for %s: %s')
            LOGGER.warning(msg, props.full_name, exc, type='autodo
…[73 chars omitted]…
eep the return annotation
        signatures = [('', retann) for _args, retann in signatures]

    _record_typehints(
        autodoc_annotations=autodoc_annotations,
        name=props.full_name,
        obj=props._obj,
        short_literals=kwargs.get('short_literals', False),
        type_aliases=config.autodoc_type_aliases,
        unqualified_typehints=kwargs.get('unqualified_typehints', False),

76:def unwrap(obj: Any) -> Any:
82:        # Skip unwrapping mock object to avoid RecursionError
86:        return inspect.unwrap(obj)
92:def unwrap_all(obj: Any, *, stop: Callable[[Any], bool] | None = None) -> Any:
95:    Unlike :func:`unwrap`, this unwraps partial functions, wrapped functions,
99:    be unwrapped or not.
364:        unwrapped = unwrap(obj)
365:        if isfunction(unwrapped) or isbuiltin(unwrapped) or ismethod(unwrapped):
368:        if is_cython_function_or_method(unwrapped):
371:        if isclass(unwrapped):

163:def test_parse_annotation(annotation: Any, module: str, class_name: str, args: tuple[Any, ...]) -> None:
167:    assert (got_mod, got_cls, got_args) == (module, class_name, args)
407:def test_format_annotation(inv: Inventory, annotation: Any, expected_result: str) -> None:
410:    assert result == expected_result
426:        assert format_annotation(annotation, conf) == expected_result_not_simplified
437:            assert format_annotation(annotation, conf) == expected_result_not_simplified
451:        assert format_annotation(annotation, conf) == expected_result
463:        assert match.group("role") == expected_role
479:def test_always_use_bars_union(annotation: str, expected_result: str) -> None:
482:    assert result == expected_result
496:def test_format_annotation_both_libs(library: ModuleType, annotation: str, params: Any, expected_result: str) -> None:
505:    assert resu

…[2760 chars omitted]…
str(Path(__file__).parent) or ".").absolute() / "roots"


def pytest_ignore_collect(collection_path: Path, config: Config) -> bool | None:  # noqa: ARG001
    version_re = re.compile(r"_py(\d)(\d)\.py$")
    match = version_re.search(collection_path.name)
    if match:
        version = tuple(int(x) for x in match.groups())
        if sys.version_info < version:
            return True
    return None

e4d09ce base
test-dummy
test-integration
test-resolve-typing-guard
test-resolve-typing-guard-tmp

pytest.skip(f"{annotation} not available in the {library.__name__} module")
        return  # pragma: no cover

    ann = annotation_cls if params is None else annotation_cls[params]
    result = format_annotation(ann, create_autospec(Config))
    assert result == expected_result


def test_process_docstring_slot_wrapper() -> None:
    lines: list[str] = []
    config = create_autospec(
        Config,

        typehints_fully_qualified=False,
        simplify_optional_unions=False,
        typehints_formatter=None,
        autodoc_mock_imports=[],
    )
    app: Sphinx = create_autospec(Sphinx, config=config)
    process_docstring(app, "class", "SlotWrapper", Slotted, None, lines)
    assert not lines


def set_python_path() -> None:
    test_path = Path(__file__).parent
    # Add test directory to sys.path to allow imports of dummy module.
    if str(test_path) not in sys.pat
…[713 chars omitted]…
k()
    (Path(app.srcdir) / "index.rst").write_text(
        dedent(
            """
            .. autofunction:: dummy_module.undocumented_function

            .. autoclass:: dummy_module.DataClass
                :undoc-members:
                :special-members: __init__
            """,
        ),
    )

    app.build()

    assert "build succeeded" in status.getvalue()  # Build succeeded
conf.py

ismethod = inspect.ismethod
ismethoddescriptor = inspect.ismethoddescriptor
isclass = inspect.isclass
ismodule = inspect.ismodule


def unwrap(obj: Any) -> Any:
    """Get an original object from wrapped object (wrapped functions).

    Mocked objects are returned as is.
    """
    if hasattr(obj, '__sphinx_mock__'):

        # Skip unwrapping mock object to avoid RecursionError
        return obj

    try:
        return inspect.unwrap(obj)
    except ValueError:
        # might be a mock object
        return obj


def unwrap_all(obj: Any, *, stop: Callable[[Any], bool] | None = None) -> Any:
    """Get an original object from wrapped object.

    Unlike :func:`unwrap`, this unwraps partial functions, wrapped functions,
    class methods and static methods.

    When specified, *stop* is a predicate indicating whether an object should
    be unwrapped or not.
    """
    if callable(stop):
        while not stop(obj):
            if ispartial(obj):
                obj = obj.func
            elif inspect.isroutine(obj) and hasattr(obj, '__wrapped__'):
                obj = obj.__wrapped__  # pyright: ignore[reportFunctionMemberAccess]
            elif isclassmethod(obj) or isstaticmethod(obj):
                obj = obj.__func__
            else:
                return obj

"""Signature utilities for autodoc"""

from __future__ import annotations

import sys
from inspect import Parameter, Signature
from typing import TYPE_CHECKING, NewType, TypeVar

from sphinx.errors import PycodeError
from sphinx.ext.autodoc._dynamic._preserve_defaults import update_default_value
from sphinx.ext.autodoc._dynamic._type_annotations import _record_typehints
from sphinx.ext.autodoc._dynamic._type_comments import (

    _update_annotations_using_type_comments,
)
from sphinx.ext.autodoc._names import py_ext_sig_re
from sphinx.ext.autodoc._property_types import _AssignStatementProperties
from sphinx.ext.autodoc._shared import LOGGER
from sphinx.locale import __
from sphinx.pycode import ModuleAnalyzer
from sphinx.util import inspect
from sphinx.util.docstrings import prepare_docstring
from sphinx.util.inspect import (
    _stringify_signature_to_parts,
    evaluate_signature,

…[1888 chars omitted]…

309:            actual = inspect.signature(
319:                overload = evaluate_signature(
475:    obj, is_bound_method = _get_object_for_signature(
489:            return inspect.signature(
511:def _get_object_for_signature(
566:                inspect.signature(meth, bound_method=True, type_aliases=type_aliases)
610:        sig = inspect.signature(func, type_aliases=config.autodoc_type_aliases)

76:def unwrap(obj: Any) -> Any:
82:        # Skip unwrapping mock object to avoid RecursionError
86:        return inspect.unwrap(obj)
92:def unwrap_all(obj: Any, *, stop: Callable[[Any], bool] | None = None) -> Any:
95:    Unlike :func:`unwrap`, this unwraps partial functions, wrapped functions,
99:    be unwrapped or not.
364:        unwrapped = unwrap(obj)
365:        if isfunction(unwrapped) or isbuiltin(unwrapped) or ismethod(unwrapped):
368:        if is_cython_function_or_method(unwrapped):
371:        if isclass(unwrapped):
_DESCRIPTOR_LIKE: Final[tuple[type, ...]] = (
    ClassMethodDescriptorType,

    MethodDescriptorType,
    WrapperDescriptorType,
)


def isattributedescriptor(obj: Any) -> bool:
    """Check if the object is an attribute-like descriptor."""
    if inspect.isdatadescriptor(obj):
        # data descriptor is kind of attribute
        return True
    if isdes
…[471 chars omitted]…
be a class
            return False
        if isinstance(unwrapped, _DESCRIPTOR_LIKE):
            # attribute must not be a method descriptor
            return False
        # attribute must not be an instancemethod (C-API) nor nb_method (specific for nanobind)
        return type(unwrapped).__name__ not in {'instancemethod', 'nb_method'}
    return False

16:738-        if _should_unwrap(subject):

signature_kwds['annotation_format'] = annotationlib.Format.FORWARDREF


def signature(
    subject: _SignatureType,
    bound_method: bool = False,
    type_aliases: Mapping[str, str] | None = None,
) -> Signature:
    """Return a Signature object for the given *subject*.

    :param bound_method: Specify *subject* is a bound method or not.

    When *subject* is a built-in callable, *bound_method* is ignored.
    """
    if type_aliases is None:
        type_aliases = {}

    try:
        if _should_unwrap(subject):
            signature = inspect.signature(subject, **signature_kwds)  # type: ignore[arg-type]
        else:
            signature = inspect.signature(
                subject,  # type: ignore[arg-type]
                follow_wrapped=True,
                **signature_kwds,
            )
    except ValueError:
        # follow built-in wrappers up (ex. functools.lru_ca
…[276 chars omitted]…
_aliases.
        localns = TypeAliasNamespace(type_aliases)
        annotations = typing.get_type_hints(subject, None, localns, include_extras=True)
        for i, param in enumerate(parameters):
            if param.name in annotations:
                annotation = annotations[param.name]
                if isinstance(annotation, TypeAliasForwardRef):
                    annotation = annotation.name

sig err: wrapper loop when unwrapping <function circular at 0x78cc19402200>
fw err: wrapper loop when unwrapping <function circular at 0x78cc19402200>
plain err: wrapper loop when unwrapping <function circular at 0x78cc19402200>

WARNING: error while formatting arguments for pkg.circular: wrapper loop when unwrapping <function circular at 0x7a55197309a0> [autodoc]
build succeeded, 1 warning.

WARNING: error while formatting arguments for pkg.circular: wrapper loop when unwrapping <function circular at 0x730cf1060ae0> [autodoc]
build succeeded, 1 warning.

/usr/local/lib/python3.12/site-packages/sphinx/ext/autodoc/_dynamic/_signatures.py:20:from sphinx.util import inspect
/usr/local/lib/python3.12/site-packages/sphinx/ext/autodoc/_dynamic/_signatures.py:22:from sphinx.util.inspect import (
/usr/local/lib/python3.12/site-packages/sphinx/ext/autodoc/_legacy_class_based/_documenters.py:40:from sphinx.util import inspect
/usr/local/lib/python3.12/site-packages/sphinx/ext/autodoc/_legacy_class_based/_documenters.py:42:from sphinx.util.inspect import (

doctree = _parse_str_to_doctree(
  File "/usr/local/lib/python3.12/site-packages/sphinx/util/docutils.py", line 902, in _parse_str_to_doctree
    parser.parse(content, document)
  File "/usr/local/lib/python3.12/site-packages/sphinx/parsers.py", line 99, in parse
    self.statemachine.run(inputlines, document, inliner=self.inliner)
  File "/usr/local/lib/python3.12/site-packages/docutils/parsers/rst/states.py", line 182, in run
    results = StateMachineWS.run(self, input_lines, input_offset,
  File "/usr/local/lib/python3.12/site-packages/docutils/statemachine.py", line 234, in run
    context, next_state, result = self.check_line(
  File "/usr/local/lib/python3.12/site-packages/docutils/statemachine.py", line 446, in check_line
    return method(match, context, next_state)
  File "/usr/local/lib/python3.12/site-packages/docutils/parsers/rst/states.py", line 2487, in explicit_mar

…[1063 chars omitted]…
es
    LOGGER.warning(msg, props.full_name, exc, type='autodoc')
  File "<stdin>", line 5, in w
WARNING: error while formatting arguments for pkg.circular: wrapper loop when unwrapping <function circular at 0x78e7474b42c0> [autodoc]
WARN: ('error while formatting arguments for %s: %s', 'pkg.circular', ValueError('wrapper loop when unwrapping <function circular at 0x78e7474b42c0>')) {'type': 'autodoc'}

props: _ItemProperties,
    type_aliases: Mapping[str, str] | None,
    use_type_comments: bool,
) -> Signature | None:
    """Return a Signature for *obj*, or None on failure."""
    obj, is_bound_method = _get_object_for_signature(
        props=props, get_attr=get_attr, parent=parent, type_aliases=type_aliases
    )
    if obj is None or isinstance(obj, Signature):
        return obj

    if preserve_defaults:

        update_default_value(obj, bound_method=is_bound_method)
    if use_type_comments:
        _update_annotations_using_type_comments(obj, bound_method=is_bound_method)
    events.emit('autodoc-before-process-signature', obj, is_bound_method)

    if props.obj_type in {'class', 'exception', 'function', 'method', 'decorator'}:
        try:
            return inspect.signature(
                obj, bound_method=is_bound_method, type_aliases=type_aliases
            )
  
…[713 chars omitted]…
o `__text_signature__`.
            return None

    return None


def _get_object_for_signature(
    props: _ItemProperties,
    get_attr: _AttrGetter,
    parent: Any,
    type_aliases: Mapping[str, str] | None,
) -> tuple[Any, bool]:
    """Return the object from which we will obtain the signature."""
    obj = props._obj
    if props.obj_type in {'function', 'decorator'}:
        return obj, False

Traceback (most recent call last):
  File "/usr/local/lib/python3.12/site-packages/sphinx/ext/autodoc/_dynamic/_signatures.py", line 93, in _format_signatures
    signatures[:] = _extract_signature_from_object(
                    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.12/site-packages/sphinx/ext/autodoc/_dynamic/_signatures.py", line 417, in _extract_signature_from_object
    sig = _get_signature_object(
          ^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.12/site-packages/sphinx/ext/autodoc/_dynamic/_signatures.py", line 484, in _get_signature_object
    _update_annotations_using_type_comments(obj, bound_method=is_bound_method)
  File "/usr/local/lib/python3.12/site-packages/sphinx/ext/autodoc/_dynamic/_type_comments.py", line 108, in _update_annotations_using_type_comments
    type_sig = get_type_comment(obj, bound_method)
               ^^^^^^^^^

…[440 chars omitted]…
  object = unwrap(object)
             ^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.12/inspect.py", line 781, in unwrap
    raise ValueError('wrapper loop when unwrapping {!r}'.format(f))
ValueError: wrapper loop when unwrapping <function circular at 0x7869ba68c2c0>
WARNING: error while formatting arguments for pkg.circular: wrapper loop when unwrapping <function circular at 0x7869ba68c2c0> [autodoc]

"""Sphinx autodoc type hints."""

from __future__ import annotations

import ast
import importlib
import inspect
import re
import sys
import textwrap
import types
from dataclasses import dataclass

from typing import TYPE_CHECKING, Any, AnyStr, ForwardRef, NewType, TypeVar, Union, get_type_hints

from docutils import nodes
from docutils.frontend import get_default_settings
from sphinx.ext.autodoc.mock import mock  # type: ignore[attr-defined]
from sphinx.parsers import RSTParser
from sphinx.util import logging, rst
from sphinx.util.inspect import TypeAliasForwardRef, stringify_signature
from sphinx.util.inspect import signature as sphinx_signature

from ._parser import parse
from .patches import install_patches
from .version import __version__

if TYPE_CHECKING:
    from ast import FunctionDef, Module, stmt
    from collections.abc import Callable

    from docutils.nodes import Node
    from docutils.parsers.rst import states
    from sphinx.application import Sphinx
    from sphinx.config import Config
    from sphinx.environment import BuildEnvironment
    from sphinx.ext.autodoc import Options

_LOGGER = logging.getLogger(__name__)
_PYDATA_ANNOTS_TYPING = {
    "Any",
58:urls.Changelog = "https://github.com/tox-dev/sphinx-autodoc-typehints/releases"

424:        use_type_comments=config.autodoc_use_type_comments,
472:    use_type_comments: bool,
483:    if use_type_comments:

193:        'autodoc_use_type_comments', True, 'env', types=frozenset({bool})

ERROR: Could not find a version that satisfies the requirement sphinx-autodoc-typehints==1.27 (from versions: none)
ERROR: No matching distribution found for sphinx-autodoc-typehints==1.27

src/sphinx_autodoc_typehints/__init__.py | 20 +++++++++++++++++---
 1 file changed, 17 insertions(+), 3 deletions(-)
WARNING: error while formatting arguments for pkg.circular: wrapper loop when unwrapping <function circular at 0x77e6efc909a0> [autodoc]
build succeeded, 1 warning.

annotations.setdefault(attrname, annotation)
    except PycodeError:
        pass


def _update_annotations_using_type_comments(obj: Any, bound_method: bool) -> None:
    """Update annotations info of *obj* using type_comments."""
    try:
        type_sig = get_type_comment(obj, bound_method)
        if type_sig:
            sig = inspect.signature(obj, bound_method)
            for param in sig.parameters.values():

                if param.name not in obj.__annotations__:
                    annotation = type_sig.parameters[param.name].annotation
                    if annotation is not Parameter.empty:
                        obj.__annotations__[param.name] = ast_unparse(annotation)

            if 'return' not in obj.__annotations__:
                obj.__annotations__['return'] = type_sig.return_annotation
    except KeyError as exc:
        LOGGER.warning(
          
…[959 chars omitted]…
          subject = cast('ast.FunctionDef', module.body[0])

        type_comment = getattr(subject, 'type_comment', None)
        if type_comment:
            function = ast.parse(type_comment, mode='func_type', type_comments=True)
            return signature_from_ast(subject, bound_method, function)
        else:
            return None
    except (OSError, TypeError):  # failed to load source code

/usr/local/lib/python3.12/site-packages/sphinx/ext/autodoc/_dynamic/_type_comments.py:108:        type_sig = get_type_comment(obj, bound_method)
/usr/local/lib/python3.12/site-packages/sphinx/ext/autodoc/_dynamic/_type_comments.py:127:def get_type_comment(obj: Any, bound_method: bool = False) -> Signature | None:

build succeeded.

/usr/local/lib/python3.12/site-packages/sphinx/ext/napoleon/docstring.py:361: RemovedInSphinx11Warning: The mapping interface for autodoc options objects is deprecated, and will be removed in Sphinx 11. Use attribute access instead.
    if options:

-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
=========================== short test summary info ============================
ERROR tests/test_sphinx_autodoc_typehints.py::test_format_annotation[str] - u...
!!!!!!!!!!!!!!!!!!!!!!!!!! stopping after 1 failures !!!!!!!!!!!!!!!!!!!!!!!!!!!
216 passed, 464 warnings, 1 error in 16.07s

ERROR tests/test_sphinx_autodoc_typehints.py::test_format_annotation[Tuple-p-Ellipsis]
ERROR tests/test_sphinx_autodoc_typehints.py::test_format_annotation[Annotated-metadata]
ERROR tests/test_sphinx_autodoc_typehints.py::test_format_annotation[Required]
ERROR tests/test_sphinx_autodoc_typehints.py::test_format_annotation[NotRequired]
264 passed, 840 warnings, 80 errors in 41.51s
ERROR tests/test_sphinx_autodoc_typehints.py::test_format_annotation[Pattern-str]
ERROR tests/test_sphinx_autodoc_typehints.py::test_format_annotation[IO-str]
145 deselected, 18 errors in 4.85s

diff --git a/src/sphinx_autodoc_typehints/__init__.py b/src/sphinx_autodoc_typehints/__init__.py
index a7a020b..bf2bb1c 100644
--- a/src/sphinx_autodoc_typehints/__init__.py
+++ b/src/sphinx_autodoc_typehints/__init__.py
@@ -393,8 +393,17 @@ def process_signature(  # noqa: C901, PLR0913, PLR0917
     if not getattr(obj, "__annotations__", None):  # when has no annotation we cannot autodoc typehints so bail
         return None
 
-    obj = inspect.unwrap(obj)
-    sph_signature = sphinx_signature(obj, type_aliases=app.config["autodoc_type_aliases"])
+    try:
+        obj = inspect.unwrap(obj)

+        sph_signature = sphinx_signature(obj, type_aliases=app.config["autodoc_type_aliases"])
+    except (ValueError, TypeError):  # e.g. circular __wrapped__ chain -- cannot safely inspect
+        _LOGGER.warning(
+            'Cannot inspect signature of object: "%s" -- skipping signature 
…[2587 chars omitted]…
f fix_directive_based_signature_formatting() -> None:
     """
@@ -151,6 +176,7 @@ def install_patches(app: Sphinx) -> None:
     """
     # For Sphinx 9+ directive-based architecture
     fix_directive_based_signature_formatting()
+    _patch_type_comment_extraction()
     patch_attribute_handling(app)
     _patch_google_docstring_lookup_annotation()
     fix_napoleon_numpy_docstring_return_type(app)

build succeeded.
ERROR tests/test_sphinx_autodoc_typehints.py::test_format_annotation[NotRequired]
264 passed, 840 warnings, 80 errors in 37.53s

…[330 chars omitted]…
w builds cleanly; test suite matches the pre-existing baseline (264 passed; 80 pre-existing unrelated test_format_annotation errors also present on the base commit)."}
submitted.

LICENSE
README.md
ignore-words.txt
pyproject.toml
src
tests
tox.toml
whitelist.txt
ls: cannot access '/repo/sphinx/ext': No such file or directory

ls: cannot access '/repo/src/sphinx/ext': No such file or directory
grep: /repo/src/sphinx/util/inspect.py: No such file or directory

sphinx_autodoc_typehints
ls: cannot access '/repo/src/sphinx': No such file or directory

__init__.py
_parser.py
attributes_patch.py
patches.py
py.typed
version.py
/repo/src/sphinx_autodoc_typehints/__init__.py:20:from sphinx.util.inspect import TypeAliasForwardRef, stringify_signature
/repo/src/sphinx_autodoc_typehints/__init__.py:21:from sphinx.util.inspect import signature as sphinx_signature
/repo/src/sphinx_autodoc_typehints/__init__.py:367:def process_signature(  # noqa: C901, PLR0913, PLR0917
/repo/src/sphinx_autodoc_typehints/__init__.py:373:    signature: str,  # noqa: ARG001
/repo/src/sphinx_autodoc_typehints/__init__.py:377:    Process the signature.
/repo/src/sphinx_autodoc_typehints/__init__.py:384:    :param signature:

/repo/src/sphinx_autodoc_typehints/__init__.py:392:    obj = getattr(obj, "__init__", getattr(obj, "__new__", None)) if inspect.isclass(obj) else obj
/repo/src/sphinx_autodoc_typehints/__init__.py:396:    obj = inspect.unwrap(obj)
/repo/src/sph
…[3063 chars omitted]…
07:    "process_signature",
/repo/src/sphinx_autodoc_typehints/attributes_patch.py:16:    from sphinx.addnodes import desc_signature
/repo/src/sphinx_autodoc_typehints/attributes_patch.py:29:orig_handle_signature = PyAttribute.handle_signature
/repo/src/sphinx_autodoc_typehints/attributes_patch.py:49:def patched_handle_signature(self: PyAttribute, sig: str, signode: desc_signature) -> tuple[str, str]:

aligned_suffix = [whitespace + remove_prefix(s, whitespace) for s in lines[idx + 1 :]]

    # Put it together again
    aligned_prefix.append(fn_def)
    return "\n".join(aligned_prefix + aligned_suffix)


def process_signature(  # noqa: C901, PLR0913, PLR0917
    app: Sphinx,
    what: str,
    name: str,
    obj: Any,

    options: Options,  # noqa: ARG001
    signature: str,  # noqa: ARG001
    return_annotation: str,  # noqa: ARG001
) -> tuple[str, None] | None:
    """
    Process the signature.

    :param app:
    :param what:
    :param name:
    :param obj:
    :param options:
    :param signature:
    :param return_annotation:
    :return:
    """
    if not callable(obj):
        return None

    original_obj = obj
    obj = getattr(obj, "__init__", getattr(obj, "__new__", None)) if inspect.isclass(obj) else obj
    if not getattr(obj, "__annotations__", None):  # when h
…[4895 chars omitted]…
d_argument(line: str) -> tuple[str, str | None] | None:
    """
    Extract a keyword, and its optional argument out of a sphinx field option line.

    For example
    >>> _get_sphinx_line_keyword_and_argument(":param parameter:")
    ("param", "parameter")
    >>> _get_sphinx_line_keyword_and_argument(":return:")
    ("return", None)
    >>> _get_sphinx_line_keyword_and_argument("some invalid line")

67:# types has a bunch of things like ModuleType where ModuleType.__module__ is
105:    if hasattr(annotation, "__module__"):
106:        return annotation.__module__  # type: ignore[no-any-return]
108:        return annotation.__origin__.__module__  # type: ignore[no-any-return]
165:        original = getattr(sys.modules[module], class_name)
434:            outer = inspect.getmodule(obj)
466:    annotations_ = getattr(inspect.getmodule(obj), "annotations", None)
502:    if hasattr(obj, "__module__"):
503:        return obj.__module__ in _TYPE_GUARD_IMPORTS_RESOLVED or obj.__module__ in sys.builtin_module_names
537:    module = inspect.getmodule(obj)

if module in {"typing", "typing_extensions"} and isinstance(getattr(annotation, "name", None), str):
        # Required for at least Pattern and Match
        return annotation.name  # type: ignore[no-any-return]

    origin = getattr(annotation, "__origin__", None)
    if origin:
        if getattr(origin, "__qualname__", None):  # Required for Protocol subclasses
            return origin.__qualname__  # type: ignore[no-any-return]
        if getattr(origin, "_name", None):  # Required for Union on Python 3.7+
            return origin._name  # type: ignore[no-any-return]  # noqa: SLF001

    annotation_cls = annotation if inspect.isclass(annotation) else type(annotation)

    return annotation_cls.__qualname__.lstrip("_")


def get_annotation_args(annotation: Any, module: str, class_name: str) -> tuple[Any, ...]:  # noqa: PLR0911
    """
    Get annotation arguments.

    :param
…[1950 chars omitted]…
uteError, TypeError, RecursionError) as exc:
        # TypeError - slot wrapper, PEP-563 when part of new syntax not supported
        # RecursionError - some recursive type definitions https://github.com/python/typing/issues/574
        if isinstance(exc, TypeError) and _future_annotations_imported(obj) and "unsupported operand type" in str(exc):
            result = obj.__annotations__
        else:

conftest.py
roots
test_integration.py
test_integration_autodoc_type_aliases.py
test_integration_issue_384.py
test_sphinx_autodoc_typehints.py
test_version.py

from __future__ import annotations

import re
import shutil
import sys
from contextlib import suppress
from pathlib import Path
from typing import TYPE_CHECKING

import pytest
from sphobjinv import Inventory

if TYPE_CHECKING:
    from _pytest.config import Config

pytest_plugins = "sphinx.testing.fixtures"
collect_ignore = ["roots"]


@pytest.fixture(scope="session")
def inv(pytestconfig: Config) -> Inventory:
    cache_path = f"python{sys.version_info.major}.{sys.version_info.minor}/objects.inv"
    assert pytestconfig.cache is not None
    inv_dict = pytestconfig.cache.get(cache_path, None)
    if inv_dict is not None:
        return Inventory(inv_dict)

    url = f"https://docs.python.org/{sys.version_info.major}.{sys.version_info.minor}/objects.inv"
    inv = Inventory(url=url)
    pytestconfig.cache.set(cache_path, inv.json_dict())
    return inv


@pytest.fixture(autouse=True)

…[565 chars omitted]…
collection_path: Path, config: Config) -> bool | None:  # noqa: ARG001
    version_re = re.compile(r"_py(\d)(\d)\.py$")
    match = version_re.search(collection_path.name)
    if match:
        version = tuple(int(x) for x in match.groups())
        if sys.version_info < version:
            return True
    return None
test-dummy
test-integration
test-resolve-typing-guard
test-resolve-typing-guard-tmp

None
DOC ERR: ValueError wrapper loop when unwrapping <function <lambda> at 0x79fa2226eb60>
NT SIG ERR: AttributeError 'dict' object has no attribute 'typehints_use_signature_return'
NT DOC ERR: AttributeError 'dict' object has no attribute 'autodoc_mock_imports'

sig: None
DOC ERR: ValueError wrapper loop when unwrapping <function <lambda> at 0x77ecc9fbf420>
NT SIG ERR: AttributeError 'NoneType' object has no attribute 'NT'
NT DOC ERR: AttributeError 'Cfg' object has no attribute '_annotation_globals'

ok

sig: None
doc ok []
nt sig: None
Traceback (most recent call last):
  File "<stdin>", line 6, in __getattr__
KeyError: 'always_document_param_types'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/repo/src/sphinx_autodoc_typehints/__init__.py", line 754, in process_docstring
    _inject_types_to_docstring(type_hints, signature, original_obj, app, what, name, lines)

  File "/repo/src/sphinx_autodoc_typehints/__init__.py", line 810, in _inject_types_to_docstring
    _inject_signature(type_hints, signature, app, lines)
  File "/repo/src/sphinx_autodoc_typehints/__init__.py", line 822, in _inject_signature
    _inject_arg_signature(type_hints, signature, app, lines, arg_name)
  File "/repo/src/sphinx_autodoc_typehints/__init__.py", line 848, in _inject_arg_signature
    if annotation is not None and insert_index is None and
…[166 chars omitted]…
n __getattr__
AttributeError: always_document_param_types

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "<stdin>", line 28, in <module>
  File "/repo/src/sphinx_autodoc_typehints/__init__.py", line 756, in process_docstring
    delattr(app.config, "_annotation_globals")
AttributeError: 'Cfg' object has no attribute '_annotation_globals'

Traceback (most recent call last):
  File "<stdin>", line 17, in <module>
  File "/repo/src/sphinx_autodoc_typehints/__init__.py", line 756, in process_docstring
    delattr(app.config, "_annotation_globals")
AttributeError: 'Cfg' object has no attribute '_annotation_globals'

/usr/local/lib/python3.12/urllib/request.py:1347: URLError
=========================== short test summary info ============================
ERROR tests/test_sphinx_autodoc_typehints.py::test_format_annotation[str] - u...
!!!!!!!!!!!!!!!!!!!!!!!!!! stopping after 1 failures !!!!!!!!!!!!!!!!!!!!!!!!!!!
36 passed, 1 error in 0.54s

ERROR tests/test_sphinx_autodoc_typehints.py::test_format_annotation[Tuple-p-int-int]
ERROR tests/test_sphinx_autodoc_typehints.py::test_format_annotation[Tuple-p-Ellipsis]
ERROR tests/test_sphinx_autodoc_typehints.py::test_format_annotation[Annotated-metadata]
ERROR tests/test_sphinx_autodoc_typehints.py::test_format_annotation[Required]
ERROR tests/test_sphinx_autodoc_typehints.py::test_format_annotation[NotRequired]
264 passed, 1 deselected, 840 warnings, 79 errors in 22.02s

Saved working directory and index state WIP on master: 3d969ed base
ERROR tests/test_sphinx_autodoc_typehints.py::test_format_annotation[Required]
ERROR tests/test_sphinx_autodoc_typehints.py::test_format_annotation[NotRequired]
264 passed, 840 warnings, 80 errors in 21.66s
On branch master
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
	modified:   src/sphinx_autodoc_typehints/__init__.py

no changes added to commit (use "git add" and/or "git commit -a")
Dropped refs/stash@{0} (3c1ae6369f37fe6482f33a6bd6dd8c3b42416be5)

diff --git a/src/sphinx_autodoc_typehints/__init__.py b/src/sphinx_autodoc_typehints/__init__.py
index a7a020b..fe5837d 100644
--- a/src/sphinx_autodoc_typehints/__init__.py
+++ b/src/sphinx_autodoc_typehints/__init__.py
@@ -393,8 +393,11 @@ def process_signature(  # noqa: C901, PLR0913, PLR0917
     if not getattr(obj, "__annotations__", None):  # when has no annotation we cannot autodoc typehints so bail
         return None
 
-    obj = inspect.unwrap(obj)
-    sph_signature = sphinx_signature(obj, type_aliases=app.config["autodoc_type_aliases"])
+    try:
+        obj = inspect.unwrap(obj)

+        sph_signature = sphinx_signature(obj, type_aliases=app.config["autodoc_type_aliases"])
+    except ValueError:  # e.g. circular __wrapped__ reference
+        return None
     typehints_formatter: Callable[..., str | None] | None = getattr(app.config, "typehints_formatter", None)
 
    
…[523 chars omitted]…
 process_docstring(  # noqa: PLR0913, PLR0917
     if not callable(obj):
         return
     obj = obj.__init__ if inspect.isclass(obj) else obj
-    obj = inspect.unwrap(obj)
+    try:
+        obj = inspect.unwrap(obj)
+    except ValueError:  # e.g. circular __wrapped__ reference
+        return
 
     try:
         signature = sphinx_signature(obj, type_aliases=app.config["autodoc_type_aliases"])

…[89 chars omitted]…
ead of raising AttributeError on NoneType. Reproducers confirmed fixed; test suite matches baseline (264 passed; only pre-existing network-dependent fixture errors)."}
submitted.