python-ldap

python-ldap gives Python programs a native, object-oriented API for talking to LDAP directory servers. Rather than reimplementing the LDAP protocol, it compiles a thin C extension against OpenLDAP’s own libldap and Cyrus SASL libraries, then layers idiomatic Python classes — SimpleLDAPObject, ReconnectLDAPObject, and typed wrappers for LDAPv3 controls, schema, and LDIF — on top. The result stays close to the underlying C semantics (explicit message IDs, async result polling, error codes mapped to LDAPError subclasses) while remaining usable from ordinary Python code.

Beyond base bind/search/modify operations, the package includes broad support for LDAPv3 extended controls (paged results, VLV, password policy, session tracking, sync replication), SASL bind mechanisms, LDIF parsing/writing, LDAP URL handling, and a slapd-backed test harness used by its own test suite. It has shipped since the early 2000s and remains the de facto standard LDAP client for Python, used for directory-backed authentication, user/group provisioning, and directory synchronization.

What You Get

• SimpleLDAPObject / ReconnectLDAPObject - core client classes for bind, search, add, modify, delete, and compare operations, with an opt-in auto-reconnecting variant
• LDAPv3 controls package - typed encode/decode support for paged results, VLV, password policy, session tracking, deref, and sync replication controls
• SASL bind support - Cyrus SASL mechanism wrappers (ldap.sasl) for GSSAPI/Kerberos, DIGEST-MD5, and other non-simple binds
• Schema and LDIF utilities - ldap.schema for parsing LDAPv3 subschema subentries, plus standalone ldapurl and ldif modules with no C dependency
• slapd-backed test harness - slapdtest spins up a real OpenLDAP server for integration testing instead of mocking the protocol

Common Use Cases

• Directory-backed authentication - validating usernames and passwords against an LDAP/Active Directory server via simple or SASL bind
• User and group provisioning - scripting create/update/delete operations against a corporate directory from Python automation or admin tools
• Directory synchronization - using the syncrepl and psearch controls to stream and react to changes in a directory in near-real-time
• LDIF import/export tooling - parsing or generating LDIF files for directory migrations and bulk edits

Under The Hood

Architecture Hybrid Python/C architecture: a C extension module (built from Modules/*.c — ldapmodule.c, LDAPObject.c, options.c, functions.c, message.c, ldapcontrol.c, berval.c, constants.c) wraps OpenLDAP’s C client library and is imported into ldap/init.py, which immediately verifies the C module and Python package version numbers match. On top, Lib/ldap/ layers pure Python: ldapobject.py defines SimpleLDAPObject (wrapping every method of the C-level LDAPObject) and ReconnectLDAPObject, which adds automatic reconnect-and-retry semantics; ldap/controls/ implements LDAPv3 control encoding/decoding as separate per-control modules; ldap/schema/ parses LDAPv3 subschema subentries; ldap/sasl.py wraps Cyrus SASL bind mechanisms; ldapurl.py and ldif.py are standalone, dependency-free modules usable without the C extension. Application code calls SimpleLDAPObject methods, which dispatch into the C extension, which calls libldap; async LDAP message IDs are returned and resolved via result()/result3() polling. If the core C extension’s ABI changed, nearly everything downstream (ldapobject, controls, extop) would break, since all of it imports and calls directly into that module.

Tech Stack Python 3.9+ plus a C extension built against OpenLDAP’s libldap and Cyrus SASL headers, compiled via setuptools with a dedicated Build/ directory for locating the OpenLDAP/OpenSSL/SASL system libraries. Runtime Python dependencies are pyasn1 and pyasn1_modules, used for ASN.1/BER decoding of LDAP controls. The build backend is setuptools (PEP 621 pyproject.toml, dynamic version sourced from ldap/pkginfo.py). Tests run under tox across CPython 3.9-3.13 and PyPy 3.9/3.10 against a real slapd (OpenLDAP server) instance spun up by Tests/slapdtest; CI runs on GitHub Actions across Ubuntu and Fedora matrices, installing ldap-utils/slapd/libldap2-dev/libsasl2-dev system packages. Docs are built with Sphinx and hosted on Read the Docs.

Code Quality Tests/ contains roughly two dozen unittest-based modules covering URL parsing, DN handling, filters, individual controls (ppolicy, sss, readentry, sasl, syncrepl), schema tokenizing/subentries, cidict, and modlist, exercising both the C extension and Python layer directly; a dedicated t_untested_mods.py tracks coverage gaps. Integration tests run against a real slapd server rather than a protocol mock, trading CI complexity for high confidence. tox runs the suite with -bb -Werror (bytes-warnings and warnings promoted to errors), and the C build compiles with -Werror -std=c99. No type hints or mypy/ruff configuration were found beyond isort settings, lighter static-analysis tooling than a typical modern pure-Python project, consistent with this being a long-lived C-extension-backed package. CI runs on every push/PR across seven Python/PyPy versions plus a weekly scheduled run.

API Design SimpleLDAPObject deliberately mirrors the underlying C API almost method-for-method rather than offering a higher-level abstraction, which keeps behavior predictable for anyone who already knows LDAP’s bind/search/modify semantics but means callers manage async message IDs and result polling directly. ReconnectLDAPObject is an opt-in subclass that adds reconnection without hiding that model. Getting started requires understanding LDAP concepts (DNs, scopes, filters) up front — the API is not beginner-friendly, but it is thorough: the controls package (deref, ppolicy, pwdpolicy, sss, vlv, sessiontrack, psearch, syncrepl) gives unusually broad, maintained coverage of LDAPv3 extended controls that most other language bindings skip.