1.1.5.1 LDAP operations

abandon(msgid): Abandons or cancels an LDAP operation in progress. The msgid argument should be the message ID of an outstanding LDAP operation as returned by the asynchronous methods search(), modify(), etc. The caller can expect that the result of an abandoned operation will not be returned from a future call to result().

add(dn, modlist)
add_s(dn, modlist): This function is similar to modify(), except that the operation integer is omitted from the tuples in modlist.

bind(who, cred, method)
bind_s(who, cred, method)
simple_bind(who, passwd)
simple_bind_s(who, passwd): After an LDAP object is created, and before any other operations can be attempted over the connection, a bind operation must be performed.
This method attempts to bind with the LDAP server using either simple authentication, or Kerberos (if available). The first and most general method, bind(), takes a third parameter, method, which can currently solely be AUTH_SIMPLE.

compare(dn, attr, value)

compare_s(dn, attr, value)

Perform an LDAP comparison between the attribute named attr of entry dn, and the value value. The synchronous form returns 0 for false, or 1 for true. The asynchronous form returns the message ID of the initiated request, and the result of the asynchronous compare can be obtained using result().

Note that the asynchronous technique yields the answer by raising the exception objects COMPARE_TRUE or COMPARE_FALSE.

Note A design fault in the LDAP API prevents value from containing nul characters.

delete(dn)
delete_s(dn): Performs an LDAP delete operation on dn. The asynchronous form returns the message id of the initiated request, and the result can be obtained from a subsequent call to result().

modify( dn, modlist )

modify_s( dn, modlist )

Performs an LDAP modify operation on an entry's attributes. The dn argument is the distinguished name (DN) of the entry to modify, and modlist is a list of modifications to make to that entry.

Each element in the list modlist should be a tuple of the form (mod_op,mod_type,mod_vals), where mod_op indicates the operation (one of MOD_ADD, MOD_DELETE, or MOD_REPLACE), mod_type is a string indicating the attribute type name, and mod_vals is either a string value or a list of string values to add, delete or replace respectively. For the delete operation, mod_vals may be None indicating that all attributes are to be deleted.

The asynchronous method modify() returns the message ID of the initiated request.

modrdn(dn, newrdn [, delold=1])
modrdn_s(dn, newrdn [, delold=1]): Perform a `modify RDN' operation, (i.e. a renaming operation). These routines take dn (the DN of the entry whose RDN is to be changed, and newrdn, the new RDN to give to the entry. The optional parameter delold is used to specify whether the old RDN should be kept as an attribute of the entry or not. (Note: This may not actually be supported by the underlying library.) The asynchronous version returns the initiated message id.

rename(dn, newrdn [, newsuperior=None][, delold=1])
rename_s(dn, newrdn [, newsuperior=None [, delold=1]]): Perform a `Rename' operation, (i.e. a renaming operation). These routines take dn (the DN of the entry whose RDN is to be changed, and newrdn, the new RDN to give to the entry. The optional parameter newsuperior is used to specify a new parent DN for moving an entry in the tree (not all LDAP servers support this). The optional parameter delold is used to specify whether the old RDN should be kept as an attribute of the entry or not.

result([ msgid=RES_ANY [, all=1 [, timeout=-1]]])

This method is used to wait for and return the result of an operation previously initiated by one of the LDAP asynchronous operations (eg search(), modify(), etc.)

The msgid parameter is the integer identifier returned by that method. The identifier is guaranteed to be unique across an LDAP session, and tells the result() method to request the result of that specific operation. If a result is desired from any one of the in-progress operations, msgid should be specified as the constant RES_ANY.

The all parameter has meaning only for search() responses, and is used to select whether a single entry of the search response should be returned, or whether the result() method should wait until all the results of the search are available before returning.

The timeout parameter is a limit on the number of seconds that the method will wait for a response from the server. If timeout is negative (which is the default), the method will wait indefinitely for a response. The timeout can be expressed as a floating-point value, and a value of 0 effects a poll. If a timeout does occur, a TIMEOUT exception is raised, unless polling, in which case (None, None) is returned.

The result() method returns a tuple of the form (result-type, result-data). The first element, result-type is a string, being one of: 'RES_BIND', 'RES_SEARCH_ENTRY', 'RES_SEARCH_RESULT', 'RES_MODIFY', 'RES_ADD', 'RES_DELETE', 'RES_MODRDN', or 'RES_COMPARE'. (The module constants RES_* are set to these strings, for your convenience.)

If all is 0, one response at a time is returned on each call to result(), with termination indicated by result-data being an empty list.

See search() for a description of the search result's result-data, otherwise the result-data is normally meaningless.

search(base, scope, filter [, attrlist=None[, attrsonly=0]])

search_s(base, scope, filter [, attrlist=None[, attrsonly=0]])

search_st(base, scope, filter [, attrlist=None[, attrsonly=0[, timeout=-1]]])

Perform an LDAP search operation, with base as the DN of the entry at which to start the search, scope being one of SCOPE_BASE (to search the object itself), SCOPE_ONELEVEL (to search the object's immediate children), or SCOPE_SUBTREE (to search the object and all its descendants).

The filter argument is a string representation of the filter to apply in the search. Simple filters can be specified as "attribute_type=attribute_value".

See Also:

RFC 2254, The String Representation of LDAP Search Filters

When using the asynchronous form and result(), the all parameter affects how results come in. For all set to 0, result tuples trickle in (with the same message id), and with the result type RES_SEARCH_ENTRY, until the final result which has a result type of RES_SEARCH_RESULT and a (usually) empty data field. When all is set to 1, only one result is returned, with a result type of RES_SEARCH_RESULT, and all the result tuples listed in the data field.

Each result tuple is of the form (dn,attrs), where dn is a string containing the DN (distinguished name) of the entry, and attrs is a dictionary containing the attributes associated with the entry. The keys of attrs are strings, and the associated values are lists of strings.

The DN in dn is extracted using the underlying ldap_get_dn() function, which may raise an exception if the DN is malformed.

If attrsonly is non-zero, the values of attrs will be meaningless (they are not transmitted in the result).

The retrieved attributes can be limited with the attrlist parameter. If attrlist is None, all the attributes of each entry are returned.

The synchronous form with timeout, search_st(), will block for at most timeout seconds (or indefinitely if timeout is negative). A TIMEOUT exception is raised if no result is received within the specified time.

set_rebind_proc(func)

If a referral is returned from the server, automatic re-binding can be achieved by providing a function that accepts as an argument the newly opened LDAP object and returns the tuple (who, cred, method).

Passing a value of None for func will disable this facility.

Because of restrictions in the implementation, only one rebinding function is supported at any one time. In addition, this method is only available if support is available in the underlying library (LDAP_REFERRALS).

unbind()
unbind_s(): This call is used to unbind from the directory, terminate the current association, and free resources. Once called, the connection to the LDAP server is closed and the LDAP object is marked invalid. Further invocation of methods on the object will yield exceptions.
The unbind() and unbind_s() methods are both synchronous in nature

url_search_s(url [, attrsonly=0])
url_search_s(url [, attrsonly=0 [, timeout=-1]]): These routine works much like the search() family of methods, except that many of the search parameters are extracted from the url argument.
LDAP URLs are fully described in RFC 2255.