more on SASL binds and extended controls

stroeder · stroeder · commit c12868458d10 · 2017-09-05T07:23:36.000Z
diff --git 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.
 
