Tests and documentation for msgid for exceptions raised from result4()

Doc/reference/ldap.rst

@@ -329,6 +329,14 @@ The module defines the following exceptions:
    is set to a truncated form of the name provided or alias dereferenced
    for the lowest entry (object or alias) that was matched.
 
+   For use in asynchronous operations an optional field :py:const:`msg_id` is
+   also set in the dictionary in cases where the exception can be associated
+   with a request. This can be used in asynchronous code where
+   :py:meth:`result()` returns an exception that is effectively the result of a
+   previously started asynchronous operation. For example, this is the case for
+   asynchronous (:py:meth:`compare()`), where the boolean result is always
+   raised as an exception (:py:exc:`COMPARE_TRUE` or :py:exc:`COMPARE_FALSE`).
+
    Most exceptions from protocol results also carry the :py:attr:`errnum`
    attribute.
 

Tests/t_ldapobject.py

@@ -673,6 +673,20 @@ def test_compare_s_invalidattr(self):
         with self.assertRaises(ldap.UNDEFINED_TYPE):
             result = l.compare_s('cn=Foo1,%s' % base, 'invalidattr', b'invalid')
 
+    def test_compare_true_exception_contains_message_id(self):
+        base = self.server.suffix
+        l = self._ldap_conn
+        msgid = l.compare('cn=Foo1,%s' % base, 'cn', b'Foo1')
+        with self.assertRaises(ldap.COMPARE_TRUE) as cm:
+            l.result()
+        self.assertEqual(cm.exception.args[0]["msgid"], msgid)
+
+    def test_async_search_no_such_object_exception_contains_message_id(self):
+        msgid = self._ldap_conn.search("CN=XXX", ldap.SCOPE_SUBTREE)
+        with self.assertRaises(ldap.NO_SUCH_OBJECT) as cm:
+            self._ldap_conn.result()
+        self.assertEqual(cm.exception.args[0]["msgid"], msgid)
+
 
 class Test01_ReconnectLDAPObject(Test00_SimpleLDAPObject):
     """