Skip to content

Document the LDAPError fields #355

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jun 18, 2020
Merged

Document the LDAPError fields #355

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
6a1fc4d
Document the LDAPError fields
encukou Jun 18, 2020
dc15cf5
Adjust wording
encukou Jun 18, 2020
ad27e33
Document "result" and "errno"
encukou Jun 18, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 25 additions & 24 deletions Doc/reference/ldap.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -462,26 +462,27 @@ 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.
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 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.
* ``'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.
* ``'errno'``: the C ``errno``, usually set by system calls or ``libc``
rather than the LDAP libraries.

.. py:exception:: ADMINLIMIT_EXCEEDED

Expand Down Expand Up @@ -515,14 +516,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

Expand Down