From 6a1fc4d66b9587fcaf22951d4e38a347f501be4e Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Thu, 18 Jun 2020 11:43:35 +0200 Subject: [PATCH 1/3] Document the LDAPError fields Also, correct the note on COMPARE_FALSE and COMPARE_TRUE --- Doc/reference/ldap.rst | 45 ++++++++++++++++++++---------------------- 1 file changed, 21 insertions(+), 24 deletions(-) diff --git a/Doc/reference/ldap.rst b/Doc/reference/ldap.rst index 164e2b6a..43314b33 100644 --- a/Doc/reference/ldap.rst +++ b/Doc/reference/ldap.rst @@ -462,26 +462,23 @@ The module defines the following exceptions: are instead turned into exceptions, raised as soon an the error condition is detected. - The exceptions are accompanied by a dictionary possibly - containing an string value for the key :py:const:`desc` - (giving an English description of the error class) - and/or a string value for the key :py:const:`info` - (giving a string containing more information that the server may have sent). - - A third possible field of this dictionary is :py:const:`matched` and - 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. - + The exceptions are accompanied by a dictionary with additional information. + The following fields are set in the dictionary if the relevant information + is available: + + * ``'desc'``: string giving an English description of the error class. + * ``'info'``: string containing more information that the server may + have sent. + * ``'errnum'``: numeric error code. + * ``'matched'``: truncated form of the name provided or alias. + dereferenced for the lowest entry (object or alias) that was matched. + * ``'msgid'``: ID of the matching 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:`~LDAPObject.compare()`, always raises the boolean result as an + exception (:py:exc:`COMPARE_TRUE` or :py:exc:`COMPARE_FALSE`). + * ``'ctrls'``: list of :py:class:`ldap.controls.LDAPControl` instances + attached to the error. .. py:exception:: ADMINLIMIT_EXCEEDED @@ -515,14 +512,14 @@ The module defines the following exceptions: .. py:exception:: COMPARE_FALSE A compare operation returned false. - (This exception should never be seen because :py:meth:`compare()` returns - a boolean result.) + (This exception should only be seen asynchronous operations, because + :py:meth:`~LDAPObject.compare_s()` returns a boolean result.) .. py:exception:: COMPARE_TRUE A compare operation returned true. - (This exception should never be seen because :py:meth:`compare()` returns - a boolean result.) + (This exception should only be seen asynchronous operations, because + :py:meth:`~LDAPObject.compare_s()` returns a boolean result.) .. py:exception:: CONFIDENTIALITY_REQUIRED From dc15cf54d3d2c220d0c4d52e21a79afeaa915698 Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Thu, 18 Jun 2020 15:05:41 +0200 Subject: [PATCH 2/3] Adjust wording - All fields are optional and more fields may be added in the future - desc might not be English. It comes from ldap_err2string - info is server-specific - there is errno, no errnum --- Doc/reference/ldap.rst | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/Doc/reference/ldap.rst b/Doc/reference/ldap.rst index 43314b33..f26cbc54 100644 --- a/Doc/reference/ldap.rst +++ b/Doc/reference/ldap.rst @@ -463,13 +463,15 @@ The module defines the following exceptions: is detected. The exceptions are accompanied by a dictionary with additional information. - The following fields are set in the dictionary if the relevant information - is available: + All fields are optional and more fields may be added in the future. + Currently, ``python-ldap`` may set the following fields: - * ``'desc'``: string giving an English description of the error class. + * ``'desc'``: string giving a description of the error class, as provided + by OpenLDAP's ``ldap_err2string``. * ``'info'``: string containing more information that the server may - have sent. - * ``'errnum'``: numeric error code. + have sent. The value is server-specific: for example, the OpenLDAP server + may send different info messages than Active Directory or 389-DS. + * ``'errno'``: numeric error code. * ``'matched'``: truncated form of the name provided or alias. dereferenced for the lowest entry (object or alias) that was matched. * ``'msgid'``: ID of the matching asynchronous request. From ad27e33a386b7f99381c3a0c24f655831254830e Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Thu, 18 Jun 2020 15:47:56 +0200 Subject: [PATCH 3/3] Document "result" and "errno" --- Doc/reference/ldap.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/Doc/reference/ldap.rst b/Doc/reference/ldap.rst index f26cbc54..a6d69287 100644 --- a/Doc/reference/ldap.rst +++ b/Doc/reference/ldap.rst @@ -466,12 +466,12 @@ The module defines the following exceptions: All fields are optional and more fields may be added in the future. Currently, ``python-ldap`` may set the following fields: + * ``'result'``: a numeric code of the error class. * ``'desc'``: string giving a description of the error class, as provided - by OpenLDAP's ``ldap_err2string``. + by calling OpenLDAP's ``ldap_err2string`` on the ``result``. * ``'info'``: string containing more information that the server may have sent. The value is server-specific: for example, the OpenLDAP server may send different info messages than Active Directory or 389-DS. - * ``'errno'``: numeric error code. * ``'matched'``: truncated form of the name provided or alias. dereferenced for the lowest entry (object or alias) that was matched. * ``'msgid'``: ID of the matching asynchronous request. @@ -481,6 +481,8 @@ The module defines the following exceptions: exception (:py:exc:`COMPARE_TRUE` or :py:exc:`COMPARE_FALSE`). * ``'ctrls'``: list of :py:class:`ldap.controls.LDAPControl` instances attached to the error. + * ``'errno'``: the C ``errno``, usually set by system calls or ``libc`` + rather than the LDAP libraries. .. py:exception:: ADMINLIMIT_EXCEEDED