diff --git a/Doc/ldap.rst b/Doc/ldap.rst index 37afc63..10abf2a 100644 --- a/Doc/ldap.rst +++ b/Doc/ldap.rst @@ -1,4 +1,4 @@ -.. % $Id: ldap.rst,v 1.40 2017/09/04 15:02:29 stroeder Exp $ +.. % $Id: ldap.rst,v 1.41 2017/09/05 07:23:36 stroeder Exp $ ******************************************** :py:mod:`ldap` LDAP library interface module @@ -593,6 +593,8 @@ LDAPObject classes *retry_delay* specifies the time in seconds between reconnect attempts. +.. _ldap-controls: + Arguments for LDAPv3 controls ----------------------------- @@ -638,7 +640,7 @@ and wait for and return with the server's result, or with 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. + *serverctrls* and *clientctrls* like described in section :ref:`ldap-controls`. .. py:method:: LDAPObject.add(dn, modlist) -> int @@ -658,46 +660,13 @@ and wait for and return with the server's result, or with 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. + *serverctrls* and *clientctrls* like described in section :ref:`ldap-controls`. + .. py:method:: LDAPObject.bind(who, cred, method) -> int .. py:method:: LDAPObject.bind_s(who, cred, method) -> None -.. py:method:: LDAPObject.simple_bind([who='' [, cred='' [, serverctrls=None [, clientctrls=None]]]]) -> int - -.. py:method:: LDAPObject.simple_bind_s([who='' [, cred='' [, serverctrls=None [, clientctrls=None]]]]) -> 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[, serverctrls=None [, clientctrls=None [, sasl_flags=ldap.SASL_QUIET]]]) -> None - - This call is used to bind to the directory with a SASL bind request. - - -.. py:method:: LDAPObject.sasl_non_interactive_bind_s(who, auth[, serverctrls=None [, clientctrls=None [, sasl_flags=ldap.SASL_QUIET [, authz_id='']]]]) -> None - - This call is used to bind to the directory with a SASL bind request. - - -.. py:method:: LDAPObject.sasl_external_bind_s([serverctrls=None [, clientctrls=None [, sasl_flags=ldap.SASL_QUIET [, authz_id='']]]]) -> None - - This call is used to bind to the directory with a SASL bind request with mechanism EXTERNAL. - - -.. py:method:: LDAPObject.sasl_gssapi_bind_s([serverctrls=None [, clientctrls=None [, sasl_flags=ldap.SASL_QUIET [, authz_id='']]]]) -> None - - This call is used to bind to the directory with a SASL bind request with mechanism GSSAPI. - - .. py:method:: LDAPObject.cancel( cancelid, [, serverctrls=None [, clientctrls=None]]) -> None Send cancels extended operation for an LDAP operation specified by *cancelid*. @@ -708,7 +677,7 @@ and wait for and return with the server's result, or with 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. + *serverctrls* and *clientctrls* like described in section :ref:`ldap-controls`. :rfc:`3909` - Lightweight Directory Access Protocol (LDAP): Cancel Operation @@ -732,7 +701,7 @@ and wait for and return with the server's result, or with by raising the exception objects :py:exc:`ldap.COMPARE_TRUE` or :py:exc:`ldap.COMPARE_FALSE`. - *serverctrls* and *clientctrls* like described above. + *serverctrls* and *clientctrls* like described in section :ref:`ldap-controls`. .. note:: @@ -752,7 +721,7 @@ and wait for and return with the server's result, or with 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. + *serverctrls* and *clientctrls* like described in section :ref:`ldap-controls`. .. py:method:: LDAPObject.extop(extreq[,serverctrls=None[,clientctrls=None]]]) -> int @@ -766,6 +735,8 @@ and wait for and return with the server's result, or with The *extreq* is an instance of class :py:class:`ldap.extop.ExtendedRequest` containing the parameters for the extended operation request. + *serverctrls* and *clientctrls* like described in section :ref:`ldap-controls`. + 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. @@ -797,7 +768,7 @@ and wait for and return with the server's result, or with 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. + *serverctrls* and *clientctrls* like described in section :ref:`ldap-controls`. The asynchronous methods :py:meth:`modify()` and :py:meth:`modify_ext()` return the message ID of the initiated request. @@ -835,7 +806,7 @@ and wait for and return with the server's result, or with of the specified *user* which is sometimes used when a user changes his own password. - *serverctrls* and *clientctrls* like described above. + *serverctrls* and *clientctrls* like described in section :ref:`ldap-controls`. The asynchronous version returns the initiated message id. @@ -858,7 +829,8 @@ and wait for and return with the server's result, or with 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. + *serverctrls* and *clientctrls* like described in section :ref:`ldap-controls`. + .. py:method:: LDAPObject.result([msgid=RES_ANY [, all=1 [, timeout=None]]]) -> 2-tuple @@ -960,6 +932,54 @@ and wait for and return with the server's result, or with If :py:const:`None` the global dictionary :py:data:`ldap.controls.KNOWN_RESPONSE_CONTROLS` is used instead. +.. py:method:: LDAPObject.sasl_interactive_bind_s(who, auth[, serverctrls=None [, clientctrls=None [, sasl_flags=ldap.SASL_QUIET]]]) -> None + + This call is used to bind to the directory with a SASL bind request. + + *serverctrls* and *clientctrls* like described in section :ref:`ldap-controls`. + + +.. py:method:: LDAPObject.sasl_non_interactive_bind_s(sasl_mech[, serverctrls=None [, clientctrls=None [, sasl_flags=ldap.SASL_QUIET [, authz_id='']]]]) -> None + + This call is used to bind to the directory with a SASL bind request with + non-interactive SASL mechanism defined with argument *sasl_mech* and + internally calls :py:meth:`sasl_interactive_bind_s()`. + + *serverctrls* and *clientctrls* like described in section :ref:`ldap-controls`. + + +.. py:method:: LDAPObject.sasl_external_bind_s([serverctrls=None [, clientctrls=None [, sasl_flags=ldap.SASL_QUIET [, authz_id='']]]]) -> None + + This call is used to bind to the directory with a SASL bind request with + mechanism EXTERNAL and internally calls :py:meth:`sasl_non_interactive_bind_s()`. + + *serverctrls* and *clientctrls* like described in section :ref:`ldap-controls`. + + +.. py:method:: LDAPObject.sasl_gssapi_bind_s([serverctrls=None [, clientctrls=None [, sasl_flags=ldap.SASL_QUIET [, authz_id='']]]]) -> None + + This call is used to bind to the directory with a SASL bind request with + mechanism GSSAPI and internally calls :py:meth:`sasl_non_interactive_bind_s()`. + + *serverctrls* and *clientctrls* like described in section :ref:`ldap-controls`. + + +.. py:method:: LDAPObject.simple_bind([who='' [, cred='' [, serverctrls=None [, clientctrls=None]]]]) -> int + +.. py:method:: LDAPObject.simple_bind_s([who='' [, cred='' [, serverctrls=None [, clientctrls=None]]]]) -> 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`. + + *serverctrls* and *clientctrls* like described in section :ref:`ldap-controls`. + + .. 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 @@ -1000,7 +1020,7 @@ and wait for and return with the server's result, or with 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. + *serverctrls* and *clientctrls* like described in section :ref:`ldap-controls`. 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* @@ -1038,7 +1058,7 @@ and wait for and return with the server's result, or with 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. + *serverctrls* and *clientctrls* like described in section :ref:`ldap-controls`. These methods are all synchronous in nature.