fix: Ignore invalid inventory lines

Yoshanuikabundi · pawamoy · commit 81caff5ff76f · 2025-03-31T10:13:47.000+02:00
Previously, inventory items whose `dispname` value contains multiple lines would prevent mkdocstrings from loading the whole inventory file. This change makes mkdocstrings ignore invalid lines in inventories so that the rest of the inventory can still be loaded. This continuation line behavior can be seen in the wild in the OpenEye toolkits inventory file and a few Open Force Field inventory files. These projects' inventories cannot be used with mkdocstrings because of the raised error. Note that in Sphinx too, these inventory files are read succesfully, and the continuation lines are discarded, truncating the display name. In theory, a continuation line that by chance did parse correctly would be interpreted by both packages as a new inventory item. OpenEye Toolkits inventory file: https://docs.eyesopen.com/toolkits/python/objects.inv Open Force Field Toolkit inventory file: https://docs.openforcefield.org/projects/toolkit/en/stable/objects.inv BespokeFit inventory file: https://docs.openforcefield.org/projects/bespokefit/en/stable/objects.inv
diff --git a/src/mkdocstrings/_internal/inventory.py b/src/mkdocstrings/_internal/inventory.py
@@ -8,7 +8,7 @@
 import re
 import zlib
 from textwrap import dedent
-from typing import TYPE_CHECKING, BinaryIO
+from typing import TYPE_CHECKING, BinaryIO, Literal, overload
 
 if TYPE_CHECKING:
     from collections.abc import Collection
@@ -66,11 +66,21 @@ def format_sphinx(self) -> str:
     sphinx_item_regex = re.compile(r"^(.+?)\s+(\S+):(\S+)\s+(-?\d+)\s+(\S+)\s*(.*)$")
     """Regex to parse a Sphinx v2 inventory line."""
 
+    @overload
     @classmethod
-    def parse_sphinx(cls, line: str) -> InventoryItem:
+    def parse_sphinx(cls, line: str, *, return_none: Literal[False]) -> InventoryItem: ...
+
+    @overload
+    @classmethod
+    def parse_sphinx(cls, line: str, *, return_none: Literal[True]) -> InventoryItem | None: ...
+
+    @classmethod
+    def parse_sphinx(cls, line: str, *, return_none: bool = False) -> InventoryItem | None:
         """Parse a line from a Sphinx v2 inventory file and return an `InventoryItem` from it."""
         match = cls.sphinx_item_regex.search(line)
         if not match:
+            if return_none:
+                return None
             raise ValueError(line)
         name, domain, role, priority, uri, dispname = match.groups()
         if uri.endswith("$"):
@@ -167,7 +177,9 @@ def parse_sphinx(cls, in_file: BinaryIO, *, domain_filter: Collection[str] = ())
         for _ in range(4):
             in_file.readline()
         lines = zlib.decompress(in_file.read()).splitlines()
-        items = [InventoryItem.parse_sphinx(line.decode("utf8")) for line in lines]
+        items: list[InventoryItem] = [
+            item for line in lines if (item := InventoryItem.parse_sphinx(line.decode("utf8"), return_none=True))
+        ]
         if domain_filter:
             items = [item for item in items if item.domain in domain_filter]
         return cls(items)
diff --git a/tests/test_inventory.py b/tests/test_inventory.py
@@ -11,8 +11,6 @@
 
 from mkdocstrings import Inventory, InventoryItem
 
-sphinx = pytest.importorskip("sphinx.util.inventory", reason="Sphinx is not installed")
-
 
 @pytest.mark.parametrize(
     "our_inv",
@@ -21,10 +19,13 @@
         Inventory([InventoryItem(name="object_path", domain="py", role="obj", uri="page_url")]),
         Inventory([InventoryItem(name="object_path", domain="py", role="obj", uri="page_url#object_path")]),
         Inventory([InventoryItem(name="object_path", domain="py", role="obj", uri="page_url#other_anchor")]),
+        Inventory([InventoryItem(name="o", domain="py", role="obj", uri="u#o", dispname="first line\nsecond line")]),
     ],
 )
 def test_sphinx_load_inventory_file(our_inv: Inventory) -> None:
     """Perform the 'live' inventory load test."""
+    sphinx = pytest.importorskip("sphinx.util.inventory", reason="Sphinx is not installed")
+
     buffer = BytesIO(our_inv.format_sphinx())
     sphinx_inv = sphinx.InventoryFile.load(buffer, "", join)
 
@@ -37,6 +38,8 @@ def test_sphinx_load_inventory_file(our_inv: Inventory) -> None:
 
 def test_sphinx_load_mkdocstrings_inventory_file() -> None:
     """Perform the 'live' inventory load test on mkdocstrings own inventory."""
+    sphinx = pytest.importorskip("sphinx.util.inventory", reason="Sphinx is not installed")
+
     mkdocs_config = load_config()
     mkdocs_config["plugins"].run_event("startup", command="build", dirty=False)
     try:
@@ -53,3 +56,29 @@ def test_sphinx_load_mkdocstrings_inventory_file() -> None:
 
     for item in own_inv.values():
         assert item.name in sphinx_inv[f"{item.domain}:{item.role}"]
+
+
+@pytest.mark.parametrize(
+    "our_inv",
+    [
+        Inventory(),
+        Inventory([InventoryItem(name="object_path", domain="py", role="obj", uri="page_url")]),
+        Inventory([InventoryItem(name="object_path", domain="py", role="obj", uri="page_url#object_path")]),
+        Inventory([InventoryItem(name="object_path", domain="py", role="obj", uri="page_url#other_anchor")]),
+        Inventory([InventoryItem(name="o", domain="py", role="obj", uri="u#o", dispname="first line\nsecond line")]),
+    ],
+)
+def test_mkdocstrings_roundtrip_inventory_file(our_inv: Inventory) -> None:
+    """Save some inventory files, then load them in again."""
+    buffer = BytesIO(our_inv.format_sphinx())
+    round_tripped = Inventory.parse_sphinx(buffer)
+
+    assert our_inv.keys() == round_tripped.keys()
+    for key, value in our_inv.items():
+        round_tripped_item = round_tripped[key]
+        assert round_tripped_item.name == value.name
+        assert round_tripped_item.domain == value.domain
+        assert round_tripped_item.role == value.role
+        assert round_tripped_item.uri == value.uri
+        assert round_tripped_item.priority == value.priority
+        assert round_tripped_item.dispname == value.dispname.splitlines()[0]
