0
# Bonsai
1
2
A comprehensive Python LDAP library for accessing LDAP directory servers with asynchronous framework support and Windows Active Directory integration. Bonsai provides a pythonic interface with high-performance C extensions, dictionary-like LDAP entry handling, and extensive async framework support.
3
4
## Package Information
5
6
- **Package Name**: bonsai
7
- **Language**: Python
8
- **Installation**: `pip install bonsai`
9
10
## Core Imports
11
12
```python
13
import bonsai
14
```
15
16
Common imports for LDAP operations:
17
18
```python
19
from bonsai import LDAPClient, LDAPConnection, LDAPEntry, LDAPDN, LDAPURL
20
```
21
22
For async operations:
23
24
```python
25
from bonsai.asyncio import AIOLDAPConnection
26
from bonsai.gevent import GeventLDAPConnection
27
from bonsai.tornado import TornadoLDAPConnection
28
from bonsai.trio import TrioLDAPConnection
29
```
30
31
## Basic Usage
32
33
```python
34
from bonsai import LDAPClient
35
36
# Create LDAP client
37
client = LDAPClient("ldap://localhost")
38
client.set_credentials("SIMPLE", user="cn=admin,dc=example,dc=com", password="secret")
39
40
# Connect and perform operations
41
with client.connect() as conn:
42
# Search for entries
43
results = conn.search("dc=example,dc=com", 2)
44
45
# Access entry attributes
46
for entry in results:
47
print(f"DN: {entry.dn}")
48
print(f"Attributes: {dict(entry)}")
49
50
# Create new entry
51
new_entry = LDAPEntry("cn=newuser,dc=example,dc=com")
52
new_entry['objectClass'] = ['person', 'organizationalPerson']
53
new_entry['cn'] = 'newuser'
54
new_entry['sn'] = 'User'
55
56
# Add to directory
57
conn.add(new_entry)
58
```
59
60
## Architecture
61
62
Bonsai's architecture is built around several key components:
63
64
- **LDAPClient**: Configuration and connection factory for LDAP servers
65
- **LDAPConnection**: Active connection object providing all LDAP operations
66
- **LDAPEntry**: Dictionary-like interface for LDAP entries with change tracking
67
- **LDAPDN**: Distinguished name parsing and manipulation
68
- **LDAPURL**: LDAP URL parsing and construction
69
70
The library uses native LDAP libraries (libldap on Unix, WinLDAP on Windows) written in C for high performance, while providing a pythonic interface with automatic change tracking and comprehensive error handling.
71
72
## Capabilities
73
74
### Core LDAP Operations
75
76
Essential LDAP functionality including client configuration, connection management, entry operations, distinguished name handling, and URL parsing. These components provide the foundation for all LDAP interactions.
77
78
```python { .api }
79
class LDAPClient:
80
def __init__(self, url: str) -> None: ...
81
def connect(self, is_async: bool = False) -> LDAPConnection: ...
82
def set_credentials(self, mechanism: str, **kwargs) -> None: ...
83
84
class LDAPConnection:
85
def search(self, base: str, scope: int, filter_exp: str = None, **kwargs) -> list[LDAPEntry]: ...
86
def add(self, entry: LDAPEntry) -> None: ...
87
def modify(self, entry: LDAPEntry) -> None: ...
88
def delete(self, dn: str) -> None: ...
89
90
class LDAPEntry:
91
def __init__(self, dn: str) -> None: ...
92
def __getitem__(self, key: str) -> LDAPValueList: ...
93
def __setitem__(self, key: str, value) -> None: ...
94
```
95
96
[Core LDAP Operations](./core-ldap.md)
97
98
### Asynchronous Framework Support
99
100
Native integration with multiple Python async frameworks including asyncio, gevent, tornado, and trio. Each framework provides specialized connection classes optimized for their respective event loops.
101
102
```python { .api }
103
class AIOLDAPConnection(LDAPConnection):
104
async def search(self, base: str, scope: int, **kwargs) -> list[LDAPEntry]: ...
105
async def add(self, entry: LDAPEntry) -> None: ...
106
107
class GeventLDAPConnection(LDAPConnection):
108
def search(self, base: str, scope: int, **kwargs) -> list[LDAPEntry]: ...
109
110
class TornadoLDAPConnection(LDAPConnection):
111
def search(self, base: str, scope: int, **kwargs) -> Future[list[LDAPEntry]]: ...
112
```
113
114
[Async Framework Support](./async-frameworks.md)
115
116
### Active Directory Integration
117
118
Comprehensive Windows Active Directory support including Security Identifiers (SID), Access Control Lists (ACL), Security Descriptors, and User Account Control flags.
119
120
```python { .api }
121
class SID:
122
def __init__(self, sid_string: str) -> None: ...
123
def __str__(self) -> str: ...
124
125
class SecurityDescriptor:
126
def __init__(self, descriptor: bytes) -> None: ...
127
@property
128
def owner(self) -> SID: ...
129
@property
130
def dacl(self) -> ACL: ...
131
132
class UserAccountControl:
133
def __init__(self, value: int) -> None: ...
134
@property
135
def account_disabled(self) -> bool: ...
136
```
137
138
[Active Directory Support](./active-directory.md)
139
140
### Connection Pooling
141
142
Connection pool management for handling multiple concurrent LDAP connections with automatic lifecycle management and configurable pool sizes.
143
144
```python { .api }
145
class ConnectionPool:
146
def __init__(self, client: LDAPClient, minconn: int = 1, maxconn: int = 10) -> None: ...
147
def get(self) -> LDAPConnection: ...
148
def put(self, conn: LDAPConnection) -> None: ...
149
```
150
151
[Connection Pooling](./connection-pooling.md)
152
153
### LDIF Format Support
154
155
Read and write LDAP Data Interchange Format (LDIF) files for data import/export and backup operations.
156
157
```python { .api }
158
class LDIFReader:
159
def __init__(self, input_file) -> None: ...
160
def parse(self) -> Iterator[tuple[str, dict]]: ...
161
162
class LDIFWriter:
163
def __init__(self, output_file) -> None: ...
164
def write_entry(self, dn: str, entry: dict) -> None: ...
165
```
166
167
[LDIF Support](./ldif-support.md)
168
169
### Utilities and Error Handling
170
171
Utility functions for escaping LDAP filter expressions and attribute values, plus comprehensive exception hierarchy for robust error handling.
172
173
```python { .api }
174
def escape_filter_exp(expression: str) -> str: ...
175
def escape_attribute_value(value: str) -> str: ...
176
def get_vendor_info() -> dict: ...
177
178
class LDAPError(Exception):
179
def __init__(self, error_message: str, error_code: int = None) -> None: ...
180
181
class AuthenticationError(LDAPError): ...
182
class ConnectionError(LDAPError): ...
183
```
184
185
[Utilities and Errors](./utilities-errors.md)
186
187
## Types
188
189
```python { .api }
190
from enum import IntEnum
191
192
class LDAPSearchScope(IntEnum):
193
BASE = 0
194
ONELEVEL = 1
195
SUBTREE = 2
196
197
class LDAPModOp(IntEnum):
198
ADD = 0
199
DELETE = 1
200
REPLACE = 2
201
202
class LDAPValueList(list):
203
def __init__(self, items=None) -> None: ...
204
def append(self, item) -> None: ...
205
def extend(self, items) -> None: ...
206
def insert(self, index: int, item) -> None: ...
207
def remove(self, item) -> None: ...
208
def clear(self) -> None: ...
209
210
@property
211
def added(self) -> set: ...
212
213
@property
214
def deleted(self) -> set: ...
215
216
@property
217
def status(self) -> int: ...
218
219
class LDAPSearchIter:
220
def __init__(self, conn: "LDAPConnection", base: str, scope: int, **kwargs) -> None: ...
221
def __iter__(self) -> "LDAPSearchIter": ...
222
def __next__(self) -> "LDAPEntry": ...
223
def acquire_next_page(self) -> None: ...
224
225
@property
226
def cookie(self) -> Optional[bytes]: ...
227
228
@property
229
def estimated_list_count(self) -> int: ...
230
231
class LDAPReference:
232
def __init__(self, client: "LDAPClient", references: List[Union[str, "LDAPURL"]]) -> None: ...
233
234
@property
235
def client(self) -> "LDAPClient": ...
236
237
@property
238
def references(self) -> List["LDAPURL"]: ...
239
```