sphinx-codelinks 2.0.0__tar.gz → 2.0.1__tar.gz

{sphinx_codelinks-2.0.0 → sphinx_codelinks-2.0.1}/PKG-INFO

@@ -1,18 +1,19 @@
 Metadata-Version: 2.4
 Name: sphinx-codelinks
-Version: 2.0.0
+Version: 2.0.1
 Summary: Fast Source Code Traceability for Sphinx-Needs
 Author-email: team useblocks <info@useblocks.com>
 Maintainer-email: Marco Heinemann <marco.heinemann@useblocks.com>, Jui-Wen Chen <jui-wen.chen@useblocks.com>
 Requires-Python: >=3.11,<4
 Description-Content-Type: text/markdown
+Classifier: Typing :: Typed
 License-File: LICENSE
 Requires-Dist: comment-parser>=1.2.4
 Requires-Dist: ignore-python>=0.3.3
 Requires-Dist: typer>=0.16.0
 Requires-Dist: jsonschema
 Requires-Dist: sphinx>=7.4,<10
-Requires-Dist: sphinx-needs>=9.0.0,<10
+Requires-Dist: sphinx-needs>=9.1.0,<10
 Requires-Dist: ub-project>=1.1.0,<2
 Requires-Dist: jinja2
 Requires-Dist: pygments
@@ -28,7 +29,7 @@ Requires-Dist: tree-sitter-rust>=0.23.0
 Requires-Dist: tree-sitter-go>=0.23.0
 Requires-Dist: tree-sitter-json>=0.24.8
 Requires-Dist: tree-sitter-bash>=0.25.1
-Requires-Dist: furo>=2024.5.6 ; extra == "docs"
+Requires-Dist: furo>=2025.12.19 ; extra == "docs"
 Requires-Dist: myst-parser>=4.0.0 ; extra == "docs"
 Requires-Dist: sphinx-ai-index>=1.0.0,<2 ; extra == "docs"
 Requires-Dist: sphinx-design>=0.6.1 ; extra == "docs"

{sphinx_codelinks-2.0.0 → sphinx_codelinks-2.0.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sphinx-codelinks"
-version = "2.0.0"
+version = "2.0.1"
 description = "Fast Source Code Traceability for Sphinx-Needs"
 authors = [{ name = "team useblocks", email = "info@useblocks.com" }]
 maintainers = [
@@ -15,6 +15,7 @@ readme = "README.md"
 # locks, builds and publishes -- the gap shows up only as an install failure for a user on
 # an interpreter inside it.
 requires-python = ">=3.11,<4"
+classifiers = ["Typing :: Typed"]
 dependencies = [
   "comment-parser>=1.2.4",
   "ignore-python>=0.3.3",
@@ -27,7 +28,7 @@ dependencies = [
   # edge. uv never validates a specifier it resolves through `workspace = true` (uv#9811),
   # so the floor is the only statement of what was actually tested, and the cap is what
   # stops a future major being co-installed with a wheel written against this one.
-  "sphinx-needs>=9.0.0,<10",
+  "sphinx-needs>=9.1.0,<10",
   "ub-project>=1.1.0,<2",
   "jinja2",
   "pygments",
@@ -64,7 +65,7 @@ libclang = ["libclang>=16"]
 # the root there re-exports each member's extra (`docs-mounts = ["sphinx-mounts[docs]"]`),
 # because `uv sync --extra` resolves against the workspace root rather than the member.
 docs = [
-  "furo>=2024.5.6",
+  "furo>=2025.12.19",
   "myst-parser>=4.0.0",
   "sphinx-ai-index>=1.0.0,<2",
   "sphinx-design>=0.6.1",
@@ -84,9 +85,10 @@ Changelog = "https://github.com/useblocks/sphinx-needs/blob/master/packages/sphi
 requires = ["flit_core >=3.4,<4"]
 build-backend = "flit_core.buildapi"
 
-# Deliberately NO `[tool.flit.sdist]`: this distribution carries no non-Python payload, so
-# flit's module-only sdist is byte-for-byte the shape already published on PyPI, and
-# nothing downstream builds from it -- the git pins in the wild clone the repository.
+# Deliberately NO `[tool.flit.sdist]`: this distribution carries nothing outside the module
+# (its `py.typed` marker included, which flit ships as part of it), so flit's module-only
+# sdist is the shape already published on PyPI, and nothing downstream builds from it --
+# the git pins in the wild clone the repository.
 # Everything else -- ruff, ty, pytest and the dependency groups -- is the ROOT's, and
 # `tools/src/sn_tools/check_workspace.py` check (7) refuses those tables here: a member
 # `[tool.ruff]` does not extend the root's configuration, it replaces it.

{sphinx_codelinks-2.0.0 → sphinx_codelinks-2.0.1}/src/sphinx_codelinks/__init__.py

@@ -2,7 +2,7 @@
 
 from sphinx_codelinks.sphinx_extension.source_tracing import setup
 
-__version__ = "2.0.0"
+__version__ = "2.0.1"
 
 __all__ = [
     "__version__",

{sphinx_codelinks-2.0.0 → sphinx_codelinks-2.0.1}/src/sphinx_codelinks/analyse/analyse.py

@@ -363,9 +363,14 @@ class SourceAnalyse:
             # ``c`` is a LibclangComment duck-typing the tree-sitter Node
             # interface SourceComment reads (``.text`` / ``.start_point.row``);
             # the Node-only path (find_associated_scope) is guarded by
-            # ``is_libclang`` so it never runs on these.
+            # ``is_libclang`` so it never runs on these. The cast is that duck typing,
+            # which is why ty, seeing two unrelated classes, has to be told.
             src_comments = [
-                SourceComment(cast("TreeSitterNode", c), c.column) for c in comments
+                SourceComment(
+                    cast("TreeSitterNode", c),  # ty: ignore[disjoint-cast]
+                    c.column,
+                )
+                for c in comments
             ]
             src_file = SourceFile(src_path.absolute())
             src_file.add_comments(src_comments)

{sphinx_codelinks-2.0.0 → sphinx_codelinks-2.0.1}/src/sphinx_codelinks/config.py

@@ -67,13 +67,14 @@ class NeedIdRefsConfig:
         errors = []
         for _field_name in self.field_names():
             schema = self.get_schema(_field_name)
+            if schema is None:
+                # no schema to check against; `validate` would raise TypeError
+                continue
             value = getattr(self, _field_name)
             try:
-                # jsonschema's stubs type `schema` as `bool | Mapping`, but
-                # `get_schema` returns an optional dict
                 validate(
                     instance=value,
-                    schema=schema,  # ty: ignore[invalid-argument-type]
+                    schema=schema,
                 )
             except ValidationError as e:
                 errors.append(
@@ -137,13 +138,14 @@ class MultilineNeedsConfig:
         errors = []
         for _field_name in self.field_names():
             schema = self.get_schema(_field_name)
+            if schema is None:
+                # no schema to check against; `validate` would raise TypeError
+                continue
             value = getattr(self, _field_name)
             try:
-                # jsonschema's stubs type `schema` as `bool | Mapping`, but
-                # `get_schema` returns an optional dict
                 validate(
                     instance=value,
-                    schema=schema,  # ty: ignore[invalid-argument-type]
+                    schema=schema,
                 )
             except ValidationError as e:
                 errors.append(
@@ -334,11 +336,14 @@ class OneLineCommentStyle:
         errors = []
         for _field_name in self.field_names():
             schema = self.get_schema(_field_name)
+            if schema is None:
+                # no schema to check against; `validate` would raise TypeError
+                continue
             value = getattr(self, _field_name)
             try:
                 validate(
                     instance=value,
-                    schema=schema,  # ty: ignore[invalid-argument-type]
+                    schema=schema,
                 )  # validate has no type specified
             except ValidationError as e:
                 if _field_name == "needs_fields":

{sphinx_codelinks-2.0.0 → sphinx_codelinks-2.0.1}/src/sphinx_codelinks/needextend_write.py

@@ -118,13 +118,14 @@ class MarkedContentSchema:
         errors = []
         for _field_name in self.field_names():
             schema = self.get_schema(_field_name)
+            if schema is None:
+                # no schema to check against; `validate` would raise TypeError
+                continue
             value = getattr(self, _field_name)
             try:
-                # jsonschema's stubs type `schema` as `bool | Mapping`, but
-                # `get_schema` returns an optional dict
                 validate(
                     instance=value,
-                    schema=schema,  # ty: ignore[invalid-argument-type]
+                    schema=schema,
                 )
             except ValidationError as e:
                 errors.append(

{sphinx_codelinks-2.0.0 → sphinx_codelinks-2.0.1}/src/sphinx_codelinks/source_discover/config.py

@@ -186,13 +186,16 @@ class SourceDiscoverConfig:
         errors = []
         for _field_name in self.field_names():
             schema = self.get_schema(_field_name)
+            if schema is None:
+                # no schema to check against; `validate` would raise TypeError
+                continue
             value = getattr(self, _field_name)
             if isinstance(value, Path):  # adapt to json schema restriction
                 value = str(value)
             try:
                 validate(
                     instance=value,
-                    schema=schema,  # ty: ignore[invalid-argument-type]
+                    schema=schema,
                 )  # validate has no type specified
             except ValidationError as e:
                 errors.append(

{sphinx_codelinks-2.0.0 → sphinx_codelinks-2.0.1}/src/sphinx_codelinks/sphinx_extension/debug.py

@@ -9,7 +9,7 @@ import inspect
 import json
 from collections.abc import Callable
 from datetime import datetime
-from functools import wraps
+from functools import partial, wraps
 from pathlib import Path
 from timeit import default_timer as timer  # Used for timing measurements
 from typing import Any, TypeVar
@@ -19,15 +19,52 @@ from sphinx.application import Sphinx
 
 # Stores the timing results
 TIME_MEASUREMENTS: dict[str, Any] = {}
-EXECUTE_TIME_MEASUREMENTS = (
+EXECUTE_TIME_MEASUREMENTS: bool = (
     False  # Will be used to de/activate measurements. Set during a Sphinx Event
 )
 
-START_TIME = 0.0
+START_TIME: float = 0.0
 
 T = TypeVar("T", bound=Callable[..., Any])
 
 
+def _callable_name(func: Callable[..., Any]) -> str:
+    """A name for a measured callable, which need not have a ``__name__``.
+
+    A ``functools.partial`` is named after what it wraps, a callable instance after its
+    type; never its ``repr``, which would put memory addresses and bound arguments into
+    the report.
+    """
+    name = getattr(func, "__name__", None)
+    if isinstance(name, str) and name:
+        return name
+    if isinstance(func, partial):
+        return f"partial({_callable_name(func.func)})"
+    return type(func).__name__
+
+
+# Where a measured callable came from is a debugging aid, so a callable inspect cannot
+# place -- a partial or an instance (TypeError), a file that is gone or a class in
+# ``__main__`` (OSError), a file rewritten since (tokenize.TokenError) -- is recorded
+# without it rather than ending the build.
+
+
+def _source_file(func: Callable[..., Any]) -> str | None:
+    """The file ``func`` was defined in, or ``None`` if inspect cannot place it."""
+    try:
+        return inspect.getfile(func)
+    except Exception:
+        return None
+
+
+def _source_line(func: Callable[..., Any]) -> int | None:
+    """The first line of ``func``'s source, or ``None`` if it cannot be read."""
+    try:
+        return inspect.getsourcelines(func)[1]
+    except Exception:
+        return None
+
+
 def measure_time(
     category: str | None = None, source: str = "internal", name: str | None = None
 ) -> Callable[[T], T]:
@@ -77,9 +114,10 @@ def measure_time(
 
             runtime = end - start
 
-            mt_name = func.__name__ if name is None else name
+            func_name = _callable_name(func)
+            mt_name = func_name if name is None else name
 
-            mt_id = f"{category}_{func.__name__}"
+            mt_id = f"{category}_{func_name}"
 
             if mt_id not in TIME_MEASUREMENTS:
                 TIME_MEASUREMENTS[mt_id] = {
@@ -87,8 +125,8 @@ def measure_time(
                     "category": category,
                     "source": source,
                     "doc": func.__doc__,
-                    "file": inspect.getfile(func),
-                    "line": inspect.getsourcelines(func)[1],
+                    "file": _source_file(func),
+                    "line": _source_line(func),
                     "amount": 0,
                     "overall": 0,
                     "avg": None,

{sphinx_codelinks-2.0.0 → sphinx_codelinks-2.0.1}/src/sphinx_codelinks/sphinx_extension/directives/src_trace.py

@@ -651,12 +651,10 @@ class SourceTracingDirective(SphinxDirective):
             fields = frozenset(
                 [*schema.iter_extra_field_names(), *schema.iter_link_field_names()]
             )
-            # a default or a predicate (which may not match the need: which one matches
-            # is only known when the need is created, after its markup is chosen)
-            template = schema.get_core_field("template")
-            project_template = template is not None and (
-                template.default is not None or bool(template.predicate_defaults)
-            )
+            # a default or a predicate of any declaration of the template, global or a
+            # need type's (which may not apply to the need: which one applies is only
+            # known when the need is created, after its markup is chosen)
+            project_template = schema.declares_default("template")
         for marker in markers:
             filepath = src_analyse.analyse_config.src_dir / marker.filepath
 

{sphinx_codelinks-2.0.0 → sphinx_codelinks-2.0.1}/src/sphinx_codelinks/sphinx_extension/html_wrapper.py

@@ -1,13 +1,21 @@
 from collections.abc import Generator
 from pathlib import Path
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 from pygments import highlight
 from pygments.formatters import HtmlFormatter
 from pygments.lexers import CLexer
 
+if TYPE_CHECKING:
+    # generic over its output type in the stubs; pygments accepts the subscript at run
+    # time only in recent releases (`Formatter.__class_getitem__`), and this package
+    # declares no pygments floor
+    _HtmlFormatter = HtmlFormatter[str]
+else:
+    _HtmlFormatter = HtmlFormatter
 
-class LineFormatter(HtmlFormatter):
+
+class LineFormatter(_HtmlFormatter):
     def __init__(self, lineno_href: dict[int, str], *args: Any, **kwargs: Any) -> None:
         super().__init__(*args, **kwargs)
         self.lineno_href = lineno_href

{sphinx_codelinks-2.0.0 → sphinx_codelinks-2.0.1}/src/sphinx_codelinks/sphinx_extension/need_id_refs.py

@@ -17,7 +17,7 @@ runs before ``needextend`` is applied, so a user's ``needextend`` of the field w
 from __future__ import annotations
 
 from collections import Counter
-from collections.abc import Iterable, Mapping, MutableMapping
+from collections.abc import Collection, Iterable, Mapping, MutableMapping
 from dataclasses import dataclass, field
 from pathlib import Path, PurePosixPath
 from typing import Any
@@ -35,6 +35,7 @@ from sphinx_codelinks.config import (
     need_id_refs_fields,
 )
 from sphinx_codelinks.sphinx_extension.project_analysis import configured_git_root
+from sphinx_needs.data import SphinxNeedsData
 
 logger = logging.getLogger(__name__)
 
@@ -133,6 +134,7 @@ def attach_need_id_refs(
     *,
     fields: Mapping[str, str],
     roots: Mapping[str, str] | None = None,
+    derived: Collection[str] = (),
 ) -> AttachResult:
     """Give each referenced need the URLs of its references.
 
@@ -150,7 +152,10 @@ def attach_need_id_refs(
     each kept. Records are ordered by ``(path, lineno, start_column)``. A
     need gets one entry per reference: its remote URL, else its local one; projects
     naming the same field share one list. The need is not marked as modified, and an
-    unreferenced need is left alone.
+    unreferenced need is left alone. Nothing is written into a field in ``derived``
+    (the fields the schema derives: a user's declaration of the field with a ``derive``
+    rule), which a need refuses to have set: the need keeps what its rule computes, and
+    a reference to an unknown id is still reported.
     """
     roots = roots or {}
     unique: dict[tuple[str, str, str, int, str], NeedIdRef] = {}
@@ -174,6 +179,8 @@ def attach_need_id_refs(
         if need is None:
             result.unknown.append(ref)
             continue
+        if fields[ref.project] in derived:
+            continue
         value = ref.remote_url or _local_value(ref.local_url, need.get("docname"))
         if value is None:
             continue
@@ -196,7 +203,10 @@ def attach_and_report(
     codelinks_config = CodeLinksConfig.from_sphinx(app.config)
     fields = need_id_refs_fields(codelinks_config)
     roots = project_roots(app.confdir, codelinks_config)
-    result = attach_need_id_refs(refs, needs, fields=fields, roots=roots)
+    derived = SphinxNeedsData(app.env).get_schema().derived_names
+    result = attach_need_id_refs(
+        refs, needs, fields=fields, roots=roots, derived=derived
+    )
 
     # one warning per located id, even when two fields cover one file
     warned: set[tuple[str, int, str]] = set()

{sphinx_codelinks-2.0.0 → sphinx_codelinks-2.0.1}/src/sphinx_codelinks/sphinx_extension/source_tracing.py

@@ -447,8 +447,8 @@ def prepare_env(
 
     # Set time measurement flag
     if src_trace_sphinx_config.debug_measurement:
-        debug.START_TIME = timer()  # Store the rough start time of Sphinx build  # ty: ignore[invalid-assignment]
-        debug.EXECUTE_TIME_MEASUREMENTS = True  # ty: ignore[invalid-assignment]
+        debug.START_TIME = timer()  # Store the rough start time of Sphinx build
+        debug.EXECUTE_TIME_MEASUREMENTS = True
 
     if src_trace_sphinx_config.debug_filters:
         with contextlib.suppress(FileNotFoundError):