Forward-port from 2.12 branch.

doc/CHANGES.rst

@@ -153,6 +153,9 @@ Features Added
 Bugs Fixed
 ++++++++++
 
+- Document ``Products.PluginIndexes.PathIndex.PathIndex.insertEntry`` as
+  an API for use by subclasses.
+
 - LP #143655:  don't prevent sorting using a path index.
 
 - LP #142478:  normalize terms passed to ``PLexicon.queryLexicon`` using

src/Products/PluginIndexes/PathIndex/PathIndex.py

@@ -226,18 +226,11 @@ class PathIndex(Persistent, SimpleItem):
         """
         return self._unindex
 
-    # Helper methods
+    # IPathIndex implementation.
 
     def insertEntry(self, comp, id, level):
-        """ Insert an entry.
-
-        'comp' is an individual path component
-
-        'id' is the docid
-
-        .level'is the level of the component inside the path
+        """ See IPathIndex
         """
-
         if not self._index.has_key(comp):
             self._index[comp] = IOBTree()
 
@@ -248,6 +241,8 @@ class PathIndex(Persistent, SimpleItem):
         if level > self._depth:
             self._depth = level
 
+    # Helper methods
+
     def _search(self, path, default_level=0):
         """ Perform the actual search.
 

src/Products/PluginIndexes/PathIndex/tests/testPathIndex.py

@@ -456,6 +456,42 @@ class PathIndexTests(unittest.TestCase):
         self.assertEqual(dict(index.documentToKeyMap()),
                          dict([(k, v.path) for k, v in DUMMIES.items()]))
 
+    def test_insertEntry_empty_depth_0(self):
+        index = self._makeOne()
+        index.insertEntry('xx', 123, level=0)
+        self.assertEqual(index._depth, 0)
+        self.assertEqual(len(index._index), 1)
+        self.assertEqual(list(index._index['xx'][0]), [123])
+
+        # insertEntry oesn't update the length or the reverse index.
+        self.assertEqual(len(index), 0)
+        self.assertEqual(len(index._unindex), 0)
+        self.assertEqual(index._length(), 0)
+
+    def test_insertEntry_empty_depth_1(self):
+        index = self._makeOne()
+        index.insertEntry('xx', 123, level=0)
+        index.insertEntry('yy', 123, level=1)
+        self.assertEqual(index._depth, 1)
+        self.assertEqual(len(index._index), 2)
+        self.assertEqual(list(index._index['xx'][0]), [123])
+        self.assertEqual(list(index._index['yy'][1]), [123])
+
+    def test_insertEntry_multiple(self):
+        index = self._makeOne()
+        index.insertEntry('xx', 123, level=0)
+        index.insertEntry('yy', 123, level=1)
+        index.insertEntry('aa', 456, level=0)
+        index.insertEntry('bb', 456, level=1)
+        index.insertEntry('cc', 456, level=2)
+        self.assertEqual(index._depth, 2)
+        self.assertEqual(len(index._index), 5)
+        self.assertEqual(list(index._index['xx'][0]), [123])
+        self.assertEqual(list(index._index['yy'][1]), [123])
+        self.assertEqual(list(index._index['aa'][0]), [456])
+        self.assertEqual(list(index._index['bb'][1]), [456])
+        self.assertEqual(list(index._index['cc'][2]), [456])
+
     def test__search_empty_index_string_query(self):
         index = self._makeOne()
         self.assertEqual(list(index._search('/xxx')), [])

src/Products/PluginIndexes/interfaces.py

@@ -157,6 +157,18 @@ class IPathIndex(Interface):
     - the value is a mapping 'level of the path component' to
       'all docids with this path component on this level'
     """
+    def insertEntry(comp, id, level):
+        """ Insert an entry.
+
+        This method is intended for use by subclasses:  it is not
+        a normal API for the index.
+
+        'comp' is an individual path component
+
+        'id' is the docid
+
+        .level'is the level of the component inside the path
+        """
 
 
 class IFilteredSet(Interface):