From bb6452c7981bfea9865c9bf37a98585e1cf75268 Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Thu, 25 Oct 2018 13:40:35 +0200 Subject: [PATCH 1/3] Make initialize() pass extra keyword arguments to LDAPObject Fixes: https://github.com/python-ldap/python-ldap/issues/249 --- Doc/reference/ldap.rst | 2 ++ Lib/ldap/functions.py | 11 +++++++++-- 2 files changed, 11 insertions(+), 2 deletions(-) diff --git a/Doc/reference/ldap.rst b/Doc/reference/ldap.rst index 0ce2e418..59151c6f 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 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): From edfc33514471888b03feb61b2c414f40bce826e4 Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Thu, 25 Oct 2018 16:22:50 +0200 Subject: [PATCH 2/3] Synchronize docs and code for initialize() and LDAPObject Use signatures and doc from the code (and docstrings) using Sphinx autodoc. --- Doc/reference/ldap.rst | 29 ++++++----------------------- Lib/ldap/ldapobject.py | 27 +++++++++++++++++---------- 2 files changed, 23 insertions(+), 33 deletions(-) diff --git a/Doc/reference/ldap.rst b/Doc/reference/ldap.rst index 59151c6f..b13aa6f0 100644 --- a/Doc/reference/ldap.rst +++ b/Doc/reference/ldap.rst @@ -581,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. + Internally :py:class:`LDAPObject` is set to + :py:class:`~ldap.ldapobject.SimpleLDAPObject` by default. -.. py:class:: SimpleLDAPObject(uri [, trace_level=0 [, trace_file=sys.stdout [, trace_stack_limit=5]]]) +.. autoclass:: ldap.ldapobject.SimpleLDAPObject - 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: - - *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. +.. autoclass:: ldap.ldapobject.ReconnectLDAPObject .. _ldap-controls: diff --git a/Lib/ldap/ldapobject.py b/Lib/ldap/ldapobject.py index 8fa71c3e..462c3061 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__ = { From 313e79ee48d402808b9a422539dd76a35c182754 Mon Sep 17 00:00:00 2001 From: Petr Viktorin Date: Mon, 7 Jan 2019 17:10:37 +0100 Subject: [PATCH 3/3] Match surrounding indentation in docstrings --- Lib/ldap/ldapobject.py | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/Lib/ldap/ldapobject.py b/Lib/ldap/ldapobject.py index 462c3061..e4e6841a 100644 --- a/Lib/ldap/ldapobject.py +++ b/Lib/ldap/ldapobject.py @@ -76,9 +76,9 @@ class NO_UNIQUE_ENTRY(ldap.NO_SUCH_OBJECT): class SimpleLDAPObject: """ - This basic class wraps all methods of the underlying C API object. + This basic class wraps all methods of the underlying C API object. - The arguments are same as for the :func:`~ldap.initialize()` function. + The arguments are same as for the :func:`~ldap.initialize()` function. """ CLASSATTR_OPTION_MAPPING = { @@ -1059,20 +1059,20 @@ def get_naming_contexts(self): class ReconnectLDAPObject(SimpleLDAPObject): """ - :py:class:`SimpleLDAPObject` subclass whose synchronous request methods - automatically reconnect and re-try in case of server failure - (:exc:`ldap.SERVER_DOWN`). + :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: + 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_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. + * retry_delay: specifies the time in seconds between reconnect attempts. - This class also implements the pickle protocol. + This class also implements the pickle protocol. """ __transient_attrs__ = {