Intersphinx inventories: add loading-time warning when ambiguous name definitions exist.

Author: jayaddison

sphinx/util/inventory.py

@@ -6,6 +6,7 @@
 import zlib
 from typing import IO, TYPE_CHECKING, Callable
 
+from sphinx.locale import __
 from sphinx.util import logging
 
 BUFSIZE = 16 * 1024
@@ -86,19 +87,23 @@ def load(
         reader = InventoryFileReader(stream)
         line = reader.readline().rstrip()
         if line == '# Sphinx inventory version 1':
-            return cls.load_v1(reader, uri, joinfunc)
+            invdata, ambiguities = cls.load_v1(reader, uri, joinfunc)
         elif line == '# Sphinx inventory version 2':
-            return cls.load_v2(reader, uri, joinfunc)
+            invdata, ambiguities = cls.load_v2(reader, uri, joinfunc)
         else:
             raise ValueError('invalid inventory header: %s' % line)
+        for ambiguity in ambiguities:
+            logger.warning(__("inventory <%s> contains multiple definitions for %s"),
+                           uri, ambiguity, type='intersphinx',  subtype='external')
+        return invdata
 
     @classmethod
     def load_v1(
         cls: type[InventoryFile],
         stream: InventoryFileReader,
         uri: str,
         join: Callable[[str, str], str],
-    ) -> Inventory:
+    ) -> tuple[Inventory, set]:
         invdata: Inventory = {}
         projname = stream.readline().rstrip()[11:]
         version = stream.readline().rstrip()[11:]
@@ -113,18 +118,20 @@ def load_v1(
                 type = 'py:' + type
                 location += '#' + name
             invdata.setdefault(type, {})[name] = (projname, version, location, '-')
-        return invdata
+        return invdata, frozenset()
 
     @classmethod
     def load_v2(
         cls: type[InventoryFile],
         stream: InventoryFileReader,
         uri: str,
         join: Callable[[str, str], str],
-    ) -> Inventory:
+    ) -> tuple[Inventory, set]:
         invdata: Inventory = {}
         projname = stream.readline().rstrip()[11:]
         version = stream.readline().rstrip()[11:]
+        potential_ambiguities = set()
+        actual_ambiguities = set()
         line = stream.readline()
         if 'zlib' not in line:
             raise ValueError('invalid inventory header (not compressed): %s' % line)
@@ -147,12 +154,20 @@ def load_v2(
                 # for Python modules, and the first
                 # one is correct
                 continue
+            if type in {'std:label', 'std:term'}:
+                # Some types require case insensitive matches:
+                # * 'term': https://github.com/sphinx-doc/sphinx/issues/9291
+                # * 'label': https://github.com/sphinx-doc/sphinx/issues/12008
+                if name.lower() in potential_ambiguities:
+                    actual_ambiguities.add(f"{type}:{name}")
+                else:
+                    potential_ambiguities.add(name.lower())
             if location.endswith('$'):
                 location = location[:-1] + name
             location = join(uri, location)
             inv_item: InventoryItem = projname, version, location, dispname
             invdata.setdefault(type, {})[name] = inv_item
-        return invdata
+        return invdata, actual_ambiguities
 
     @classmethod
     def dump(

tests/test_util/test_util_inventory.py

@@ -10,6 +10,7 @@
 from tests.test_util.intersphinx_data import (
     INVENTORY_V1,
     INVENTORY_V2,
+    INVENTORY_V2_AMBIGUOUS_TERMS,
     INVENTORY_V2_NO_VERSION,
 )
 
@@ -48,6 +49,13 @@ def test_read_inventory_v2_not_having_version():
         ('foo', '', '/util/foo.html#module-module1', 'Long Module desc')
 
 
+def test_ambiguous_definition_warning(warning):
+    f = BytesIO(INVENTORY_V2_AMBIGUOUS_TERMS)
+    invdata = InventoryFile.load(f, '/util', posixpath.join)
+
+    assert 'contains multiple definitions for std:term:a' in warning.getvalue().lower()
+
+
 def _write_appconfig(dir, language, prefix=None):
     prefix = prefix or language
     os.makedirs(dir / prefix, exist_ok=True)