Merge pull request #1 from python-ldap/master

peppelinux · web-flow · commit 54c24f2b99f5 · 2019-02-15T12:49:10.000+01:00
merge
diff --git a/Doc/bytes_mode.rst b/Doc/bytes_mode.rst
@@ -93,12 +93,11 @@ to be given as well.
 Porting recommendations
 -----------------------
 
-Since end of life of Python 2 is coming in a few years,
-projects are strongly urged to make their code compatible with Python 3.
-General instructions for this are provided `in Python documentation`_ and in
-the `Conservative porting guide`_.
+Since end of life of Python 2 is coming in a few years, projects are strongly
+urged to make their code compatible with Python 3. General instructions for
+this are provided :ref:`in Python documentation <pyporting-howto>` and in the
+`Conservative porting guide`_.
 
-.. _in Python documentation: https://docs.python.org/3/howto/pyporting.html
 .. _Conservative porting guide: https://portingguide.readthedocs.io/en/latest/
 
 
diff --git a/Doc/conf.py b/Doc/conf.py
@@ -31,7 +31,10 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc']
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.intersphinx',
+]
 
 try:
     import sphinxcontrib.spelling
@@ -148,3 +151,5 @@
 
 # If false, no module index is generated.
 latex_use_modindex = True
+
+intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
diff --git a/Doc/installing.rst b/Doc/installing.rst
@@ -99,10 +99,8 @@ From a source repository::
 If you have more than one Python interpreter installed locally, you should
 use the same one you plan to use python-ldap with.
 
-Further instructions can be found in `Setuptools documentation`_.
-
-
-.. _Setuptools documentation: https://docs.python.org/3/distributing/index.html
+Further instructions can be found in :ref:`Setuptools documentation
+<distributing-index>`.
 
 
 .. _build prerequisites:
@@ -169,11 +167,10 @@ Packages for building and testing::
 setup.cfg
 =========
 
-The file setup.cfg allows to set some build and installation
-parameters for reflecting the local installation of required
-software packages. Only section ``[_ldap]`` is described here.
-More information about other sections can be found in
-`Setuptools documentation`_.
+The file setup.cfg allows to set some build and installation parameters for
+reflecting the local installation of required software packages. Only section
+``[_ldap]`` is described here. More information about other sections can be
+found in :ref:`Setuptools documentation <distributing-index>`.
 
 .. data:: library_dirs
 
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/Doc/requirements.txt b/Doc/requirements.txt
@@ -0,0 +1,2 @@
+pyasn1
+pyasn1_modules
diff --git a/Doc/sample_workflow.rst b/Doc/sample_workflow.rst
@@ -26,15 +26,14 @@ Clone the repository::
     $ git clone https://github.com/python-ldap/python-ldap
     $ cd python-ldap
 
-Create a `virtual environment`_ to ensure you in-development python-ldap won't
-affect the rest of your system::
+Create a :mod:`virtual environment <venv>` to ensure you in-development
+python-ldap won't affect the rest of your system::
 
     $ python3 -m venv __venv__
 
 (For Python 2, install `virtualenv`_ and use it instead of ``python3 -m venv``.)
 
 .. _git: https://git-scm.com/
-.. _virtual environment: https://docs.python.org/3/library/venv.html
 .. _virtualenv: https://virtualenv.pypa.io/en/stable/
 
 Activate the virtual environment::
diff --git a/Lib/ldap/controls/sss.py b/Lib/ldap/controls/sss.py
@@ -12,6 +12,8 @@
 ]
 
 
+import sys
+
 import ldap
 from ldap.ldapobject import LDAPObject
 from ldap.controls import (RequestControl, ResponseControl,
@@ -20,6 +22,10 @@
 from pyasn1.type import univ, namedtype, tag, namedval, constraint
 from pyasn1.codec.ber import encoder, decoder
 
+PY2 = sys.version_info[0] <= 2
+if not PY2:
+  basestring = str
+
 
 #    SortKeyList ::= SEQUENCE OF SEQUENCE {
 #                     attributeType   AttributeDescription,
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__ = {
diff --git a/Lib/ldap/schema/models.py b/Lib/ldap/schema/models.py
diff --git a/Tests/t_ldap_controls_sss.py b/Tests/t_ldap_controls_sss.py
diff --git a/Tests/t_ldap_schema_subentry.py b/Tests/t_ldap_schema_subentry.py
