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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sphinx-codeautolink
-Version: 0.18.0
+Version: 0.19.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>

{sphinx_codeautolink-0.18.0 → sphinx_codeautolink-0.19.0}/docs/src/reference.rst

@@ -55,6 +55,15 @@ Configuration
    Useful when objects are imported and documented somewhere else than their
    original location as advertised by ``__module__``.
 
+.. confval:: codeautolink_disable_link_titles
+
+   Type: ``bool``. Don't add a ``title`` attribute, shown as a tooltip on
+   hover, to code links. By default the title contains the resolved location
+   of the linked object, but only when it differs from the code that is being
+   linked: hovering over ``instance.method()`` shows ``module.Class.method``,
+   while hovering over ``module.Class`` adds no tooltip.
+   Defaults to :code:`False`.
+
 .. confval:: codeautolink_warn_on_missing_inventory
 
    Type: ``bool``. Warn when an object cannot be found in

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

@@ -8,6 +8,23 @@ These release notes are based on
 sphinx-codeautolink adheres to
 `Semantic Versioning <https://semver.org>`_.
 
+0.19.0 (2026-07-29)
+-------------------
+- Only add a hover title to links when the resolved location of the object
+  differs from the linked code, and add
+  :confval:`codeautolink_disable_link_titles`
+  to disable the titles altogether (:issue:`200`)
+- Fix "Could not match transformation" warnings for assignments to
+  attributes such as ``thing.attr = 1`` (:issue:`201`)
+- Resolve ``typing.Self`` return annotations, respecting inheritance so a
+  ``Self``-returning method accessed through a subclass or mixin resolves to
+  the accessing class rather than the class it's defined on (:issue:`147`)
+
+0.18.1 (2026-04-30)
+-------------------
+- Recognize aliased ``TYPE_CHECKING`` imports such as
+  ``from typing import TYPE_CHECKING as _TYPE_CHECKING`` (:issue:`199`)
+
 0.18.0 (2026-04-25)
 -------------------
 - Support module attributes and class aliases (:issue:`65`)

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

@@ -72,6 +72,7 @@ ignore = [
 extend-ignore = [
     "ARG001", # unused args needed in interfaces
     "ARG002", # unused args needed in interfaces
+    "CPY001", # no copyright notices needed
     "D107", # docstring missing is fine
     "D203", # recommended by ruff format
     "D212", # docstring format clash
@@ -80,6 +81,7 @@ extend-ignore = [
     "ISC001", # recommended by ruff format
     "PLR0913", # many arguments is fine
     "PLR0915", # many statements is fine
+    "PLR0917", # many arguments is fine
 ]
 extend-unsafe-fixes = ["F401"]
 isort.split-on-trailing-comma = false

sphinx_codeautolink-0.19.0/requirements/tests

@@ -0,0 +1,5 @@
+-r extras
+
+pytest>=6
+coverage[toml]>=5
+typing-extensions>=4; python_version < "3.11"

{sphinx_codeautolink-0.18.0 → sphinx_codeautolink-0.19.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.18.0"
+__version__ = "0.19.0"
 
 
 def setup(app: Sphinx):
@@ -34,6 +34,9 @@ def setup(app: Sphinx):
     app.add_config_value(
         "codeautolink_inventory_map", default={}, rebuild="html", types=[dict]
     )
+    app.add_config_value(
+        "codeautolink_disable_link_titles", default=False, rebuild="html", types=[bool]
+    )
     app.add_config_value(
         "codeautolink_warn_on_missing_inventory",
         default=False,

{sphinx_codeautolink-0.18.0 → sphinx_codeautolink-0.19.0}/src/sphinx_codeautolink/extension/__init__.py

@@ -78,6 +78,7 @@ class SphinxCodeAutoLink:
         self.warn_no_backreference = None
         self.warn_default_parse_fail = None
         self.highlight_lang = None
+        self.disable_link_titles = None
 
         # Populated once
         self.outdated_docs: set[str] = set()
@@ -112,6 +113,7 @@ class SphinxCodeAutoLink:
             app.config.codeautolink_warn_on_default_parse_fail
         )
         self.highlight_lang = app.config.highlight_language
+        self.disable_link_titles = app.config.codeautolink_disable_link_titles
 
         # Append static resources path so references in setup() are valid
         app.config.html_static_path.append(
@@ -295,6 +297,7 @@ class SphinxCodeAutoLink:
                 self.custom_blocks,
                 self.search_css_classes,
                 builder_name=app.builder.name,
+                disable_link_titles=self.disable_link_titles,
             )
 
         self.cache.write()

{sphinx_codeautolink-0.18.0 → sphinx_codeautolink-0.19.0}/src/sphinx_codeautolink/extension/block.py

@@ -369,6 +369,14 @@ class CodeBlockAnalyser(nodes.SparseNodeVisitor):
         )
 
 
+def format_title(location: str, text: str) -> str:
+    """Format the title attribute of a link, empty if it wouldn't add information."""
+    code = re.sub(r"\s+", "", BeautifulSoup(text, "html.parser").get_text())
+    if code == location:
+        return ""
+    return f' title="{location}"'
+
+
 def link_html(
     document: str,
     out_dir: str,
@@ -377,6 +385,8 @@ def link_html(
     custom_blocks: dict,
     search_css_classes: list,
     builder_name: str = "html",
+    *,
+    disable_link_titles: bool,
 ) -> None:
     """Inject links to code blocks on disk."""
     if builder_name == "dirhtml" and Path(document).name != "index":
@@ -400,9 +410,7 @@ def link_html(
 
     up_lvls = len(html_file.relative_to(out_dir).parents) - 1
     local_prefix = "../" * up_lvls
-    link_pattern = (
-        '<a href="{link}" title="{title}" class="sphinx-codeautolink-a">{text}</a>'
-    )
+    link_pattern = '<a href="{link}"{title} class="sphinx-codeautolink-a">{text}</a>'
 
     for trans in transforms:
         for ix in range(len(inners)):
@@ -447,9 +455,13 @@ def link_html(
             location = inventory[name.resolved_location]
             if not any(location.startswith(s) for s in ("http://", "https://")):
                 location = local_prefix + location
-            link = link_pattern.format(
-                link=location, title=name.resolved_location, text=selection[start:end]
+            text = selection[start:end]
+            title = (
+                ""
+                if disable_link_titles
+                else format_title(name.resolved_location, text)
             )
+            link = link_pattern.format(link=location, title=title, text=text)
             transformed = selection[:start] + link + selection[end:]
             lines[begin_line : end_line + 1] = transformed.split("\n")
 

{sphinx_codeautolink-0.18.0 → sphinx_codeautolink-0.19.0}/src/sphinx_codeautolink/extension/resolve.py

@@ -16,6 +16,14 @@ from typing import Any, Union, get_type_hints
 
 from sphinx_codeautolink.parse import Name, NameBreak
 
+try:
+    from typing import Self  # Python >= 3.11
+except ImportError:  # pragma: no cover
+    try:
+        from typing_extensions import Self
+    except ImportError:
+        Self = None  # type: ignore[assignment,misc]
+
 # 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.
@@ -87,6 +95,13 @@ class Cursor:
     value: Any
     instance: bool
     annotation: Any = None
+    # The live object/class this cursor's value was accessed on, e.g. the
+    # receiver of a bound method. Used to resolve `Self` return annotations
+    # to the accessing class rather than the (possibly different, e.g. a
+    # mixin) class the method happens to be defined on. Unlike `location`,
+    # this is never rewritten by the MRO fallback below, so it reflects the
+    # true runtime receiver even when the naive `location` doesn't resolve.
+    receiver: Any = None
 
 
 def make_cursor(components: list[str]) -> tuple[list[str], Cursor]:
@@ -121,6 +136,7 @@ def locate_type(cursor: Cursor, components: tuple[str, ...], inventory) -> Curso
             getattr(previous.value, component, None),
             previous.instance,
             annotation=annotation,
+            receiver=previous.value,
         )
 
         if cursor.value is None:
@@ -163,6 +179,21 @@ def call_value(cursor: Cursor) -> None:
         raise CouldNotResolve  # not a function either
 
     annotation = get_return_annotation(cursor.value)
+    if Self is not None and annotation is Self and cursor.receiver is not None:
+        # `Self` refers to whichever class/instance the method was accessed
+        # on, which is not necessarily the class it's defined on (e.g. a
+        # mixin). Use the receiver rather than re-deriving the owner from
+        # `cursor.location`, since that string may have been rewritten to
+        # the *defining* class by the MRO fallback above.
+        owner_value = cursor.receiver
+        if not isclass(owner_value):
+            owner_value = type(owner_value)
+        cursor.value = owner_value
+        cursor.location = fully_qualified_name(owner_value)
+        cursor.instance = True
+        cursor.annotation = annotation
+        return
+
     type_ = origin_type(annotation)
     if not isinstance(type_, type):
         msg = f"Unable to follow return annotation of {annotation!r}."
@@ -282,10 +313,13 @@ def populate_type_checking(mod: ModuleType) -> None:
         return
 
     tree = ast.parse(source)
+    aliases = collect_type_checking_aliases(tree)
 
     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):
+        if not isinstance(node, ast.If):
+            continue
+        if not is_type_checking_test(node.test, aliases):
             continue
         body = ast.Module(body=node.body, type_ignores=[])
         # Catch e.g. optional deps and cyclic imports
@@ -293,15 +327,23 @@ def populate_type_checking(mod: ModuleType) -> None:
             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.
+def collect_type_checking_aliases(tree: ast.Module) -> set[str]:
+    """Walk top-level imports, return names bound to ``typing.TYPE_CHECKING``."""
+    aliases: set[str] = set()
+    for node in tree.body:
+        if isinstance(node, ast.ImportFrom) and node.module == "typing":
+            for alias in node.names:
+                if alias.name in ("TYPE_CHECKING", "MYPY"):
+                    aliases.add(alias.asname or alias.name)
+    return aliases
 
-    Mirror mypy's ``infer_condition_value``: match a bare name or any
-    attribute access regardless of qualifier.
-    """
+
+def is_type_checking_test(
+    expr: ast.expr, aliases: frozenset[str] | set[str] = frozenset()
+) -> bool:
+    """Determine if expr is a test for type checking."""
     if isinstance(expr, ast.Name):
-        return expr.id in ("TYPE_CHECKING", "MYPY")
+        return expr.id in ("TYPE_CHECKING", "MYPY") or expr.id in aliases
     if isinstance(expr, ast.Attribute):
         return expr.attr in ("TYPE_CHECKING", "MYPY")
     return False

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

@@ -286,15 +286,17 @@ class ImportTrackerVisitor(ast.NodeVisitor):
         if target is None:
             return
 
-        if len(target.components) == 1:
-            comp = target.components[0]
-            if value is None:
-                self.overwrite_name(comp.name)
-            else:
-                self.assign_name(comp.name, value.components)
-                self._create_access(target.components)
+        if len(target.components) != 1:
+            # Dotted targets don't assign to the current scope, and their access
+            # was already resolved when the access chain was visited.
+            return
+
+        comp = target.components[0]
+        if value is None:
+            self.overwrite_name(comp.name)
         else:
-            self.resolve_pending_access(target)
+            self.assign_name(comp.name, value.components)
+            self._create_access(target.components)
 
     def create_simple_access(self, name: str, lineno: int) -> None:
         """Create single-component access to scope."""

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sphinx-codeautolink
-Version: 0.18.0
+Version: 0.19.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>

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

@@ -122,6 +122,7 @@ tests/extension/ref/preface_multiline_and_arg.txt
 tests/extension/ref/preface_multiple.txt
 tests/extension/ref/preface_single.txt
 tests/extension/ref/ref_assign_targets.txt
+tests/extension/ref/ref_attribute_assignment.txt
 tests/extension/ref/ref_builtins.txt
 tests/extension/ref/ref_chain.txt
 tests/extension/ref/ref_chain_call.txt
@@ -154,8 +155,10 @@ 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_aliased.txt
 tests/extension/ref/ref_type_checking_gated.txt
 tests/extension/ref/search_css_duplicates_removed.txt
+tests/extension/ref/self_type.txt
 tests/extension/ref/skip_file.txt
 tests/extension/ref/skip_next.txt
 tests/extension/ref/skip_next_consumed_non_python.txt
@@ -164,10 +167,13 @@ tests/extension/ref/skip_section.txt
 tests/extension/src/class_mro_fix.py
 tests/extension/src/future_project.py
 tests/extension/src/parser_func.py
+tests/extension/src/self_type.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/src/type_checking_aliased/__init__.py
+tests/extension/src/type_checking_aliased/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 → sphinx_codeautolink-0.19.0}/tests/extension/__init__.py

@@ -282,6 +282,63 @@ Test project
     assert check_link_targets(result_dir) == n_subfiles * len(links)
 
 
+title_index = """
+Test project
+============
+
+.. code:: python
+
+   import test_project
+
+   test_project.bar().attr
+
+.. code:: python
+
+   import test_project
+
+   (test_project
+       .bar())
+
+.. automodule:: test_project
+"""
+
+
+def link_titles(file: Path) -> list[tuple[str, str | None]]:
+    """Return the text and title of all code links in a file."""
+    soup = BeautifulSoup(file.read_text("utf-8"), "html.parser")
+    links = soup.find_all("a", attrs={"class": "sphinx-codeautolink-a"})
+    return [(any_whitespace.sub("", "".join(a.strings)), a.get("title")) for a in links]
+
+
+def test_link_titles_show_resolved_location(tmp_path: Path):
+    """Titles are added only when they differ from the code being linked."""
+    files = {"conf.py": default_conf, "index.rst": title_index}
+    result_dir = _sphinx_build(tmp_path, "html", files)
+
+    assert link_titles(result_dir / "index.html") == [
+        ("test_project", None),
+        ("test_project.bar", None),
+        ("attr", "test_project.Foo.attr"),
+        ("test_project", None),
+        ("test_project.bar", None),
+    ]
+
+
+def test_link_titles_disabled(tmp_path: Path):
+    """No titles are added when they are turned off."""
+    conf = default_conf + "\ncodeautolink_disable_link_titles = True"
+    files = {"conf.py": conf, "index.rst": title_index}
+    result_dir = _sphinx_build(tmp_path, "html", files)
+
+    assert link_titles(result_dir / "index.html") == [
+        ("test_project", None),
+        ("test_project.bar", None),
+        ("attr", None),
+        ("test_project", None),
+        ("test_project.bar", None),
+    ]
+
+
 def test_skip_identical_code(tmp_path: Path):
     """Code skipped and then linked in an identical block after."""
     index = """

sphinx_codeautolink-0.19.0/tests/extension/ref/ref_attribute_assignment.txt

@@ -0,0 +1,17 @@
+test_project
+thing
+test_project.Foo
+thing.attr
+# split
+# split
+Test project
+============
+
+.. code:: python
+
+   import test_project
+
+   thing = test_project.Foo()
+   thing.attr = "value"
+
+.. automodule:: test_project

sphinx_codeautolink-0.19.0/tests/extension/ref/ref_type_checking_aliased.txt

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

sphinx_codeautolink-0.19.0/tests/extension/ref/self_type.txt

@@ -0,0 +1,17 @@
+self_type
+self_type.Derived
+make
+own
+# split
+# split
+Test project
+============
+
+.. code:: python
+
+   import self_type
+
+   self_type.Derived().make().own()
+
+.. automodule:: self_type
+   :no-inherited-members:

{sphinx_codeautolink-0.18.0 → sphinx_codeautolink-0.19.0}/tests/extension/src/future_project.py

@@ -14,7 +14,7 @@ def optional() -> Optional[Foo]:  # noqa: UP045
     """Return optional type."""
 
 
-def optional_manual() -> None | Foo:
+def optional_manual() -> None | Foo:  # noqa: RUF036
     """Return manually constructed optional type."""
 
 

sphinx_codeautolink-0.19.0/tests/extension/src/self_type.py

@@ -0,0 +1,23 @@
+# noqa: INP001
+# Test resolving `typing.Self` return annotations, see #147 for details.
+
+try:
+    from typing import Self  # Python >= 3.11
+except ImportError:
+    from typing_extensions import Self
+
+
+class Base:
+    """Base class defining a method that returns `Self`."""
+
+    def make(self) -> Self:
+        """Return an instance of whatever class this was accessed through."""
+        return self
+
+
+class Derived(Base):
+    """Combines a `Self`-returning base with its own method, like a mixin."""
+
+    def own(self) -> Self:
+        """Test method defined directly on the subclass."""
+        return self

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

@@ -56,7 +56,7 @@ def optional() -> Foo | None:
     """Return optional type."""
 
 
-def optional_manual() -> None | Foo:
+def optional_manual() -> None | Foo:  # noqa: RUF036
     """Return manually constructed optional type."""
 
 

sphinx_codeautolink-0.19.0/tests/extension/src/type_checking_aliased/__init__.py

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

sphinx_codeautolink-0.19.0/tests/extension/src/type_checking_aliased/foo.py

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

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

@@ -88,6 +88,48 @@ class TestAssign:
         refs = [("a", "a"), ("a", "a")]
         return s, refs
 
+    @refs_equal
+    def test_assign_to_attribute_uses_once(self):
+        s = "import a\na.b = 1"
+        refs = [("a", "a"), ("a.b", "a.b")]
+        return s, refs
+
+    @refs_equal
+    def test_assign_to_nested_attribute_uses_once(self):
+        s = "import a\na.b.c = 1"
+        refs = [("a", "a"), ("a.b.c", "a.b.c")]
+        return s, refs
+
+    @refs_equal
+    def test_assign_to_attribute_of_followed_name_uses_once(self):
+        s = "import a\nb = a()\nb.c = 1"
+        refs = [("a", "a"), ("a", "a"), ("a.()", "b"), ("a.().c", "b.c")]
+        return s, refs
+
+    @refs_equal
+    def test_multitarget_assign_to_attributes_uses_once_each(self):
+        s = "import a\na.b = a.c = 1"
+        refs = [("a", "a"), ("a.c", "a.c"), ("a.b", "a.b")]
+        return s, refs
+
+    @refs_equal
+    def test_unpack_assign_to_attribute_uses_once(self):
+        s = "import a\na.b, c = 1, 2"
+        refs = [("a", "a"), ("a.b", "a.b")]
+        return s, refs
+
+    @refs_equal
+    def test_annassign_to_attribute_uses_once(self):
+        s = "import a\na.b: int = 1"
+        refs = [("a", "a"), ("int", "int"), ("a.b", "a.b")]
+        return s, refs
+
+    @refs_equal
+    def test_augassign_to_attribute_uses_once(self):
+        s = "import a\na.b += 1"
+        refs = [("a", "a"), ("a.b", "a.b")]
+        return s, refs
+
     @refs_equal
     def test_assign_subscript_uses(self):
         s = "import a\na.b[0] = 1"

sphinx_codeautolink-0.18.0/requirements/tests

@@ -1,4 +0,0 @@
--r extras
-
-pytest>=6
-coverage[toml]>=5