# twisted/ldaptor architecture

> Architecture diagram of the GitHub repository twisted/ldaptor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/twisted/ldaptor
- Repository: https://github.com/twisted/ldaptor

## Overview

Ldaptor is a Python LDAP library and command-line toolkit. Its primary workflow connects to an LDAP server, binds, searches through a Pythonic entry API, and returns entries that can be rendered as LDIF or edited. The architecture also includes server-side and in-memory directory implementations, proxy/merge support, and LDAP/BER and filter codecs. Edges reflect the README example, sampled calls, or SOURCE INDEX references; unsampled utility and integration wiring is not inferred.

Main entry points: [`ldaptor/protocols/ldap/ldapsyntax.py`](https://github.com/twisted/ldaptor/blob/master/ldaptor/protocols/ldap/ldapsyntax.py) (Entry API), [`ldaptor/protocols/ldap/ldapclient.py`](https://github.com/twisted/ldaptor/blob/master/ldaptor/protocols/ldap/ldapclient.py) (LDAP client), [`ldaptor/entry.py`](https://github.com/twisted/ldaptor/blob/master/ldaptor/entry.py) (Directory entries), [`ldaptor/protocols/ldap/ldapserver.py`](https://github.com/twisted/ldaptor/blob/master/ldaptor/protocols/ldap/ldapserver.py) (LDAP server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["LDAP client"]
  node_connector["Connection setup<br/>[ldapconnector.py]"]
  node_clientproto["LDAP client<br/>[ldapclient.py]"]
  node_entryapi["Entry API<br/>[ldapsyntax.py]"]
end

subgraph group_protocol["Protocol codecs"]
  node_filter["Filter parsing<br/>[ldapfilter.py]"]
  node_ldapwire["LDAP messages<br/>[pureldap.py]"]
  node_ber["BER encoding<br/>[pureber.py]"]
  node_ldif["LDIF conversion<br/>[ldif.py]"]
  node_errors["LDAP errors<br/>[ldaperrors.py]"]
end

subgraph group_directory["Directory model"]
  node_dn["Distinguished names"]
  node_entry["Directory entries<br/>[entry.py]"]
  node_delta["Entry changes<br/>[delta.py]"]
  node_attributes["Attribute sets<br/>[attributeset.py]"]
  node_memory[("In-memory directory<br/>[inmemory.py]")]
  node_tree[("LDIF directory tree<br/>[ldiftree.py]")]
  node_samba["Samba password logic<br/>[ldapsyntax.py]"]
end

subgraph group_server["Server and proxy"]
  node_serverproto["LDAP server<br/>[ldapserver.py]"]
  node_proxy["Proxy base<br/>[proxybase.py]"]
  node_merger["Directory merger<br/>[merger.py]"]
end

subgraph group_tools["LDAP utilities"]
  node_config["LDAP configuration<br/>[config.py]"]
  node_scripts["Command-line tools"]
end

node_user(("Application"))

node_user -->|"connects"| node_connector
node_connector -->|"creates connection"| node_clientproto
node_user -->|"binds"| node_clientproto
node_user -->|"searches"| node_entryapi
node_entryapi -->|"issues LDAP operations"| node_clientproto
node_entryapi -->|"builds search filter"| node_filter
node_clientproto -->|"encodes operations"| node_ldapwire
node_ldapwire -->|"uses BER"| node_ber
node_entryapi -->|"models entries"| node_entry
node_entry -->|"stores attributes"| node_attributes
node_entryapi -->|"journals changes"| node_delta
node_entry -->|"parses name"| node_dn
node_entry -->|"renders LDIF"| node_ldif
node_serverproto -->|"handles messages"| node_ldapwire
node_serverproto -->|"uses directory"| node_memory
node_tree -->|"loads entries"| node_entry
node_proxy -->|"extends server"| node_serverproto
node_merger -->|"connects upstream"| node_clientproto
node_merger -->|"serves merged data"| node_serverproto
node_scripts -.->|"uses client"| node_clientproto
node_scripts -.->|"queries entries"| node_entryapi
node_scripts -.->|"reads settings"| node_config
node_clientproto -->|"raises results"| node_errors
node_entryapi -->|"selects password handling"| node_samba

click node_connector "https://github.com/twisted/ldaptor/blob/master/ldaptor/protocols/ldap/ldapconnector.py"
click node_clientproto "https://github.com/twisted/ldaptor/blob/master/ldaptor/protocols/ldap/ldapclient.py"
click node_entryapi "https://github.com/twisted/ldaptor/blob/master/ldaptor/protocols/ldap/ldapsyntax.py"
click node_dn "https://github.com/twisted/ldaptor/blob/master/ldaptor/protocols/ldap/distinguishedname.py"
click node_filter "https://github.com/twisted/ldaptor/blob/master/ldaptor/ldapfilter.py"
click node_ldapwire "https://github.com/twisted/ldaptor/blob/master/ldaptor/protocols/pureldap.py"
click node_ber "https://github.com/twisted/ldaptor/blob/master/ldaptor/protocols/pureber.py"
click node_entry "https://github.com/twisted/ldaptor/blob/master/ldaptor/entry.py"
click node_delta "https://github.com/twisted/ldaptor/blob/master/ldaptor/delta.py"
click node_attributes "https://github.com/twisted/ldaptor/blob/master/ldaptor/attributeset.py"
click node_memory "https://github.com/twisted/ldaptor/blob/master/ldaptor/inmemory.py"
click node_tree "https://github.com/twisted/ldaptor/blob/master/ldaptor/ldiftree.py"
click node_serverproto "https://github.com/twisted/ldaptor/blob/master/ldaptor/protocols/ldap/ldapserver.py"
click node_proxy "https://github.com/twisted/ldaptor/blob/master/ldaptor/protocols/ldap/proxybase.py"
click node_merger "https://github.com/twisted/ldaptor/blob/master/ldaptor/protocols/ldap/merger.py"
click node_config "https://github.com/twisted/ldaptor/blob/master/ldaptor/config.py"
click node_scripts "https://github.com/twisted/ldaptor/tree/master/ldaptor/_scripts"
click node_ldif "https://github.com/twisted/ldaptor/blob/master/ldaptor/protocols/ldap/ldif.py"
click node_errors "https://github.com/twisted/ldaptor/blob/master/ldaptor/protocols/ldap/ldaperrors.py"
click node_samba "https://github.com/twisted/ldaptor/blob/master/ldaptor/protocols/ldap/ldapsyntax.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_connector,node_clientproto,node_entryapi toneBlue
class node_filter,node_ldapwire,node_ber,node_ldif,node_errors toneAmber
class node_dn,node_entry,node_delta,node_attributes,node_memory,node_tree,node_samba toneMint
class node_serverproto,node_proxy,node_merger toneRose
class node_config,node_scripts,node_user toneIndigo
```

## Components

### LDAP client

- [Connection setup](https://github.com/twisted/ldaptor/blob/master/ldaptor/protocols/ldap/ldapconnector.py): `ldaptor/protocols/ldap/ldapconnector.py`
- [LDAP client](https://github.com/twisted/ldaptor/blob/master/ldaptor/protocols/ldap/ldapclient.py): `ldaptor/protocols/ldap/ldapclient.py`
- [Entry API](https://github.com/twisted/ldaptor/blob/master/ldaptor/protocols/ldap/ldapsyntax.py): `ldaptor/protocols/ldap/ldapsyntax.py`

### Protocol codecs

- [Filter parsing](https://github.com/twisted/ldaptor/blob/master/ldaptor/ldapfilter.py): `ldaptor/ldapfilter.py`
- [LDAP messages](https://github.com/twisted/ldaptor/blob/master/ldaptor/protocols/pureldap.py): `ldaptor/protocols/pureldap.py`
- [BER encoding](https://github.com/twisted/ldaptor/blob/master/ldaptor/protocols/pureber.py): `ldaptor/protocols/pureber.py`
- [LDIF conversion](https://github.com/twisted/ldaptor/blob/master/ldaptor/protocols/ldap/ldif.py): `ldaptor/protocols/ldap/ldif.py`
- [LDAP errors](https://github.com/twisted/ldaptor/blob/master/ldaptor/protocols/ldap/ldaperrors.py): `ldaptor/protocols/ldap/ldaperrors.py`

### Directory model

- [Distinguished names](https://github.com/twisted/ldaptor/blob/master/ldaptor/protocols/ldap/distinguishedname.py): `ldaptor/protocols/ldap/distinguishedname.py`
- [Directory entries](https://github.com/twisted/ldaptor/blob/master/ldaptor/entry.py): `ldaptor/entry.py`
- [Entry changes](https://github.com/twisted/ldaptor/blob/master/ldaptor/delta.py): `ldaptor/delta.py`
- [Attribute sets](https://github.com/twisted/ldaptor/blob/master/ldaptor/attributeset.py): `ldaptor/attributeset.py`
- [In-memory directory](https://github.com/twisted/ldaptor/blob/master/ldaptor/inmemory.py): `ldaptor/inmemory.py`
- [LDIF directory tree](https://github.com/twisted/ldaptor/blob/master/ldaptor/ldiftree.py): `ldaptor/ldiftree.py`
- [Samba password logic](https://github.com/twisted/ldaptor/blob/master/ldaptor/protocols/ldap/ldapsyntax.py): `ldaptor/protocols/ldap/ldapsyntax.py`

### Server and proxy

- [LDAP server](https://github.com/twisted/ldaptor/blob/master/ldaptor/protocols/ldap/ldapserver.py): `ldaptor/protocols/ldap/ldapserver.py`
- [Proxy base](https://github.com/twisted/ldaptor/blob/master/ldaptor/protocols/ldap/proxybase.py): `ldaptor/protocols/ldap/proxybase.py`
- [Directory merger](https://github.com/twisted/ldaptor/blob/master/ldaptor/protocols/ldap/merger.py): `ldaptor/protocols/ldap/merger.py`

### LDAP utilities

- [LDAP configuration](https://github.com/twisted/ldaptor/blob/master/ldaptor/config.py): `ldaptor/config.py`
- [Command-line tools](https://github.com/twisted/ldaptor/tree/master/ldaptor/_scripts): `ldaptor/_scripts`

### Other components

- **Application**

## Connections

- Application → Connection setup: connects
- Connection setup → LDAP client: creates connection (evidence: `ldaptor/protocols/ldap/ldapconnector.py`)
- Application → LDAP client: binds
- Application → Entry API: searches
- Entry API → LDAP client: issues LDAP operations (evidence: `ldaptor/protocols/ldap/ldapsyntax.py`)
- Entry API → Filter parsing: builds search filter (evidence: `ldaptor/protocols/ldap/ldapsyntax.py`)
- LDAP client → LDAP messages: encodes operations (evidence: `ldaptor/protocols/ldap/ldapclient.py`)
- LDAP messages → BER encoding: uses BER (evidence: `ldaptor/protocols/pureldap.py`)
- Entry API → Directory entries: models entries (evidence: `ldaptor/protocols/ldap/ldapsyntax.py`)
- Directory entries → Attribute sets: stores attributes (evidence: `ldaptor/entry.py`)
- Entry API → Entry changes: journals changes (evidence: `ldaptor/protocols/ldap/ldapsyntax.py`)
- Directory entries → Distinguished names: parses name (evidence: `ldaptor/entry.py`)
- Directory entries → LDIF conversion: renders LDIF (evidence: `ldaptor/entry.py`)
- LDAP server → LDAP messages: handles messages (evidence: `ldaptor/protocols/ldap/ldapserver.py`)
- LDAP server → In-memory directory: uses directory (evidence: `ldaptor/protocols/ldap/ldapserver.py`)
- LDIF directory tree → Directory entries: loads entries (evidence: `ldaptor/ldiftree.py`)
- Proxy base → LDAP server: extends server (evidence: `ldaptor/protocols/ldap/proxybase.py`)
- Directory merger → LDAP client: connects upstream (evidence: `ldaptor/protocols/ldap/merger.py`)
- Directory merger → LDAP server: serves merged data (evidence: `ldaptor/protocols/ldap/merger.py`)
- Command-line tools → LDAP client: uses client (evidence: `ldaptor/_scripts/search.py`)
- Command-line tools → Entry API: queries entries (evidence: `ldaptor/_scripts/search.py`)
- Command-line tools → LDAP configuration: reads settings (evidence: `ldaptor/_scripts/search.py`)
- LDAP client → LDAP errors: raises results (evidence: `ldaptor/protocols/ldap/ldapclient.py`)
- Entry API → Samba password logic: selects password handling (evidence: `ldaptor/protocols/ldap/ldapsyntax.py`)
