diff --git a/Doc/reference/ldap.rst b/Doc/reference/ldap.rst index 0ce2e418..b13aa6f0 100644 --- 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 index ae83d08a..529c4c8f 100644 --- 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 index 8fa71c3e..e4e6841a 100644 --- 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__ = {