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

https://github.com/python-ldap/python-ldap/pull/262

Doc/reference/ldap.rst

@@ -329,6 +329,13 @@ 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.
 
+   The field :py:const:`msgid` is set in the dictionary where the
+   exception can be associated with an asynchronous request.
+   This can be used in asynchronous code where :py:meth:`result()` raises the
+   result of an operation as an exception. For example, this is the case for
+   :py:meth:`compare()`, always raises the boolean result 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):
     """