1 from zope.interface import Interface
2
3 -class ILDAPEntry(Interface):
4 """
5
6 Pythonic API for LDAP object access and modification.
7
8 >>> o=LDAPEntry(client=ldapclient.LDAPClient(),
9 ... dn='cn=foo,dc=example,dc=com',
10 ... attributes={'anAttribute': ['itsValue', 'secondValue'],
11 ... 'onemore': ['aValue'],
12 ... })
13 >>> o
14 LDAPEntry(dn='cn=foo,dc=example,dc=com', attributes={'anAttribute': ['itsValue', 'secondValue'], 'onemore': ['aValue']})
15
16 """
17
18 - def __getitem__(self, key):
19 """
20
21 Get all values of an attribute.
22
23 >>> o=LDAPEntry(client=ldapclient.LDAPClient(),
24 ... dn='cn=foo,dc=example,dc=com',
25 ... attributes={'anAttribute': ['itsValue']})
26 >>> o['anAttribute']
27 ['itsValue']
28
29 """
30
31 - def get(self, key, default=None):
32 """
33
34 Get all values of an attribute.
35
36 >>> o=LDAPEntry(client=ldapclient.LDAPClient(),
37 ... dn='cn=foo,dc=example,dc=com',
38 ... attributes={'anAttribute': ['itsValue']})
39 >>> o.get('anAttribute')
40 ['itsValue']
41 >>> o.get('foo')
42 >>> o.get('foo', [])
43 []
44
45 """
46
47 - def has_key(self, key):
49
50 - def __contains__(self, key):
52
55
58
60 """
61
62 Stringify as LDIF.
63
64 >>> o=LDAPEntry(client=ldapclient.LDAPClient(),
65 ... dn='cn=foo,dc=example,dc=com',
66 ... attributes={'anAttribute': ['itsValue', 'secondValue'],
67 ... 'onemore': ['aValue'],
68 ... })
69 >>> # must use rstrip or doctests won't like it due to the empty line
70 >>> # you can just say "print o"
71 >>> print str(o).rstrip()
72 dn: cn=foo,dc=example,dc=com
73 anAttribute: itsValue
74 anAttribute: secondValue
75 onemore: aValue
76
77 """
78
79 - def __eq__(self, other):
80 """
81
82 Comparison. Only equality is supported.
83
84 >>> client=ldapclient.LDAPClient()
85 >>> a=LDAPEntry(client=client,
86 ... dn='dc=example,dc=com')
87 >>> b=LDAPEntry(client=client,
88 ... dn='dc=example,dc=com')
89 >>> a==b
90 1
91 >>> c=LDAPEntry(client=ldapclient.LDAPClient(),
92 ... dn='ou=different,dc=example,dc=com')
93 >>> a==c
94 0
95
96 Comparison does not consider the client of the object.
97
98 >>> anotherClient=ldapclient.LDAPClient()
99 >>> d=LDAPEntry(client=anotherClient,
100 ... dn='dc=example,dc=com')
101 >>> a==d
102 1
103
104 """
105
106 - def __ne__(self, other):
107 """
108
109 Inequality comparison. See L{__eq__}.
110
111 """
112
115
116 - def __nonzero__(self):
117 """Always return True"""
118
119 - def bind(self, password):
120 """
121 Try to authenticate with given secret.
122
123 @return: Deferred ILDAPEntry (that is, self).
124
125 @raise ldaperrors.LDAPInvalidCredentials: password was
126 incorrect.
127 """
128
129 -class IEditableLDAPEntry(Interface):
130 """Interface definition for editable LDAP entries."""
131
132 - def __setitem__(self, key, value):
133 """
134
135 Set values of an attribute. Please use lists. Do not modify
136 the lists in place, that's not supported _yet_.
137
138 >>> o=LDAPEntry(client=ldapclient.LDAPClient(),
139 ... dn='cn=foo,dc=example,dc=com',
140 ... attributes={'anAttribute': ['itsValue']})
141 >>> o['anAttribute']=['foo', 'bar']
142 >>> o['anAttribute']
143 ['bar', 'foo']
144
145 """
146
147 - def __delitem__(self, key):
148 """
149
150 Delete all values of an attribute.
151
152 >>> o=LDAPEntry(client=ldapclient.LDAPClient(),
153 ... dn='cn=foo,dc=example,dc=com',
154 ... attributes={
155 ... 'anAttribute': ['itsValue', 'secondValue'],
156 ... 'another': ['moreValues'],
157 ... })
158 >>> del o['anAttribute']
159 >>> o
160 LDAPEntry(dn='cn=foo,dc=example,dc=com', attributes={'another': ['moreValues']})
161
162 """
163
165 """
166 Forget all pending changes.
167 """
168
170 """
171 Send all pending changes to the LDAP server.
172
173 @returns: a Deferred that tells you whether the
174 operation succeeded or not. (TODO specify how)
175 """
176
177 - def move(self, newDN):
178 """
179
180 Move the object to a new DN.
181
182 @param newDN: the new DistinguishedName
183
184 @return: A Deferred that will complete when the move is done.
185
186 """
187
189 """
190
191 Delete this object from the LDAP server.
192
193 @return: A Deferred that will complete when the delete is done.
194
195 """
196
197 - def setPassword(self, newPasswd):
198 """
199
200 Set all applicable passwords for this object.
201
202 @param newPasswd: A string containing the new password.
203
204 @return: A Deferred that will complete when the operation is
205 done.
206
207 """
208
209 -class IConnectedLDAPEntry(Interface):
210 """Interface definition for LDAP entries that are part of a bigger whole."""
211
212 - def namingContext(self):
213 """
214
215 Return an LDAPEntry for the naming context that contains this object.
216
217 """
218
219 - def fetch(self, *attributes):
220 """
221
222 Fetch the attributes of this object from the server.
223
224 @param attributes: Attributes to fetch. If none, fetch all
225 attributes. Fetched attributes are overwritten, and if
226 fetching all attributes, attributes that are not on the server
227 are removed.
228
229 @return: A Deferred that will complete when the operation is
230 done.
231
232 """
233
234 - def search(self,
235 filterText=None,
236 filterObject=None,
237 attributes=(),
238 scope=None,
239 derefAliases=None,
240 sizeLimit=0,
241 timeLimit=0,
242 typesOnly=0,
243 callback=None):
244 """
245
246 Perform an LDAP search with this object as the base.
247
248 @param filterText: LDAP search filter as a string.
249
250 @param filterObject: LDAP search filter as LDAPFilter.
251 Note if both filterText and filterObject are given, they
252 are combined with AND. If neither is given, the search is
253 made with a filter that matches everything.
254
255 @param attributes: List of attributes to retrieve for the
256 result objects. An empty list and means all.
257
258 @param scope: Whether to recurse into subtrees.
259
260 @param derefAliases: Whether to deref LDAP aliases. TODO write
261 better documentation.
262
263 @param sizeLimit: At most how many entries to return. 0 means
264 unlimited.
265
266 @param timeLimit: At most how long to use for processing the
267 search request. 0 means unlimited.
268
269 @param typesOnly: Whether to return attribute types only, or
270 also values.
271
272 @param callback: Callback function to call for each resulting
273 LDAPEntry. None means gather the results into a list and give
274 that to the Deferred returned from here.
275
276 @return: A Deferred that will complete when the search is
277 done. The Deferred gives None if callback was given and a list
278 of the search results if callback is not given or is None.
279
280 """
281
282 - def children(self, callback=None):
283 """
284
285 List the direct children of this entry. Try to avoid using
286 .search(), as this will be used later to implement .search()
287 on LDAP backends.
288
289 @param callback: Callback function to call for each resulting
290 LDAPEntry. None means gather the results into a list and give
291 that to the Deferred returned from here.
292
293 @return: A Deferred that will complete when the list is
294 over. The Deferred gives None if callback was given and a list
295 of the children if callback is not given or is None.
296
297 """
298
299 - def subtree(self, callback=None):
300 """
301
302 List the subtree rooted at this entry, including this
303 entry. Try to avoid using .search(), as this will be used
304 later to implement .search() on LDAP backends.
305
306 @param callback: Callback function to call for each resulting
307 LDAPEntry. None means gather the results into a list and give
308 that to the Deferred returned from here.
309
310 @return: A Deferred that will complete when the list is
311 over. The Deferred gives None if callback was given and a list
312 of the children if callback is not given or is None.
313
314 """
315
316 - def lookup(self, dn):
317 """
318 Lookup the referred to by dn.
319
320 @return: A Deferred returning an ILDAPEntry, or failing with e.g.
321 LDAPNoSuchObject.
322 """
323
324 - def match(self, filter):
325 """
326
327 Does entry match filter.
328
329 @param filter: An LDAPFilter (e.g. LDAPFilter_present,
330 LDAPFilter_equalityMatch etc. TODO provide an interface or
331 superclass for filters.)
332
333 @return: Boolean.
334
335 """
336
338 """Generic LDAP configuration retrieval."""
339
341 """
342 Get the LDAP base DN, as a DistinguishedName.
343
344 Raises ldaptor.config.MissingBaseDNError
345 if configuration does not specify a base DN.
346 """
347
349 """
350 Get the LDAP service location overrides, as a mapping of
351 DistinguishedName to (host, port) tuples.
352 """
353
354 - def copy(self,
355 baseDN=None,
356 serviceLocationOverrides=None):
357 """
358 Make a copy of this configuration, overriding certain aspects
359 of it.
360 """
361
364
367