Make initialize() pass extra keyword arguments to LDAPObject

encukou · web-flow · commit 576d5bf84aa7 · 2019-01-07T17:38:14.000+01:00
Make initialize() pass extra keyword arguments to LDAPObject Fixes: python-ldap#249 For docs, use signatures and doc from the code (and docstrings) using Sphinx autodoc. python-ldap#250
diff --git a/Doc/reference/ldap.rst b/Doc/reference/ldap.rst
@@ -63,6 +63,8 @@ This module defines the following functions:
    :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.
 
+   Additional keyword arguments are passed to :class:`LDAPObject`.
+
    .. seealso::
 
       :rfc:`4516` - Lightweight Directory Access Protocol (LDAP): Uniform Resource Locator
@@ -579,33 +581,16 @@ 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
+   Instances of :py:class:`LDAPObject` are returned by :py:func:`initialize()`.
+   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]]])
-
-   This basic class wraps all methods of the underlying C API object.
-
-   The arguments are same like for function :py:func:`initialize()`.
-
-.. 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.
-
-   The first arguments are same like for function :py:func:`initialize()`.
-
-   For automatic reconnects it has additional arguments:
+   Internally :py:class:`LDAPObject` is set to
+   :py:class:`~ldap.ldapobject.SimpleLDAPObject` by default.
 
-   *retry_max* specifies the number of reconnect attempts before
-   re-raising the :py:exc:`ldap.SERVER_DOWN` exception.
+.. autoclass:: ldap.ldapobject.SimpleLDAPObject
 
-   *retry_delay* specifies the time in seconds between reconnect attempts.
+.. autoclass:: ldap.ldapobject.ReconnectLDAPObject
 
 
 .. _ldap-controls:
diff --git a/Lib/ldap/functions.py b/Lib/ldap/functions.py
@@ -65,7 +65,10 @@ def _ldap_function_call(lock,func,*args,**kwargs):
   return result
 
 
-def initialize(uri,trace_level=0,trace_file=sys.stdout,trace_stack_limit=None, bytes_mode=None):
+def initialize(
+    uri, trace_level=0, trace_file=sys.stdout, trace_stack_limit=None,
+    bytes_mode=None, **kwargs
+):
   """
   Return LDAPObject instance by opening LDAP connection to
   LDAP host specified by LDAP URL
@@ -81,8 +84,12 @@ def initialize(uri,trace_level=0,trace_file=sys.stdout,trace_stack_limit=None, b
         Default is to use stdout.
   bytes_mode
         Whether to enable :ref:`bytes_mode` for backwards compatibility under Py2.
+
+  Additional keyword arguments (such as ``bytes_strictness``) are
+  passed to ``LDAPObject``.
   """
-  return LDAPObject(uri,trace_level,trace_file,trace_stack_limit,bytes_mode)
+  return LDAPObject(
+      uri, trace_level, trace_file, trace_stack_limit, bytes_mode, **kwargs)
 
 
 def get_option(option):
diff --git a/Lib/ldap/ldapobject.py b/Lib/ldap/ldapobject.py
@@ -76,7 +76,9 @@ class NO_UNIQUE_ENTRY(ldap.NO_SUCH_OBJECT):
 
 class SimpleLDAPObject:
   """
-  Drop-in wrapper class around _ldap.LDAPObject
+  This basic class wraps all methods of the underlying C API object.
+
+  The arguments are same as for the :func:`~ldap.initialize()` function.
   """
 
   CLASSATTR_OPTION_MAPPING = {
@@ -1057,15 +1059,20 @@ def get_naming_contexts(self):
 
 class ReconnectLDAPObject(SimpleLDAPObject):
   """
-  In case of server failure (ldap.SERVER_DOWN) the implementations
-  of all synchronous operation methods (search_s() etc.) are doing
-  an automatic reconnect and rebind and will retry the very same
-  operation.
-
-  This is very handy for broken LDAP server implementations
-  (e.g. in Lotus Domino) which drop connections very often making
-  it impossible to have a long-lasting control flow in the
-  application.
+  :py:class:`SimpleLDAPObject` subclass whose synchronous request methods
+  automatically reconnect and re-try in case of server failure
+  (:exc:`ldap.SERVER_DOWN`).
+
+  The first arguments are same as for the :py:func:`~ldap.initialize()`
+  function.
+  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.
+
+  This class also implements the pickle protocol.
   """
 
   __transient_attrs__ = {
