| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125 |
- .. % $Id: ldap.rst,v 1.26 2011/09/14 18:21:06 stroeder Exp $
- ********************************************
- :py:mod:`ldap` LDAP library interface module
- ********************************************
- .. py:module:: ldap
- :platform: Posix, Windows
- :synopsis: Access to an underlying LDAP C library.
- .. moduleauthor:: python-ldap project (see http://www.python-ldap.org/)
- This module provides access to the LDAP (Lightweight Directory Access Protocol)
- C API implemented in OpenLDAP 2.3 or newer. It is similar to the C API, with
- the notable differences that lists are manipulated via Python list operations
- and errors appear as exceptions. For far more detailed information on the C
- interface, please see the (expired) draft-ietf-ldapext-ldap-c-api-04. This
- documentation is current for the Python LDAP module, version |release|. Source
- and binaries are available from http://www.python-ldap.org/.
- Functions
- =========
- This module defines the following functions:
- .. py:function:: initialize(uri [, trace_level=0 [, trace_file=sys.stdout [, trace_stack_limit=None]]]) -> LDAPObject object
- Initializes a new connection object for accessing the given LDAP server,
- and return an LDAP object (see :ref:`ldap-objects`) used to perform operations
- on that server. Parameter *uri* has to be a valid LDAP URL.
- Note that the C wrapper function :py:func:_ldap.initialize() is called which calls
- the OpenLDAP funtion ldap_initialize(). Calling this function just initializes
- the LDAP connection struct in the C API - nothing else. The first call to
- an operation method (bind, search etc.) then really opens the connection.
- Before that nothing is sent on the wire.
- The optional arguments are for generating debug log information:
- *trace_level* specifies the amount of information being logged,
- *trace_file* specifies a file-like object as target of the debug log and
- *trace_stack_limit* specifies the stack limit of tracebacks in debug log.
- Possible values for *trace_level* are
- :py:const:`0` for no logging,
- :py:const:`1` for only logging the method calls with arguments,
- :py:const:`2` for logging the method calls with arguments and the complete results and
- :py:const:`9` for also logging the traceback of method calls.
- .. seealso::
- :rfc:`4516` - Lightweight Directory Access Protocol (LDAP): Uniform Resource Locator
- .. py:function:: open(host [, port=PORT]) -> LDAPObject object
- Opens a new connection with an LDAP server, and return an LDAP object (see
- :ref:`ldap-objects`) used to perform operations on that server. *host* is a
- string containing solely the host name. *port* is an integer specifying the
- port where the LDAP server is listening (default is 389).
- Note: Using this function is deprecated.
- .. py:function:: get_option(option) -> int|string
- This function returns the value of the global option specified by *option*.
- .. py:function:: set_option(option, invalue) -> None
- This function sets the value of the global option specified by *option* to
- *invalue*.
- .. _ldap-constants:
- Constants
- =========
- The module defines various constants. Note that some constants depend
- on the build options and which underlying libs were used or even on
- the version of the libs. So before using those constants the application has
- to explicitly check whether they are available.
- General
- -------
- .. py:data:: PORT
- The assigned TCP port number (389) that LDAP servers listen on.
- .. py:data:: SASL_AVAIL
- Integer where a non-zero value indicates that python-ldap was built with
- support for SASL (Cyrus-SASL).
- .. py:data:: TLS_AVAIL
- Integer where a non-zero value indicates that python-ldap was built with
- support for SSL/TLS (OpenSSL or similar libs).
- .. _ldap-options:
- Options
- -------
- .. seealso::
- :manpage:`ldap.conf{5}` and :manpage:`ldap_get_options{3}`
- For use with functions :py:func:set_option() and :py:func:get_option()
- and methods :py:method:LDAPObject.set_option() and :py:method:LDAPObject.get_option() the
- following option identifiers are defined as constants:
- .. py:data:: OPT_API_FEATURE_INFO
- .. py:data:: OPT_API_INFO
- .. py:data:: OPT_CLIENT_CONTROLS
- .. py:data:: OPT_DEBUG_LEVEL
- Sets the debug level within the underlying LDAP C lib.
- .. py:data:: OPT_DEFBASE
- .. py:data:: OPT_DEREF
- Specifies how alias derefencing is done within the underlying LDAP C lib.
- .. py:data:: OPT_ERROR_STRING
- .. py:data:: OPT_DIAGNOSTIC_MESSAGE
- .. py:data:: OPT_HOST_NAME
- .. py:data:: OPT_MATCHED_DN
- .. py:data:: OPT_NETWORK_TIMEOUT
- .. py:data:: OPT_PROTOCOL_VERSION
- Sets the LDAP protocol version used for a connection. This is mapped to
- object attribute `ldap.LDAPObject.protocol_version`
- .. py:data:: OPT_REFERRALS
- int specifying whether referrals should be automatically chased within
- the underlying LDAP C lib.
- .. py:data:: OPT_REFHOPLIMIT
- .. py:data:: OPT_RESTART
- .. py:data:: OPT_SERVER_CONTROLS
- .. py:data:: OPT_SIZELIMIT
- .. py:data:: OPT_SUCCESS
- .. py:data:: OPT_TIMELIMIT
- .. py:data:: OPT_TIMEOUT
- .. py:data:: OPT_URI
- .. _ldap-sasl-options:
- SASL options
- ::::::::::::
- .. py:data:: OPT_X_SASL_AUTHCID
- .. py:data:: OPT_X_SASL_AUTHZID
- .. py:data:: OPT_X_SASL_MECH
- .. py:data:: OPT_X_SASL_NOCANON
- If set to zero SASL host name canonicalization is disabled.
- .. py:data:: OPT_X_SASL_REALM
- .. py:data:: OPT_X_SASL_SECPROPS
- .. py:data:: OPT_X_SASL_SSF
- .. py:data:: OPT_X_SASL_SSF_EXTERNAL
- .. py:data:: OPT_X_SASL_SSF_MAX
- .. py:data:: OPT_X_SASL_SSF_MIN
- .. _ldap-tls-options:
- TLS options
- :::::::::::
- .. py:data:: OPT_X_TLS
- .. py:data:: OPT_X_TLS_ALLOW
- .. py:data:: OPT_X_TLS_CACERTDIR
- .. py:data:: OPT_X_TLS_CACERTFILE
- .. py:data:: OPT_X_TLS_CERTFILE
- .. py:data:: OPT_X_TLS_CIPHER_SUITE
- .. py:data:: OPT_X_TLS_CTX
- .. py:data:: OPT_X_TLS_DEMAND
- .. py:data:: OPT_X_TLS_HARD
- .. py:data:: OPT_X_TLS_KEYFILE
- .. py:data:: OPT_X_TLS_NEVER
- .. py:data:: OPT_X_TLS_RANDOM_FILE
- .. py:data:: OPT_X_TLS_REQUIRE_CERT
- .. py:data:: OPT_X_TLS_TRY
- .. _ldap-keepalive-options:
- Keepalive options
- :::::::::::::::::
- .. py:data:: OPT_X_KEEPALIVE_IDLE
- .. py:data:: OPT_X_KEEPALIVE_PROBES
- .. py:data:: OPT_X_KEEPALIVE_INTERVAL
- .. _ldap-dn-flags:
- DN format flags
- ----------------
- This constants are used for DN-parsing functions found in
- sub-module :py:mod:`ldap.dn`.
- .. seealso::
- :manpage:`ldap_str2dn{3}`
- .. py:data:: DN_FORMAT_LDAP
- .. py:data:: DN_FORMAT_LDAPV3
- .. py:data:: DN_FORMAT_LDAPV2
- .. py:data:: DN_FORMAT_DCE
- .. py:data:: DN_FORMAT_UFN
- .. py:data:: DN_FORMAT_AD_CANONICAL
- .. py:data:: DN_FORMAT_MASK
- .. py:data:: DN_PRETTY
- .. py:data:: DN_SKIP
- .. py:data:: DN_P_NOLEADTRAILSPACES
- .. py:data:: DN_P_NOSPACEAFTERRDN
- .. py:data:: DN_PEDANTIC
- .. _ldap-exceptions:
- Exceptions
- ==========
- The module defines the following exceptions:
- .. py:exception:: LDAPError
- This is the base class of all execeptions raised by the module :py:mod:`ldap`.
- Unlike the C interface, errors are not returned as result codes, but
- are instead turned into exceptions, raised as soon an the error condition
- is detected.
- The exceptions are accompanied by a dictionary possibly
- containing an string value for the key :py:const:`desc`
- (giving an English description of the error class)
- and/or a string value for the key :py:const:`info`
- (giving a string containing more information that the server may have sent).
- A third possible field of this dictionary is :py:const:`matched` and
- is set to a truncated form of the name provided or alias dereferenced
- for the lowest entry (object or alias) that was matched.
- .. py:exception:: ADMINLIMIT_EXCEEDED
- .. py:exception:: AFFECTS_MULTIPLE_DSAS
- .. py:exception:: ALIAS_DEREF_PROBLEM
- A problem was encountered when dereferencing an alias.
- (Sets the :py:const:`matched` field.)
- .. py:exception:: ALIAS_PROBLEM
- An alias in the directory points to a nonexistent entry.
- (Sets the :py:const:`matched` field.)
- .. py:exception:: ALREADY_EXISTS
- The entry already exists. E.g. the *dn* specified with :py:meth:`add()`
- already exists in the DIT.
- .. py:exception:: AUTH_UNKNOWN
- The authentication method specified to :py:meth:`bind()` is not known.
- .. py:exception:: BUSY
- The DSA is busy.
- .. py:exception:: CLIENT_LOOP
- .. py:exception:: COMPARE_FALSE
- A compare operation returned false.
- (This exception should never be seen because :py:meth:`compare()` returns
- a boolean result.)
- .. py:exception:: COMPARE_TRUE
- A compare operation returned true.
- (This exception should never be seen because :py:meth:`compare()` returns
- a boolean result.)
- .. py:exception:: CONFIDENTIALITY_REQUIRED
- Indicates that the session is not protected by a protocol such
- as Transport Layer Security (TLS), which provides session
- confidentiality.
- .. py:exception:: CONNECT_ERROR
- .. py:exception:: CONSTRAINT_VIOLATION
- An attribute value specified or an operation started violates some
- server-side constraint
- (e.g., a postalAddress has too many lines or a line that is too long
- or a password is expired).
- .. py:exception:: CONTROL_NOT_FOUND
- .. py:exception:: DECODING_ERROR
- An error was encountered decoding a result from the LDAP server.
- .. py:exception:: ENCODING_ERROR
- An error was encountered encoding parameters to send to the LDAP server.
- .. py:exception:: FILTER_ERROR
- An invalid filter was supplied to :py:meth:`search()`
- (e.g. unbalanced parentheses).
- .. py:exception:: INAPPROPRIATE_AUTH
- Inappropriate authentication was specified (e.g. :py:const:`AUTH_SIMPLE`
- was specified and the entry does not have a userPassword attribute).
- .. py:exception:: INAPPROPRIATE_MATCHING
- Filter type not supported for the specified attribute.
- .. py:exception:: INSUFFICIENT_ACCESS
- The user has insufficient access to perform the operation.
- .. py:exception:: INVALID_CREDENTIALS
- Invalid credentials were presented during :py:meth:`bind()` or
- :py:meth:`simple_bind()`.
- (e.g., the wrong password).
- .. py:exception:: INVALID_DN_SYNTAX
- A syntactically invalid DN was specified. (Sets the :py:const:`matched` field.)
- .. py:exception:: INVALID_SYNTAX
- An attribute value specified by the client did not comply to the
- syntax defined in the server-side schema.
- .. py:exception:: IS_LEAF
- The object specified is a leaf of the diretcory tree.
- Sets the :py:const:`matched` field of the exception dictionary value.
- .. py:exception:: LOCAL_ERROR
- Some local error occurred. This is usually due to failed memory allocation.
- .. py:exception:: LOOP_DETECT
- A loop was detected.
- .. py:exception:: MORE_RESULTS_TO_RETURN
- .. py:exception:: NAMING_VIOLATION
- A naming violation occurred. This is raised e.g. if the LDAP server
- has constraints about the tree naming.
- .. py:exception:: NO_OBJECT_CLASS_MODS
- Modifying the objectClass attribute as requested is not allowed
- (e.g. modifying structural object class of existing entry).
- .. py:exception:: NOT_ALLOWED_ON_NONLEAF
- The operation is not allowed on a non-leaf object.
- .. py:exception:: NOT_ALLOWED_ON_RDN
- The operation is not allowed on an RDN.
- .. py:exception:: NOT_SUPPORTED
- .. py:exception:: NO_MEMORY
- .. py:exception:: NO_OBJECT_CLASS_MODS
- Object class modifications are not allowed.
- .. py:exception:: NO_RESULTS_RETURNED
- .. py:exception:: NO_SUCH_ATTRIBUTE
- The attribute type specified does not exist in the entry.
- .. py:exception:: NO_SUCH_OBJECT
- The specified object does not exist in the directory.
- Sets the :py:const:`matched` field of the exception dictionary value.
- .. py:exception:: OBJECT_CLASS_VIOLATION
- An object class violation occurred when the LDAP server checked
- the data sent by the client against the server-side schema
- (e.g. a "must" attribute was missing in the entry data).
- .. py:exception:: OPERATIONS_ERROR
- An operations error occurred.
- .. py:exception:: OTHER
- An unclassified error occurred.
- .. py:exception:: PARAM_ERROR
- An ldap routine was called with a bad parameter.
- .. py:exception:: PARTIAL_RESULTS
- Partial results only returned. This exception is raised if
- a referral is received when using LDAPv2.
- (This exception should never be seen with LDAPv3.)
- .. py:exception:: PROTOCOL_ERROR
- A violation of the LDAP protocol was detected.
- .. py:exception:: RESULTS_TOO_LARGE
- The result does not fit into a UDP packet. This happens only when using
- UDP-based CLDAP (connection-less LDAP) which is not supported anyway.
- .. py:exception:: SASL_BIND_IN_PROGRESS
- .. py:exception:: SERVER_DOWN
- The LDAP library can't contact the LDAP server.
- .. py:exception:: SIZELIMIT_EXCEEDED
- An LDAP size limit was exceeded.
- This could be due to a ``sizelimit`` configuration on the LDAP server.
- .. py:exception:: STRONG_AUTH_NOT_SUPPORTED
- The LDAP server does not support strong authentication.
- .. py:exception:: STRONG_AUTH_REQUIRED
- Strong authentication is required for the operation.
- .. py:exception:: TIMELIMIT_EXCEEDED
- An LDAP time limit was exceeded.
- .. py:exception:: TIMEOUT
- A timelimit was exceeded while waiting for a result from the server.
- .. py:exception:: TYPE_OR_VALUE_EXISTS
- An attribute type or attribute value specified already
- exists in the entry.
- .. py:exception:: UNAVAILABLE
- The DSA is unavailable.
- .. py:exception:: UNAVAILABLE_CRITICAL_EXTENSION
- Indicates that the LDAP server was unable to satisfy a request
- because one or more critical extensions were not available. Either
- the server does not support the control or the control is not appropriate
- for the operation type.
- .. py:exception:: UNDEFINED_TYPE
- An attribute type used is not defined in the server-side schema.
- .. py:exception:: UNWILLING_TO_PERFORM
- The DSA is unwilling to perform the operation.
- .. py:exception:: USER_CANCELLED
- The operation was cancelled via the :py:meth:`abandon()` method.
- The above exceptions are raised when a result code from an underlying API
- call does not indicate success.
- .. _ldap-objects:
- LDAPObject classes
- ==================
- .. py:class:: LDAPObject
- Instances of :py:class:`LDAPObject` are returned by :py:func:`initialize()`
- and :py:func:`open()` (deprecated). The connection is automatically unbound
- and closed when the LDAP object is deleted. Internally :py:class:`LDAPObject`
- is set to :py:class:`SimpleLDAPObject` by default.
- .. py:class:: SimpleLDAPObject(uri [, trace_level=0 [, trace_file=sys.stdout [, trace_stack_limit=5]]])
- Instances of :py:class:`LDAPObject` are returned by :py:func:`initialize()`
- and :py:func:`open()` (deprecated). The connection is automatically unbound
- and closed when the LDAP object is deleted.
- .. py:class:: ReconnectLDAPObject(uri [, trace_level=0 [, trace_file=sys.stdout [, trace_stack_limit=5] [, retry_max=1 [, retry_delay=60.0]]]])
- This class is derived from :py:class:`SimpleLDAPObject` and used for automatic
- reconnects when using the synchronous request methods (see below). This class
- also implements the pickle protocol.
- For automatic reconnects it has additional arguments:
- *retry_max* specifies the number of reconnect attempts before
- re-raising the :py:exc:`ldap.SERVER_DOWN` exception.
- *retry_delay* specifies the time in seconds between reconnect attempts.
- Arguments for LDAPv3 controls
- -----------------------------
- The :py:mod:`ldap.controls` module can be used for constructing and
- decoding LDAPv3 controls. These arguments are available in the methods
- with names ending in :py:const:`_ext` or :py:const:`_ext_s`:
- *serverctrls*
- is a list of :py:class:`ldap.controls.LDAPControl` instances sent to the server along
- with the LDAP request (see module :py:mod:`ldap.controls`). These are
- controls which alter the behaviour of the server when processing the
- request if the control is supported by the server. The effect of controls
- might differ depending on the type of LDAP request or controls might not
- be applicable with certain LDAP requests at all.
- *clientctrls*
- is a list of :py:class:`ldap.controls.LDAPControl` instances passed to the
- client API and alter the behaviour of the client when processing the
- request.
- Sending LDAP requests
- ---------------------
- Most methods on LDAP objects initiate an asynchronous request to the
- LDAP server and return a message id that can be used later to retrieve
- the result with :py:meth:`result()`.
- Methods with names ending in :py:const:`_s` are the synchronous form
- and wait for and return with the server's result, or with
- :py:const:`None` if no data is expected.
- :class:`LDAPObject` instances have the following methods:
- .. py:method:: LDAPObject.abandon(msgid) -> None
- .. py:method:: LDAPObject.abandon_ext(msgid [, serverctrls=None [, clientctrls=None]]) -> None
- Abandons an LDAP operation in progress without waiting for a LDAP response.
- The *msgid* argument should be the message ID of an outstanding LDAP
- operation as returned by the asynchronous methods :py:meth:`search()`, :py:meth:`modify()`, etc.
- The caller can expect that the result of an abandoned operation will not be
- returned from a future call to :py:meth:`result()`.
- *serverctrls* and *clientctrls* like described above.
- .. py:method:: LDAPObject.add(dn, modlist) -> int
- .. py:method:: LDAPObject.add_s(dn, modlist) -> None
- .. py:method:: LDAPObject.add_ext(dn, modlist [, serverctrls=None [, clientctrls=None]]) -> int
- .. py:method:: LDAPObject.add_ext_s(dn, modlist [, serverctrls=None [, clientctrls=None]]) -> None
- Performs an LDAP add operation. The *dn* argument is the distinguished
- name (DN) of the entry to add, and *modlist* is a list of attributes to be
- added. The modlist is similar the one passed to :py:meth:`modify()`, except that the
- operation integer is omitted from the tuples in modlist. You might want to
- look into sub-module \refmodule{ldap.modlist} for generating the modlist.
- The asynchronous methods :py:meth:`add()` and :py:meth:`add_ext()`
- return the message ID of the initiated request.
- *serverctrls* and *clientctrls* like described above.
- .. py:method:: LDAPObject.bind(who, cred, method) -> int
- .. py:method:: LDAPObject.bind_s(who, cred, method) -> None
- .. py:method:: LDAPObject.simple_bind([who='' [, cred='']]) -> int
- .. py:method:: LDAPObject.simple_bind_s([who='' [, cred='']]) -> None
- 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, :py:meth:`bind()`,
- takes a third parameter, *method* which can currently solely
- be :py:const:`AUTH_SIMPLE`.
- .. py:method:: LDAPObject.sasl_interactive_bind_s(who, auth) -> None
- This call is used to bind to the directory with a SASL bind request.
- .. py:method:: LDAPObject.cancel( cancelid, [, serverctrls=None [, clientctrls=None]]) -> None
- Send cancels extended operation for an LDAP operation specified by *cancelid*.
- The *cancelid* 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 :py:meth:`result()`.
- In opposite to :py:meth:`abandon()` this extended operation gets an result from
- the server and thus should be preferred if the server supports it.
- *serverctrls* and *clientctrls* like described above.
- :rfc:`3909` - Lightweight Directory Access Protocol (LDAP): Cancel Operation
- .. py:method:: LDAPObject.compare(dn, attr, value) -> int
- .. py:method:: LDAPObject.compare_s(dn, attr, value) -> tuple
- .. py:method:: LDAPObject.compare_ext(dn, attr, value [, serverctrls=None [, clientctrls=None]]) -> int
- .. py:method:: LDAPObject.compare_ext_s(dn, attr, value [, serverctrls=None [, clientctrls=None]]) -> tuple
- Perform an LDAP comparison between the attribute named *attr* of
- entry *dn*, and the value *value*. The synchronous forms
- returns :py:const:`0` for false, or :py:const:`1` for true.
- The asynchronous forms returns the message ID of the initiated request,
- and the result of the asynchronous compare can be obtained using
- :py:meth:`result()`.
- Note that the asynchronous technique yields the answer
- by raising the exception objects :py:exc:`ldap.COMPARE_TRUE` or
- :py:exc:`ldap.COMPARE_FALSE`.
- *serverctrls* and *clientctrls* like described above.
- .. note::
- A design fault in the LDAP API prevents *value*
- from containing *NULL* characters.
- .. py:method:: LDAPObject.delete(dn) -> int
- .. py:method:: LDAPObject.delete_s(dn) -> None
- .. py:method:: LDAPObject.delete_ext(dn [, serverctrls=None [, clientctrls=None]]) -> int
- .. py:method:: LDAPObject.delete_ext_s(dn [, serverctrls=None [, clientctrls=None]]) -> None
- 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 :py:meth:`result()`.
- *serverctrls* and *clientctrls* like described above.
- .. py:method:: extop(extreq[,serverctrls=None[,clientctrls=None]]]) -> int
- .. py:method:: extop_s(extreq[,serverctrls=None[,clientctrls=None[,extop_resp_class=None]]]]) -> (respoid,respvalue)
- Performs an LDAP extended operation. The asynchronous
- form returns the message id of the initiated request, and the
- result can be obtained from a subsequent call to :py:meth:`extop_result()`.
- The *extreq* is an instance of class :py:class:`ldap.extop.ExtendedRequest`
- containing the parameters for the extended operation request.
-
- If argument *extop_resp_class* is set to a sub-class of
- :py:class:`ldap.extop.ExtendedResponse` this class is used to return an
- object of this class instead of a raw BER value in respvalue.
- .. py:method:: extop_result(self,msgid=ldap.RES_ANY,all=1,timeout=None) -> (respoid,respvalue)
- Wrapper method around :py:meth:`result4()` just for retrieving
- the result of an extended operation sent before.
- .. py:method:: LDAPObject.modify(dn, modlist) -> int
- .. py:method:: LDAPObject.modify_s(dn, modlist) -> None
- .. py:method:: LDAPObject.modify_ext(dn, modlist [, serverctrls=None [, clientctrls=None]]) -> int
- .. py:method:: LDAPObject.modify_ext_s(dn, modlist [, serverctrls=None [, clientctrls=None]]) -> None
- 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 :py:const:`MOD_ADD`,
- :py:const:`MOD_DELETE`, or :py:const:`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 :py:const:`None` indicating that all attributes are to be deleted.
- *serverctrls* and *clientctrls* like described above.
- The asynchronous methods :py:meth:`modify()` and :py:meth:`modify_ext()`
- return the message ID of the initiated request.
- You might want to look into sub-module :py:mod:`ldap.modlist` for
- generating *modlist*.
- .. py:method:: LDAPObject.modrdn(dn, newrdn [, delold=1]) -> int
- .. py:method:: LDAPObject.modrdn_s(dn, newrdn [, delold=1]) -> None
- 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.
- The asynchronous version returns the initiated message id.
- This operation is emulated by :py:meth:`rename()` and :py:meth:`rename_s()` methods
- since the modrdn2* routines in the C library are deprecated.
- .. py:method:: LDAPObject.passwd(user, oldpw, newpw [, serverctrls=None [, clientctrls=None]]) -> int
- .. py:method:: LDAPObject.passwd_s(user, oldpw, newpw [, serverctrls=None [, clientctrls=None]]) -> None
- Perform a ``LDAP Password Modify Extended Operation`` operation
- on the entry specified by *user*.
- The old password in *oldpw* is replaced with the new
- password in *newpw* by a LDAP server supporting this operation.
- If *oldpw* is not :py:const:`None` it has to match the old password
- of the specified *user* which is sometimes used when a user changes
- his own password.
- *serverctrls* and *clientctrls* like described above.
- The asynchronous version returns the initiated message id.
- .. seealso::
- :rfc:`3062` - LDAP Password Modify Extended Operation
- .. py:method:: LDAPObject.rename(dn, newrdn [, newsuperior=None [, delold=1 [, serverctrls=None [, clientctrls=None]]]]) -> int
- .. py:method:: LDAPObject.rename_s(dn, newrdn [, newsuperior=None [, delold=1 [, serverctrls=None [, clientctrls=None]]]]) -> None
- 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.
- *serverctrls* and *clientctrls* like described above.
- .. py:method:: LDAPObject.result([msgid=RES_ANY [, all=1 [, timeout=None]]]) -> 2-tuple
- This method is used to wait for and return the result of an operation
- previously initiated by one of the LDAP *asynchronous* operations
- (eg :py:meth:`search()`, :py:meth:`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 :py:meth:`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 :py:const:`RES_ANY`
- and the method :py:meth:`result2()` should be used instead.
- The *all* parameter only has meaning for :py:meth:`search()` responses
- and is used to select whether a single entry of the search
- response should be returned, or to wait for all the results
- of the search before returning.
- A search response is made up of zero or more search entries
- followed by a search result. If *all* is 0, search entries will
- be returned one at a time as they come in, via separate calls
- to :py:meth:`result()`. If all is 1, the search response will be returned
- in its entirety, i.e. after all entries and the final search
- result have been received.
- For *all* set to 0, result tuples
- trickle in (with the same message id), and with the result types
- :py:const:`RES_SEARCH_ENTRY` and :py:const:`RES_SEARCH_REFERENCE`,
- until the final result which has a result type of :py:const:`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.
- 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 :py:const:`0` effects a poll.
- If a timeout does occur, a :py:exc:`ldap.TIMEOUT` exception is raised,
- unless polling, in which case ``(None, None)`` is returned.
- The :py:meth:`result()` method returns a tuple of the form
- ``(result-type, result-data)``.
- The first element, ``result-type`` is a string, being one of
- these module constants:
- :py:const:`RES_BIND`, :py:const:`RES_SEARCH_ENTRY`,
- :py:const:`RES_SEARCH_REFERENCE`, :py:const:`RES_SEARCH_RESULT`,
- :py:const:`RES_MODIFY`, :py:const:`RES_ADD`, :py:const:`RES_DELETE`,
- :py:const:`RES_MODRDN`, or :py:const:`RES_COMPARE`.
- If *all* is :py:const:`0`, one response at a time is returned on
- each call to :py:meth:`result()`, with termination indicated by
- ``result-data`` being an empty list.
- See :py:meth:`search()` for a description of the search result's
- ``result-data``, otherwise the ``result-data`` is normally meaningless.
- .. py:method:: LDAPObject.result2([msgid=RES_ANY [, all=1 [, timeout=None]]]) -> 3-tuple
- This method behaves almost exactly like :py:meth:`result()`. But
- it returns a 3-tuple also containing the message id of the
- outstanding LDAP operation a particular result message belongs
- to. This is especially handy if one needs to dispatch results
- obtained with ``msgid=``:py:const:`RES_ANY` to several consumer
- threads which invoked a particular LDAP operation.
- .. py:method:: LDAPObject.result3([msgid=RES_ANY [, all=1 [, timeout=None]]]) -> 4-tuple
- This method behaves almost exactly like :py:meth:`result2()`. But it
- returns an extra item in the tuple, the decoded server controls.
- .. py:method:: LDAPObject.result4([msgid=RES_ANY [, all=1 [, timeout=None [, add_ctrls=0 [, add_intermediates=0 [, add_extop=0 [, resp_ctrl_classes=None]]]]]]]) -> 6-tuple
- This method behaves almost exactly like :py:meth:`result3()`. But it
- returns an extra items in the tuple, the decoded results of an extended response.
- The additional arguments are:
- *add_ctrls* (integer flag) specifies whether response controls are returned.
-
- add_intermediates (integer flag) specifies whether response controls of
- intermediate search results are returned.
- *add_extop* (integer flag) specifies whether the response of an
- extended operation is returned. If using extended operations you should
- consider using the method :py:meth:`extop_result()` or
- :py:meth:`extop_s()` instead.
- *resp_ctrl_classes* is a dictionary mapping the OID of a response controls to a
- :py:class:`ldap.controls.ResponseControl` class of response controls known by the
- application. So the response control value will be automatically decoded.
- If :py:const:`None` the global dictionary :py:data:`ldap.controls.KNOWN_RESPONSE_CONTROLS`
- is used instead.
- .. py:method:: LDAPObject.search(base, scope [,filterstr='(objectClass=*)' [, attrlist=None [, attrsonly=0]]]) ->int
- .. py:method:: LDAPObject.search_s(base, scope [,filterstr='(objectClass=*)' [, attrlist=None [, attrsonly=0]]]) ->list|None
- .. py:method:: LDAPObject.search_st(base, scope [,filterstr='(objectClass=*)' [, attrlist=None [, attrsonly=0 [, timeout=-1]]]]) -> list|None
- .. py:method:: LDAPObject.search_ext(base, scope [,filterstr='(objectClass=*)' [, attrlist=None [, attrsonly=0 [, serverctrls=None [, clientctrls=None [, timeout=-1 [, sizelimit=0]]]]]]]) -> int
- .. py:method:: LDAPObject.search_ext_s(base, scope [,filterstr='(objectClass=*)' [, attrlist=None [, attrsonly=0 [, serverctrls=None [, clientctrls=None [, timeout=-1 [, sizelimit=0]]]]]]]) -> list|None
- Perform an LDAP search operation, with *base* as the DN of the entry
- at which to start the search, *scope* being one of
- :py:const:`SCOPE_BASE` (to search the object itself),
- :py:const:`SCOPE_ONELEVEL` (to search the object's immediate children), or
- :py:const:`SCOPE_SUBTREE` (to search the object and all its descendants).
- The *filterstr* argument is a string representation of the filter to apply in
- the search.
- .. seealso::
- :rfc:`4515` - Lightweight Directory Access Protocol (LDAP): String Representation of Search Filters.
- 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 automatically extracted using the underlying libldap
- function :cfunc:`ldap_get_dn()`, 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 :py:const:`None`, all the attributes of each entry are returned.
- *serverctrls* and *clientctrls* like described above.
- The synchronous form with timeout, :py:meth:`search_st()` or :py:meth:`search_ext_s()`,
- will block for at most *timeout* seconds (or indefinitely if *timeout*
- is negative). A :py:exc:`ldap.TIMEOUT` exception is raised if no result is received
- within the specified time.
- The amount of search results retrieved can be limited with the
- *sizelimit* parameter when using :py:meth:`search_ext()`
- or :py:meth:`search_ext_s()` (client-side search limit). If non-zero
- not more than *sizelimit* results are returned by the server.
- .. py:method:: LDAPObject.start_tls_s() -> None
- Negotiate TLS with server. The ``version`` attribute must have been
- set to :py:const:`VERSION3` (which it is by default) before calling this method.
- If TLS could not be started an exception will be raised.
- .. seealso::
- :rfc:`2830` - Lightweight Directory Access Protocol (v3): Extension for Transport Layer Security
- .. py:method:: LDAPObject.unbind() -> int
- .. py:method:: LDAPObject.unbind_s() -> None
- .. py:method:: LDAPObject.unbind_ext([, serverctrls=None [, clientctrls=None]]) -> int
- .. py:method:: LDAPObject.unbind_ext_s([, serverctrls=None [, clientctrls=None]]) -> None
- 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.
- *serverctrls* and *clientctrls* like described above.
- These methods are all synchronous in nature.
- .. py:method:: LDAPObject.whoami_s() -> string
- This synchronous method implements the LDAP "Who Am I?"
- extended operation.
- It is useful for finding out to find out which identity
- is assumed by the LDAP server after a SASL bind.
- .. seealso::
- :rfc:`4532` - Lightweight Directory Access Protocol (LDAP) "Who am I?" Operation
- Connection-specific LDAP options
- --------------------------------
- .. py:method:: LDAPObject.get_option(option) -> int|string
- This method returns the value of the LDAPObject option
- specified by *option*.
- .. py:method:: LDAPObject.set_option(option, invalue) -> None
- This method sets the value of the LDAPObject option
- specified by *option* to *invalue*.
- Object attributes
- -----------------
- If the underlying library provides enough information,
- each LDAP object will also have the following attributes.
- These attributes are mutable unless described as read-only.
- .. py:attribute:: LDAPObject.deref -> int
- Controls whether aliases are automatically dereferenced.
- This must be one of :py:const:`DEREF_NEVER`, :py:const:`DEREF_SEARCHING`,
- :py:const:`DEREF_FINDING` or :py:const:`DEREF_ALWAYS`.
- This option is mapped to option constant :py:const:`OPT_DEREF`
- and used in the underlying OpenLDAP client lib.
- .. py:attribute:: LDAPObject.network_timeout -> int
- Limit on waiting for a network response, in seconds.
- Defaults to :py:const:`NO_LIMIT`.
- This option is mapped to option constant :py:const:`OPT_NETWORK_TIMEOUT`
- and used in the underlying OpenLDAP client lib.
- .. py:attribute:: LDAPObject.protocol_version -> int
- Version of LDAP in use (either :py:const:`VERSION2` for LDAPv2
- or :py:const:`VERSION3` for LDAPv3).
- This option is mapped to option constant :py:const:`OPT_PROTOCOL_VERSION`
- and used in the underlying OpenLDAP client lib.
- .. note::
- It is highly recommended to set the protocol version after establishing
- a LDAP connection with :py:func:`ldap.initialize()` and before submitting
- the first request.
- .. py:attribute:: LDAPObject.sizelimit -> int
- Limit on size of message to receive from server.
- Defaults to :py:const:`NO_LIMIT`.
- This option is mapped to option constant :py:const:`OPT_SIZELIMIT`
- and used in the underlying OpenLDAP client lib. Its use is deprecated
- in favour of *sizelimit* parameter when using :py:meth:`search_ext()`.
- .. py:attribute:: LDAPObject.timelimit -> int
- Limit on waiting for any response, in seconds.
- Defaults to :py:const:`NO_LIMIT`.
- This option is mapped to option constant :py:const:`OPT_TIMELIMIT`
- and used in the underlying OpenLDAP client lib. Its use is deprecated
- in favour of using :py:attr:`timeout`.
- .. py:attribute:: LDAPObject.timeout -> int
- Limit on waiting for any response, in seconds.
- Defaults to :py:const:`NO_LIMIT`.
- This option is used in the wrapper module.
- .. _ldap-example:
- Example
- =======
- The following example demonstrates how to open a connection to an
- LDAP server using the :py:mod:`ldap` module and invoke a synchronous
- subtree search.
- >>> import ldap
- >>> l = ldap.initialize('ldap://localhost:1390')
- >>> l.search_s('ou=Testing,dc=stroeder,dc=de',ldap.SCOPE_SUBTREE,'(cn=fred*)',['cn','mail'])
- [('cn=Fred Feuerstein,ou=Testing,dc=stroeder,dc=de', {'cn': ['Fred Feuerstein']})]
- >>> r = l.search_s('ou=Testing,dc=stroeder,dc=de',ldap.SCOPE_SUBTREE,'(objectClass=*)',['cn','mail'])
- >>> for dn,entry in r:
- >>> print 'Processing',repr(dn)
- >>> handle_ldap_entry(entry)
|