mkdocstrings-python-xref 1.16.1__tar.gz → 1.16.3__tar.gz

{mkdocstrings_python_xref-1.16.1 → mkdocstrings_python_xref-1.16.3}/.gitignore

@@ -37,3 +37,7 @@ conda-meta-data.json
 
 
 
+
+# pixi environments
+.pixi
+*.egg-info

{mkdocstrings_python_xref-1.16.1 → mkdocstrings_python_xref-1.16.3}/LICENSE.md

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2022-2023 Analog Devices, Inc.
+   Copyright 2022-2025 Analog Devices, Inc.
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

{mkdocstrings_python_xref-1.16.1 → mkdocstrings_python_xref-1.16.3}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: mkdocstrings-python-xref
-Version: 1.16.1
+Version: 1.16.3
 Summary: Enhanced mkdocstrings python handler
 Project-URL: Repository, https://github.com/analog-garage/mkdocstrings-python-xref
 Project-URL: Documentation, https://analog-garage.github.io/mkdocstrings-python-xref/
 Author-email: Christopher Barber <Christopher.Barber@analog.com>
 License-File: LICENSE.md
 Keywords: documentation-tool,mkdocstrings,mkdocstrings-handler,python
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
@@ -18,6 +18,20 @@ Classifier: Topic :: Software Development :: Documentation
 Requires-Python: >=3.9
 Requires-Dist: griffe>=1.0
 Requires-Dist: mkdocstrings-python<2.0,>=1.16.6
+Provides-Extra: dev
+Requires-Dist: beautifulsoup4>=4.12; extra == 'dev'
+Requires-Dist: black>=23.12; extra == 'dev'
+Requires-Dist: build>=1.0.0; extra == 'dev'
+Requires-Dist: coverage>=7.4.0; extra == 'dev'
+Requires-Dist: hatchling>=1.21; extra == 'dev'
+Requires-Dist: linkchecker>=10.4; extra == 'dev'
+Requires-Dist: mike>=1.1; extra == 'dev'
+Requires-Dist: mkdocs-material>=9.5.4; extra == 'dev'
+Requires-Dist: mkdocs<2.0,>=1.5.3; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.2; extra == 'dev'
+Requires-Dist: ruff>=0.4.10; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # mkdocstrings-python-xref

{mkdocstrings_python_xref-1.16.1 → mkdocstrings_python_xref-1.16.3}/pyproject.toml

@@ -10,7 +10,7 @@ authors = [
     {name = "Christopher Barber", email="Christopher.Barber@analog.com" },
 ]
 classifiers = [
-    "Development Status :: 3 - Alpha",
+    "Development Status :: 5 - Production/Stable",
     "Intended Audience :: Developers",
     "Topic :: Software Development :: Documentation",
     "Programming Language :: Python :: 3.9",
@@ -33,6 +33,51 @@ dependencies = [
 Repository = "https://github.com/analog-garage/mkdocstrings-python-xref"
 Documentation = "https://analog-garage.github.io/mkdocstrings-python-xref/"
 
+[project.optional-dependencies]
+dev = [
+    "build >=1.0.0", # python-build on conda
+    "hatchling >=1.21",
+    "coverage >=7.4.0",
+    "pytest >=8.2",
+    "pytest-cov >=5.0",
+    "mypy >=1.10",
+    "ruff >=0.4.10",
+    "beautifulsoup4 >=4.12",
+    "black >=23.12",
+    "mike >=1.1",
+    "mkdocs >=1.5.3,<2.0",
+    "mkdocs-material >=9.5.4",
+    "linkchecker >=10.4"
+]
+
+[tool.pixi.workspace]
+name = "mkxref-dev"
+channels = ["conda-forge"]
+platforms = ["osx-arm64", "linux-64", "win-64"]
+
+[tool.pixi.dependencies]
+# Use conda for these in pixi
+mkdocstrings-python ="*"
+griffe ="*"
+hatchling = "*"
+python-build = "*"
+coverage ="*"
+pytest ="*"
+pytest-cov ="*"
+mypy ="*"
+ruff = "*"
+black = "*"
+mike = "*"
+mkdocs = "*"
+mkdocs-material = "*"
+linkchecker = "*"
+
+[tool.pixi.pypi-dependencies]
+mkdocstrings-python-xref = { path = ".", editable = true }
+
+[tool.pixi.environments]
+default = {features = ["dev"]}
+
 [tool.hatch.version]
 path = "src/mkdocstrings_handlers/python_xref/VERSION"
 pattern = "\\s*(?P<version>[\\w.]*)"
@@ -174,3 +219,53 @@ disable = [
     "wrong-spelling-in-comment",
     "wrong-spelling-in-docstring",
 ]
+
+[tool.pixi.tasks]
+# linting tasks
+mypy = "mypy"
+ruff = "ruff check src/mkdocstrings_handlers tests"
+lint = {depends-on = ["ruff", "mypy"]}
+
+# testing tasks
+pytest = "pytest -sv -ra tests"
+test = {depends-on = ["pytest", "lint"]}
+coverage = "pytest -ra --cov --cov-report=html --cov-report=term -- tests"
+coverage-show = "python -m webbrowser file://$PIXI_PROJECT_ROOT/htmlcov/index.html"
+
+# doc tasks
+docs = {depends-on = ["doc"]}
+show-doc = "mkdocs serve -f mkdocs.yml"
+show-docs = {depends-on = ["show-doc"]}
+
+# cleanup tasks
+clean-build = "rm -rf build dist"
+clean-coverage = "rm -rf .coverage .coverage.* htmlcov"
+clean-docs = "rm -rf site"
+clean-test = "rm -rf .pytest_cache .mypy_cache .ruff_cache"
+clean = {depends-on = ["clean-build", "clean-coverage", "clean-test"]}
+
+# build tasks
+build = {depends-on = ["build-wheel", "build-sdist", "build-conda"]}
+
+[tool.pixi.tasks.build-wheel]
+env = {VERSION = "$(cat src/mkdocstrings_handlers/python_xref/VERSION)"}
+cmd = "pip wheel . --no-deps --no-build-isolation -w dist"
+inputs = ["pyproject.toml", "LICENSE.md", "src/**/*"]
+outputs = ["dist/mkdocstrings_python_xref-$VERSION-py3-none-any.whl"]
+
+[tool.pixi.tasks.build-sdist]
+env = {VERSION = "$(cat src/mkdocstrings_handlers/python_xref/VERSION)"}
+cmd = "python -m build --sdist --no-isolation --outdir dist"
+inputs = ["pyproject.toml", "LICENSE.md", "src/**/*"]
+outputs = ["dist/mkdocstrings_pixipython_xref-$VERSION.tar.gz"]
+
+[tool.pixi.tasks.build-conda]
+#env = {VERSION = "$(cat src/mkdocstrings_handlers/python_xref/VERSION)"}
+cmd = "whl2conda convert dist/*.whl -w dist --overwrite"
+depends-on = ["build-wheel"]
+inputs = ["dist/mkdocstrings_python_xref-$VERSION-py3-none-any.whl"]
+
+[tool.pixi.tasks.doc]
+cmd = "mkdocs build -f mkdocs.yml"
+inputs = ["docs/*.md", "docs/*.svg", "mkdocs.yml"]
+outputs = ["site/*.html"]

mkdocstrings_python_xref-1.16.3/src/mkdocstrings_handlers/python_xref/VERSION

@@ -0,0 +1 @@
+1.16.3

{mkdocstrings_python_xref-1.16.1 → mkdocstrings_python_xref-1.16.3}/src/mkdocstrings_handlers/python_xref/crossref.py

@@ -15,8 +15,10 @@
 
 from __future__ import annotations
 
+import ast
 import re
-from typing import Callable, List, Optional, cast
+import sys
+from typing import Any, Callable, List, Optional, cast
 
 from griffe import Docstring, Object
 from mkdocstrings import get_logger
@@ -303,14 +305,12 @@ class _RelativeCrossrefProcessor:
             # We include the file:// prefix because it helps IDEs such as PyCharm
             # recognize that this is a navigable location it can highlight.
             prefix = f"file://{parent.filepath}:"
-            line = doc.lineno
-            if line is not None:  # pragma: no branch
-                # Add line offset to match in docstring. This can still be
-                # short if the doc string has leading newlines.
-                line += doc.value.count("\n", 0, self._cur_offset)
+            line, col = doc_value_offset_to_location(doc, self._cur_offset)
+            if line >= 0:
                 prefix += f"{line}:"
-                # It would be nice to add the column as well, but we cannot determine
-                # that without knowing how much the doc string was unindented.
+                if col >= 0:
+                    prefix += f"{col}:"
+
             prefix += " \n"
 
         logger.warning(prefix + msg)
@@ -334,3 +334,68 @@ def substitute_relative_crossrefs(obj: Object, checkref: Optional[Callable[[str]
     for member in obj.members.values():
         if isinstance(member, Object):  # pragma: no branch
             substitute_relative_crossrefs(member, checkref=checkref)
+
+def doc_value_offset_to_location(doc: Docstring, offset: int) -> tuple[int,int]:
+    """
+    Converts offset into doc.value to line and column in source file.
+
+    Returns:
+        line and column or else (-1,-1) if it cannot be computed
+    """
+    linenum = -1
+    colnum = -2
+
+    if doc.lineno is not None:
+        linenum = doc.lineno # start of the docstring source
+        # line offset with respect to start of cleaned up docstring
+        lineoffset = clean_lineoffset = doc.value.count("\n", 0, offset)
+
+        # look at original doc source, if available
+        try:
+            source = doc.source
+            # compute docstring without cleaning up spaces and indentation
+            rawvalue = str(safe_eval(source))
+
+            # adjust line offset by number of lines removed from front of docstring
+            lineoffset += leading_space(rawvalue).count("\n")
+
+            if lineoffset == 0 and (m := re.match(r"(\s*['\"]{1,3}\s*)\S", source)):
+                # is on the same line as opening quote
+                colnum = offset + len(m.group(1))
+            else:
+                # indentation of first non-empty line in raw and cleaned up strings
+                raw_line = rawvalue.splitlines()[lineoffset]
+                clean_line = doc.value.splitlines()[clean_lineoffset]
+                raw_indent = len(leading_space(raw_line))
+                clean_indent = len(leading_space(clean_line))
+                try:
+                    linestart = doc.value.rindex("\n", 0, offset) + 1
+                except ValueError: # pragma: no cover
+                    linestart = 0 # paranoid check, should not really happen
+                colnum = offset - linestart + raw_indent - clean_indent
+
+        except Exception:
+            # Don't expect to get here, but just in case, it is better to
+            # not fix up the line/column than to die.
+            pass
+
+        linenum += lineoffset
+
+    return linenum, colnum + 1
+
+
+def leading_space(s: str) -> str:
+    """Returns whitespace at the front of string."""
+    if m := re.match(r"\s*", s):
+        return m[0]
+    return "" # pragma: no cover
+
+if sys.version_info < (3, 10) or True:
+    # TODO: remove when 3.9 support is dropped
+    # In 3.9, literal_eval cannot handle comments in input
+    def safe_eval(s: str) -> Any:
+        """Safely evaluate a string expression."""
+        return eval(s) #eval(s, dict(__builtins__={}), {})
+else:
+    save_eval = ast.literal_eval
+

{mkdocstrings_python_xref-1.16.1 → mkdocstrings_python_xref-1.16.3}/src/mkdocstrings_handlers/python_xref/handler.py

@@ -17,8 +17,10 @@ Implementation of python_xref handler
 
 from __future__ import annotations
 
+import re
 import sys
-from dataclasses import dataclass, fields
+from dataclasses import dataclass, field, fields
+from functools import partial
 from pathlib import Path
 from typing import Any, ClassVar, Mapping, MutableMapping, Optional
 from warnings import warn
@@ -43,6 +45,7 @@ if sys.version_info >= (3, 10):
 @dataclass(**_dataclass_options)
 class PythonRelXRefOptions(PythonOptions):
     check_crossrefs: bool = True
+    check_crossrefs_exclude: list[str | re.Pattern] = field(default_factory=list)
 
 class PythonRelXRefHandler(PythonHandler):
     """Extended version of mkdocstrings Python handler
@@ -62,26 +65,30 @@ class PythonRelXRefHandler(PythonHandler):
             base_dir: The base directory of the project.
             **kwargs: Arguments passed to the parent constructor.
         """
-        check_crossrefs = config.options.pop('check_crossrefs', None)  # Remove
+        self.check_crossrefs = config.options.pop('check_crossrefs', True)
+        exclude = config.options.pop('check_crossrefs_exclude', [])
+        self.check_crossrefs_exclude = [re.compile(p) for p in exclude]
         super().__init__(config, base_dir, **kwargs)
-        if check_crossrefs is not None:
-            self.global_options["check_crossrefs"] = check_crossrefs
 
     def get_options(self, local_options: Mapping[str, Any]) -> PythonRelXRefOptions:
         local_options = dict(local_options)
-        check_crossrefs = local_options.pop('check_crossrefs', None)
+        check_crossrefs = local_options.pop(
+            'check_crossrefs', self.check_crossrefs)
+        check_crossrefs_exclude = local_options.pop(
+            'check_crossrefs_exclude', self.check_crossrefs_exclude)
         _opts = super().get_options(local_options)
         opts = PythonRelXRefOptions(
+            check_crossrefs=check_crossrefs,
+            check_crossrefs_exclude=check_crossrefs_exclude,
             **{field.name: getattr(_opts, field.name) for field in fields(_opts)}
         )
-        if check_crossrefs is not None:
-            opts.check_crossrefs = bool(check_crossrefs)
         return opts
 
     def render(self, data: CollectorItem, options: PythonOptions) -> str:
         if options.relative_crossrefs:
-            if isinstance(options, PythonRelXRefOptions):
-                checkref = self._check_ref if options.check_crossrefs else None
+            if isinstance(options, PythonRelXRefOptions) and options.check_crossrefs:
+                checkref = partial(
+                    self._check_ref, exclude=options.check_crossrefs_exclude)
             else:
                 checkref = None
             substitute_relative_crossrefs(data, checkref=checkref)
@@ -98,8 +105,11 @@ class PythonRelXRefHandler(PythonHandler):
             handler = 'python'
         return super().get_templates_dir(handler)
 
-    def _check_ref(self, ref:str) -> bool:
+    def _check_ref(self, ref : str, exclude: list[str | re.Pattern] = []) -> bool:
         """Check for existence of reference"""
+        for ex in exclude:
+            if re.match(ex, ref):
+                return True
         try:
             self.collect(ref, PythonOptions())
             return True

mkdocstrings_python_xref-1.16.1/src/mkdocstrings_handlers/python_xref/VERSION

@@ -1 +0,0 @@
-1.16.1