Installation and configuration

Installation is straightforward and can be done via a package manager or from the source.

Installation with a package manager

You need the pip package (or another package manager that can download and install from pyPI) to install ldap3. Then you can download and install the ldap3 library directly from pyPI:

pip install ldap3

This library has only one dependence on the pyasn1 module, You can install it or let the installer do it for you.

If you need to access a server with the Kerberos SASL authentication mechanism you must install the gssapi package.

ldap3 includes a backport (from Python 3.4.3) of ssl.check_hostnames to be used on older (version < 2.7.10) Python version. If you want to use a more up to date version of the check_hostnames feature you can install the backports.ssl_check_hostnames package that should be kept updated with the Standard Library of the latest Python release by its maintainers.

Installation from the source

You can download the latest source from https://github.com/cannatag/ldap3 then you can install the library with:

python setup.py install

Global configuration

in the ldap3.utils.config package there are some configurable settings:

  • POOLING_LOOP_TIMEOUT = 10 # number of seconds to wait before restarting a cycle to find an active server in the pool

  • RESPONSE_SLEEPTIME = 0.05 # seconds to wait while waiting for a response in asynchronous strategies

  • RESPONSE_WAITING_TIMEOUT = 3 # waiting timeout for receiving a response in asynchronous strategies

  • SOCKET_SIZE = 4096 # socket byte size

  • CHECK_AVAILABILITY_TIMEOUT = 2.5 # default timeout for socket connect when checking availability

  • RESET_AVAILABILITY_TIMEOUT = 5 # default timeout for resetting the availability status when checking candidate addresses

  • RESTARTABLE_SLEEPTIME = 2 # time to wait in a restartable strategy before retrying the request

  • RESTARTABLE_TRIES = 30 # number of times to retry in a restartable strategy before giving up. Set to True for unlimited retries

  • REUSABLE_THREADED_POOL_SIZE = 5

  • REUSABLE_THREADED_LIFETIME = 3600 # 1 hour

  • DEFAULT_THREADED_POOL_NAME = ‘REUSABLE_DEFAULT_POOL’

  • ADDRESS_INFO_REFRESH_TIME = 300 # seconds to wait before refreshing address info from dns

  • ADDITIONAL_ENCODINGS = [‘latin-1’] # some broken LDAP implementation may have different encoding than those expected by RFCs

  • IGNORE_MALFORMED_SCHEMA = False # some flaky LDAP servers returns malformed schema. If True no expection is raised and schema is thrown away

This parameters are library-wide and usually you should keep the default values.

You can use the get_config_parameter() and set_config_parameter() functions in the ldap3 namespace to get and set the configurable parameters at runtime.

Importing objects and constants

All objects and constants needed to use the ldap3 library can be imported from the ldap3 namespace:

from ldap3 import Connection, Server, ANONYMOUS, SIMPLE, SYNC, ASYNC

Library errors

You can deal with errors in two different ways. By default in synchronous strategies each LDAP operation returns a True/False value that specify if the operation has been successful or not. In case of failures you can check the error description in the `last_error` attribute of the Connection object. In some cases an exception of the custom hierarchy starting from the `LDAPExceptionError` class is raised with a description of the error condition in the args attribute.

If you prefer to deal always with Exceptions you can set the raise_exceptions attribute to True in the Connection object definition. From now on the Connection will raise exceptions for all operations that return result codes different from RESULT_SUCCESS, RESULT_COMPARE_FALSE, RESULT_COMPARE_TRUE, RESULT_REFERRAL.

Communication exceptions have multiple inheritance either from `LDAPCommunicationError` and the specific socket exception.

Exceptions are defined in the ldap3.core.exceptions package.