sphinx-codeautolink 0.17.5__tar.gz → 0.18.0__tar.gz

{sphinx_codeautolink-0.17.5 → sphinx_codeautolink-0.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sphinx-codeautolink
-Version: 0.17.5
+Version: 0.18.0
 Summary: Automatic links from code examples to reference documentation.
 Author-email: Felix Hildén <felix.hilden@gmail.com>
 Maintainer-email: Felix Hildén <felix.hilden@gmail.com>
@@ -19,6 +19,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Documentation
 Classifier: Topic :: Documentation :: Sphinx
 Classifier: Topic :: Software Development :: Documentation

{sphinx_codeautolink-0.17.5 → sphinx_codeautolink-0.18.0}/docs/src/about.rst

@@ -85,6 +85,28 @@ The extension parses code blocks in the ``doctree-read`` Sphinx event.
 The priority is set to 490 to catch nodes removed by ``sphinx.ext.doctest``
 (priority 500). In other cases the priority of the extension is default.
 
+Type checking blocks
+********************
+To resolve annotations that reference names imported under
+``if TYPE_CHECKING:``, the extension re-executes the bodies of those gated
+blocks in the importing module's own namespace the first time it inspects
+that module. Without this step, ``typing.get_type_hints`` would fail with
+``NameError`` because, at runtime, ``TYPE_CHECKING`` is ``False`` and the
+gated names are never bound.
+
+A few things to be aware of:
+
+- Only top-level ``if`` blocks whose condition is ``TYPE_CHECKING`` or
+  ``MYPY`` (as a bare name or attribute access, e.g. ``typing.TYPE_CHECKING``)
+  are recognised. The condition is matched by AST shape, not evaluated.
+- The original module objects are mutated in place:
+  names that would normally only exist for type checkers become real
+  attributes on the module.
+- Bodies are executed with the equivalent of ``exec`` in the module's
+  globals. If execution fails, for example due to a cyclic import or
+  a missing optional dependency, that block is silently skipped and the rest
+  of the module continues to work.
+
 Copying code blocks
 -------------------
 If you feel like code links make copying code a bit more difficult,

{sphinx_codeautolink-0.17.5 → sphinx_codeautolink-0.18.0}/docs/src/release_notes.rst

@@ -8,6 +8,15 @@ These release notes are based on
 sphinx-codeautolink adheres to
 `Semantic Versioning <https://semver.org>`_.
 
+0.18.0 (2026-04-25)
+-------------------
+- Support module attributes and class aliases (:issue:`65`)
+- Resolve for-loop iterables into targets. ``for target in lib.iterable():``
+  now links ``target.method()`` in the loop body (:issue:`196`)
+- Resolve return annotations that reference names imported inside
+  ``if TYPE_CHECKING:`` and similar blocks (:issue:`197`)
+- Support Python 3.14 officially (:issue:`198`)
+
 0.17.5 (2025-07-09)
 -------------------
 - Add ``Python`` to default lexers (:issue:`194`)

{sphinx_codeautolink-0.17.5 → sphinx_codeautolink-0.18.0}/pyproject.toml

@@ -30,6 +30,7 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Documentation",
     "Topic :: Documentation :: Sphinx",
     "Topic :: Software Development :: Documentation",

{sphinx_codeautolink-0.17.5 → sphinx_codeautolink-0.18.0}/src/sphinx_codeautolink/__init__.py

@@ -8,7 +8,7 @@ from .extension import SphinxCodeAutoLink, backref, directive
 from .extension.block import clean_ipython, clean_pycon
 from .extension.translation import MESSAGE_CATALOG_NAME
 
-__version__ = "0.17.5"
+__version__ = "0.18.0"
 
 
 def setup(app: Sphinx):

sphinx_codeautolink-0.18.0/src/sphinx_codeautolink/extension/resolve.py

@@ -0,0 +1,307 @@
+"""Resolve import locations and type hints."""
+
+from __future__ import annotations
+
+import ast
+import inspect
+from collections import abc
+from collections.abc import Callable
+from contextlib import suppress
+from dataclasses import dataclass
+from functools import cache
+from importlib import import_module
+from inspect import isclass, ismodule, isroutine
+from types import ModuleType, UnionType
+from typing import Any, Union, get_type_hints
+
+from sphinx_codeautolink.parse import Name, NameBreak
+
+# Containers whose first generic argument is the element type produced
+# by iteration. ``tuple`` only fits ``tuple[T, ...]``; for mixed tuples
+# like ``tuple[int, str]`` we pick the first arg, which may be wrong.
+ITERABLE_ORIGINS = frozenset(
+    {
+        abc.Iterable,
+        abc.Iterator,
+        abc.Generator,
+        abc.AsyncIterable,
+        abc.AsyncIterator,
+        abc.AsyncGenerator,
+        abc.Collection,
+        abc.Sequence,
+        abc.MutableSequence,
+        abc.Set,
+        abc.MutableSet,
+        abc.Mapping,
+        abc.MutableMapping,
+        list,
+        set,
+        frozenset,
+        tuple,
+        dict,
+    }
+)
+
+
+def resolve_location(chain: Name, inventory) -> str:
+    """Find the final type that a name refers to."""
+    segments: list[tuple[list[str], NameBreak | None]] = []
+    current: list[str] = []
+    for comp in chain.import_components:
+        if comp in (NameBreak.call, NameBreak.for_iter):
+            segments.append((current, NameBreak(comp)))
+            current = []
+        else:
+            current.append(comp)
+    segments.append((current, None))
+
+    cursor = None
+    last = len(segments) - 1
+    for i, (segment, terminator) in enumerate(segments):
+        comps = segment
+        if cursor is None:
+            try:
+                comps, cursor = make_cursor(comps)
+            except CouldNotResolve:
+                if i == last:
+                    # Last ditch effort to locate based on the string only
+                    return ".".join(comps)
+                raise
+        cursor = locate_type(cursor, tuple(comps), inventory)
+        if terminator == NameBreak.call:
+            call_value(cursor)
+        elif terminator == NameBreak.for_iter:
+            iter_value(cursor)
+    return cursor.location if cursor is not None else None
+
+
+class CouldNotResolve(Exception):  # noqa: N818
+    """Could not resolve type to inventory."""
+
+
+@dataclass
+class Cursor:
+    """Cursor to follow a component path to the final type."""
+
+    location: str
+    value: Any
+    instance: bool
+    annotation: Any = None
+
+
+def make_cursor(components: list[str]) -> tuple[list[str], Cursor]:
+    """Divide components into module and rest, create cursor for following the rest."""
+    value, index = closest_module(tuple(components))
+    location = ".".join(components[:index])
+    return components[index:], Cursor(location, value, instance=False)
+
+
+def locate_type(cursor: Cursor, components: tuple[str, ...], inventory) -> Cursor:
+    """Find type hint and resolve to new location."""
+    previous = cursor
+    for i, component in enumerate(components):
+        previous = cursor
+
+        # When descending through an instance or alias
+        # try to normalise to the original type if possible
+        if previous.value is not None and not (
+            isclass(previous.value)
+            or ismodule(previous.value)
+            or isroutine(previous.value)
+        ):
+            with suppress(AttributeError, TypeError):
+                previous.value = type(previous.value)
+                previous.location = fully_qualified_name(previous.value)
+
+        annotation = None
+        with suppress(NameError, TypeError):
+            annotation = get_type_hints(previous.value).get(component)
+        cursor = Cursor(
+            previous.location + "." + component,
+            getattr(previous.value, component, None),
+            previous.instance,
+            annotation=annotation,
+        )
+
+        if cursor.value is None:
+            msg = f"{cursor.location} does not exist."
+            raise CouldNotResolve(msg)
+
+        if isclass(cursor.value):
+            cursor.instance = False
+
+        if isclass(cursor.value) or (
+            isroutine(cursor.value) and cursor.location not in inventory
+        ):
+            # Normalise location of type or imported function
+            # If odd construct encountered: don't try to be clever but continue
+            with suppress(AttributeError, TypeError):
+                cursor.location = fully_qualified_name(cursor.value)
+
+        # Check bases if member not found in current class
+        if isclass(previous.value) and cursor.location not in inventory:
+            for val in previous.value.__mro__[1:]:
+                name = fully_qualified_name(val)
+                if name + "." + component in inventory:
+                    previous.location = name
+                    return locate_type(previous, components[i:], inventory)
+
+    return cursor
+
+
+def call_value(cursor: Cursor) -> None:
+    """Call class, instance or function."""
+    if isclass(cursor.value) and not cursor.instance:
+        # class definition: "instantiate" class
+        cursor.instance = True
+        return
+
+    if callable(cursor.value) and not isroutine(cursor.value):
+        # callable class instance
+        cursor.value = cursor.value.__call__
+    elif not isroutine(cursor.value):
+        raise CouldNotResolve  # not a function either
+
+    annotation = get_return_annotation(cursor.value)
+    type_ = origin_type(annotation)
+    if not isinstance(type_, type):
+        msg = f"Unable to follow return annotation of {annotation!r}."
+        raise CouldNotResolve(msg)
+    cursor.value = type_
+    cursor.location = fully_qualified_name(type_)
+    cursor.instance = True
+    cursor.annotation = annotation
+
+
+def iter_value(cursor: Cursor) -> None:
+    """Unwrap the iterable cursor points to into its element type."""
+    element = unwrap_iterable(strip_optional(cursor.annotation))
+    if not isinstance(element, type):
+        msg = (
+            f"Unable to unwrap iterable element type of"
+            f" {get_name_for_debugging(cursor.value)}."
+        )
+        raise CouldNotResolve(msg)
+    cursor.value = element
+    cursor.location = fully_qualified_name(element)
+    cursor.instance = True
+    cursor.annotation = None
+
+
+def strip_optional(annotation: Any) -> Any:
+    """Reduce ``Optional[T]`` / ``T | None`` to ``T``; otherwise return as-is."""
+    origin = getattr(annotation, "__origin__", None)
+    args = getattr(annotation, "__args__", None)
+    if (origin is Union or isinstance(annotation, UnionType)) and args:
+        non_none = [a for a in args if a is not type(None)]
+        if len(non_none) == 1:
+            return non_none[0]
+    return annotation
+
+
+def origin_type(annotation: Any) -> Any:
+    """Return underlying type of an annotation (e.g. ``list`` from ``list[Foo]``)."""
+    return getattr(annotation, "__origin__", None) or annotation
+
+
+def unwrap_iterable(annotation: Any) -> type | None:
+    """Return the element type of an iterable annotation, or None."""
+    origin = getattr(annotation, "__origin__", None)
+    args = getattr(annotation, "__args__", None)
+    if origin in ITERABLE_ORIGINS and args:
+        return args[0]
+    return None
+
+
+def get_return_annotation(func: Callable) -> Any:
+    """Determine the target of a function return type hint."""
+    try:
+        annotation = get_type_hints(func).get("return")
+    except (NameError, TypeError) as e:
+        msg = f"Unable to follow return annotation of {get_name_for_debugging(func)}."
+        raise CouldNotResolve(msg) from e
+    if not annotation:
+        msg = f"No return annotation on {get_name_for_debugging(func)}."
+        raise CouldNotResolve(msg)
+    return strip_optional(annotation)
+
+
+def fully_qualified_name(thing: type | Callable) -> str:
+    """Construct the fully qualified name of a type."""
+    return thing.__module__ + "." + thing.__qualname__
+
+
+def get_name_for_debugging(thing: type | Callable) -> str:
+    """Construct the fully qualified name or some readable information of a type."""
+    try:
+        return fully_qualified_name(thing)
+    except (AttributeError, TypeError):
+        return repr(thing)
+
+
+@cache
+def closest_module(components: tuple[str, ...]) -> tuple[Any, int]:
+    """Find closest importable module."""
+    try:
+        mod = import_module(components[0])
+    except ImportError as e:
+        msg = f"Could not import {components[0]}."
+        raise CouldNotResolve(msg) from e
+    populate_type_checking(mod)
+
+    for i in range(1, len(components)):
+        try:
+            mod = import_module(".".join(components[: i + 1]))
+        except ImportError:
+            # import failed, exclude previously added item
+            return mod, i
+        populate_type_checking(mod)
+    # imports succeeded, include all items
+    return mod, len(components)
+
+
+populated_modules: set[int] = set()
+
+
+def populate_type_checking(mod: ModuleType) -> None:
+    """
+    Execute top-level TYPE_CHECKING blocks into ``mod.__dict__``.
+
+    At runtime TYPE_CHECKING is False, so names imported under such gates
+    are never bound on the module. ``get_type_hints`` then fails to resolve
+    annotations that reference them. Re-execute the gated bodies in the
+    module's own namespace so those names become available.
+    """
+    if id(mod) in populated_modules:
+        return
+    populated_modules.add(id(mod))
+
+    try:
+        source = inspect.getsource(mod)
+    except (OSError, TypeError):
+        return
+
+    tree = ast.parse(source)
+
+    filename = getattr(mod, "__file__", None) or "<type_checking>"
+    for node in tree.body:
+        if not isinstance(node, ast.If) or not is_type_checking_test(node.test):
+            continue
+        body = ast.Module(body=node.body, type_ignores=[])
+        # Catch e.g. optional deps and cyclic imports
+        with suppress(Exception):
+            exec(compile(body, filename, "exec"), mod.__dict__)  # noqa: S102
+
+
+def is_type_checking_test(expr: ast.expr) -> bool:
+    """
+    Determine if expr is a test for type checking.
+
+    Mirror mypy's ``infer_condition_value``: match a bare name or any
+    attribute access regardless of qualifier.
+    """
+    if isinstance(expr, ast.Name):
+        return expr.id in ("TYPE_CHECKING", "MYPY")
+    if isinstance(expr, ast.Attribute):
+        return expr.attr in ("TYPE_CHECKING", "MYPY")
+    return False

{sphinx_codeautolink-0.17.5 → sphinx_codeautolink-0.18.0}/src/sphinx_codeautolink/parse.py

@@ -94,6 +94,7 @@ class NameBreak(str, Enum):
     call = "()"
     namedexpr = ":="
     import_from = ">"
+    for_iter = "<>"
 
 
 class LinkContext(str, Enum):
@@ -499,9 +500,19 @@ class ImportTrackerVisitor(ast.NodeVisitor):
         self.visit_For(node)
 
     def visit_For(self, node: ast.For | ast.AsyncFor) -> None:
-        """Swap node order."""
-        self.visit(node.iter)
-        self.visit(node.target)
+        """Swap node order and resolve iterators."""
+        iter_pending = self.visit(node.iter)
+
+        if (
+            isinstance(iter_pending, PendingAccess)
+            and iter_pending.components
+            and isinstance(node.target, ast.Name)
+        ):
+            marker = Component(NameBreak.for_iter.value, *linenos(node), "load")
+            self.assign_name(node.target.id, [*iter_pending.components, marker])
+        else:
+            self.visit(node.target)
+
         for n in node.body:
             self.visit(n)
         for n in node.orelse:

{sphinx_codeautolink-0.17.5 → sphinx_codeautolink-0.18.0}/src/sphinx_codeautolink.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sphinx-codeautolink
-Version: 0.17.5
+Version: 0.18.0
 Summary: Automatic links from code examples to reference documentation.
 Author-email: Felix Hildén <felix.hilden@gmail.com>
 Maintainer-email: Felix Hildén <felix.hilden@gmail.com>
@@ -19,6 +19,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Documentation
 Classifier: Topic :: Documentation :: Sphinx
 Classifier: Topic :: Software Development :: Documentation

{sphinx_codeautolink-0.17.5 → sphinx_codeautolink-0.18.0}/src/sphinx_codeautolink.egg-info/SOURCES.txt

@@ -131,6 +131,7 @@ tests/extension/ref/ref_class_type_attr.txt
 tests/extension/ref/ref_decorator.txt
 tests/extension/ref/ref_fluent_attrs.txt
 tests/extension/ref/ref_fluent_call.txt
+tests/extension/ref/ref_for_loop.txt
 tests/extension/ref/ref_func_args.txt
 tests/extension/ref/ref_func_no_module.txt
 tests/extension/ref/ref_import_as.txt
@@ -146,10 +147,14 @@ tests/extension/ref/ref_inherited.txt
 tests/extension/ref/ref_intersphinx_only.txt
 tests/extension/ref/ref_invalid_func.txt
 tests/extension/ref/ref_invalid_typehint.txt
+tests/extension/ref/ref_module_attribute.txt
+tests/extension/ref/ref_module_attribute_builtin.txt
+tests/extension/ref/ref_module_attribute_class.txt
 tests/extension/ref/ref_optional.txt
 tests/extension/ref/ref_optional_future.txt
 tests/extension/ref/ref_shadow_builtin.txt
 tests/extension/ref/ref_simple.txt
+tests/extension/ref/ref_type_checking_gated.txt
 tests/extension/ref/search_css_duplicates_removed.txt
 tests/extension/ref/skip_file.txt
 tests/extension/ref/skip_next.txt
@@ -161,6 +166,8 @@ tests/extension/src/future_project.py
 tests/extension/src/parser_func.py
 tests/extension/src/test_project/__init__.py
 tests/extension/src/test_project/sub.py
+tests/extension/src/type_checking/__init__.py
+tests/extension/src/type_checking/foo.py
 tests/extension/table/tab_autodoc_empty.txt
 tests/extension/table/tab_autodoc_links.txt
 tests/extension/table/tab_manual_collapse.txt

sphinx_codeautolink-0.18.0/tests/extension/ref/ref_for_loop.txt

@@ -0,0 +1,26 @@
+test_project
+test_project.mod_list
+a.meth
+test_project.mod_typing_list
+b.meth
+test_project.iter_foos
+c.meth
+# split
+# split
+Test project
+============
+
+.. code:: python
+
+   import test_project
+
+   for a in test_project.mod_list:
+       a.meth()
+
+   for b in test_project.mod_typing_list:
+       b.meth()
+
+   for c in test_project.iter_foos():
+       c.meth()
+
+.. automodule:: test_project

sphinx_codeautolink-0.18.0/tests/extension/ref/ref_module_attribute.txt

@@ -0,0 +1,13 @@
+test_project
+test_project.mod_attr.attr
+# split
+# split
+Test project
+============
+
+.. code:: python
+
+   import test_project
+   test_project.mod_attr.attr
+
+.. automodule:: test_project

sphinx_codeautolink-0.18.0/tests/extension/ref/ref_module_attribute_builtin.txt

@@ -0,0 +1,13 @@
+test_project
+# split
+codeautolink_warn_on_missing_inventory = False
+# split
+Test project
+============
+
+.. code:: python
+
+   import test_project
+   test_project.mod_int.bit_length()
+
+.. automodule:: test_project

sphinx_codeautolink-0.18.0/tests/extension/ref/ref_module_attribute_class.txt

@@ -0,0 +1,13 @@
+test_project
+test_project.mod_type.attr
+# split
+# split
+Test project
+============
+
+.. code:: python
+
+   import test_project
+   test_project.mod_type.attr
+
+.. automodule:: test_project

sphinx_codeautolink-0.18.0/tests/extension/ref/ref_type_checking_gated.txt

@@ -0,0 +1,15 @@
+type_checking
+type_checking.pick
+attr
+# split
+# split
+Test project
+============
+
+.. code:: python
+
+   import type_checking
+   type_checking.pick(["a"]).attr
+
+.. automodule:: type_checking
+.. automodule:: type_checking.foo

{sphinx_codeautolink-0.17.5 → sphinx_codeautolink-0.18.0}/tests/extension/src/test_project/__init__.py

@@ -1,5 +1,8 @@
 """Docstring."""
 
+from collections.abc import Iterator
+from typing import List  # noqa: UP035
+
 from .sub import SubBar, subfoo  # noqa: F401
 
 
@@ -25,10 +28,30 @@ class Foo:
         """Test call."""
 
 
+mod_attr: Foo = Foo()
+"""Module attribute."""
+
+mod_int: int = 0
+"""Module attribute with a builtin type."""
+
+mod_type = Foo
+"""Module attribute whose value is a class, not an instance."""
+
+mod_list: list[Foo] = []
+"""Module list attribute."""
+
+mod_typing_list: List[Foo] = []  # noqa: UP006
+"""Typing module list attribute."""
+
+
 def bar() -> Foo:
     """Bar test function."""
 
 
+def iter_foos() -> "Iterator[Foo]":
+    """Return an iterator of Foos."""
+
+
 def optional() -> Foo | None:
     """Return optional type."""
 

sphinx_codeautolink-0.18.0/tests/extension/src/type_checking/__init__.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+import typing
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Collection
+
+if typing.TYPE_CHECKING:
+    from .foo import Foo
+
+if False:
+    pass
+
+
+def pick(items: Collection[str]) -> Foo:
+    """Return value whose annotation references a name guarded by
+    ``if TYPE_CHECKING: ...``
+    """

sphinx_codeautolink-0.18.0/tests/extension/src/type_checking/foo.py

@@ -0,0 +1,4 @@
+class Foo:
+    """Foo test class."""
+
+    attr: str = "test"

{sphinx_codeautolink-0.17.5 → sphinx_codeautolink-0.18.0}/tests/parse/assign.py

@@ -298,7 +298,7 @@ class TestAssignLike:
         return s, refs
 
     @refs_equal
-    def test_for_uses_imported(self):
+    def test_for_uses_imported_but_target_unused(self):
         s = "import a\nfor b in a:\n  a"
         refs = [("a", "a"), ("a", "a"), ("a", "a")]
         return s, refs
@@ -312,6 +312,30 @@ class TestAssignLike:
     @refs_equal
     def test_for_uses_and_overwrites_imported(self):
         s = "import a\nfor a in a:\n  a"
+        refs = [("a", "a"), ("a", "a"), ("a.<>", "a")]
+        return s, refs
+
+    @refs_equal
+    def test_for_target_bound_to_iter_name_element(self):
+        s = "import a\nfor b in a:\n  b"
+        refs = [("a", "a"), ("a", "a"), ("a.<>", "b")]
+        return s, refs
+
+    @refs_equal
+    def test_for_target_bound_to_iter_call_element(self):
+        s = "import a\nfor b in a():\n  b"
+        refs = [("a", "a"), ("a", "a"), ("a.().<>", "b")]
+        return s, refs
+
+    @refs_equal
+    def test_for_target_bound_to_iter_attribute_element(self):
+        s = "import a\nfor b in a.x:\n  b"
+        refs = [("a", "a"), ("a.x", "a.x"), ("a.x.<>", "b")]
+        return s, refs
+
+    @refs_equal
+    def test_for_tuple_target_not_bound(self):
+        s = "import a\nfor b, c in a():\n  b"
         refs = [("a", "a"), ("a", "a")]
         return s, refs