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 pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy