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
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
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
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
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
Communication exceptions have multiple inheritance either from
`LDAPCommunicationError` and the specific socket exception.
Exceptions are defined in the ldap3.core.exceptions package.