diff --git a/Doc/faq.rst b/Doc/faq.rst index 58bb81e..ef479a8 100644 --- a/Doc/faq.rst +++ b/Doc/faq.rst @@ -35,41 +35,41 @@ Usage **Q**: My code imports module ``_ldap``. -That used to work but from version 2.0.0pre that does not work anymore? +That used to work, but after an upgrade it does not work anymore. Why? - **A**: Despite some outdated programming examples the extension module - ``_ldap`` **MUST NOT** be imported directly unless - you really know what you're doing (e.g. for internal regression testing). + **A**: Despite some outdated programming examples, the extension module + ``_ldap`` **MUST NOT** be imported directly, unless you really know what + you're doing (e.g. for internal regression testing). - Import ``ldap`` instead which is a Python wrapper around ``_ldap`` + Import ``ldap`` instead, which is a Python wrapper around ``_ldap`` providing the full functionality. **Q**: My script bound to MS Active Directory but a a search operation results -in an exception :exc:`ldap.OPERATIONS_ERROR` with the diagnostic messages text -"In order to perform this operation a successful bind must be -completed on the connection." +in the exception :exc:`ldap.OPERATIONS_ERROR` with the diagnostic messages text +“In order to perform this operation a successful bind must be +completed on the connection.” What's happening here? - **A**: When searching from the domain level MS AD returns referrals (search continuations) + **A**: When searching from the domain level, MS AD returns referrals (search continuations) for some objects to indicate to the client where to look for these objects. - Client-chasing of referrals is a broken concept since LDAPv3 does not specify + Client-chasing of referrals is a broken concept, since LDAPv3 does not specify which credentials to use when chasing the referral. Windows clients are supposed - to simply use their Windows credentials but this does not work in general when + to simply use their Windows credentials, but this does not work in general when chasing referrals received from and pointing to arbitrary LDAP servers. - Therefore per default ``libldap`` automatically chases the referrals + Therefore, per default, ``libldap`` automatically chases the referrals internally with an *anonymous* access which fails with MS AD. - So best thing is to switch this behaviour off:: + So, the best thing to do is to switch this behaviour off:: l = ldap.initialize('ldap://foobar') l.set_option(ldap.OPT_REFERRALS,0) -**Q**: Why am I seeing ``ldap.SUCCESS`` traceback as output? +**Q**: Why am I seeing a ``ldap.SUCCESS`` traceback as output? - **A**: Most likely you are using one of the non-synchronous calls, and probably + **A**: Most likely, you are using one of the non-synchronous calls, and probably mean to be using a synchronous call - (see detailed explanation in :ref:`sending-ldap-requests`. + (see detailed explanation in :ref:`sending-ldap-requests`). **Q**: Can I use LDAPv2 via python-ldap? @@ -87,13 +87,14 @@ Installing **Q**: Does it work with Windows 32? - **A**: You can find links to pre-compiled packages for Win32 on the - :ref:`Download information` page. + **A**: Yes. You can find links to unofficial pre-compiled packages + for Windows on the :ref:`installing` page. **Q**: Can python-ldap be built against OpenLDAP 2.3 libs or older? - **A**: No, for recent python-ldap 2.4.x the OpenLDAP 2.4 client libs or newer are required. + **A**: No. + The needed minimal version of OpenLDAP is documented in :ref:`build prerequisites`. Patched builds of python-ldap linked to older libs are not supported by the python-ldap project. @@ -123,8 +124,8 @@ telling Lib/ldap.py and Lib/ldap/schema.py are not found:: --global-option="-I$(xcrun --show-sdk-path)/usr/include/sasl" -**Q**: While importing module ldap some shared lib files are not found. -Error message looks similar to this:: +**Q**: While importing module ``ldap``, some shared lib files are not found. +The error message looks similar to this:: ImportError: ld.so.1: /usr/local/bin/python: fatal: liblber.so.2: open failed: No such file or directory @@ -133,9 +134,9 @@ Error message looks similar to this:: **A1**: You need to make sure that the path to ``liblber.so.2`` and ``libldap.so.2`` is in your ``LD_LIBRARY_PATH`` environment variable. - **A2**: Alternatively if you're on Linux you can add the path to + **A2**: Alternatively, if you're on Linux, you can add the path to ``liblber.so.2`` and ``libldap.so.2`` to ``/etc/ld.so.conf`` - and invoke command ``ldconfig`` afterwards. + and invoke the command ``ldconfig`` afterwards. @@ -151,32 +152,32 @@ Historic But the python-ldap docs say LDAP libs 2.x are needed. I'm confused! Short answer: - See answer above and :ref:`download information` for + See answer above and the :ref:`installing` page for a more recent version. Long answer: E.g. some Win32 DLLs floating around for download are based on the old Umich LDAP code which is not maintained anymore for - ``many`` years! Last Umich 3.3 release was 1997 if I remember correctly. + *many* years! Last Umich 3.3 release was 1997 if I remember correctly. The OpenLDAP project took over the Umich code and started releasing OpenLDAP 1.x series mainly fixing bugs and doing some improvements - to the database backend. Still only LDAPv2 was supported at server + to the database backend. Still, only LDAPv2 was supported at server and client side. (Many commercial vendors also derived their products from the Umich code.) - OpenLDAP 2.x is a full-fledged LDAPv3 implementation. Still it has + OpenLDAP 2.x is a full-fledged LDAPv3 implementation. It has its roots in Umich code but has many more features/improvements. -**Q**: While importing module ldap there are undefined references reported. -Error message looks similar to this:: +**Q**: While importing module ``ldap``, there are undefined references reported. +The error message looks similar to this:: ImportError: /usr/local/lib/libldap.so.2: undefined symbol: res_query .. - **A**: Especially on older Linux systems you might have to explicitly link + **A**: Especially on older Linux systems, you might have to explicitly link against ``libresolv``. Tweak ``setup.cfg`` to contain this line:: diff --git a/Doc/index.rst b/Doc/index.rst index 6d2f1ac..b346145 100644 --- a/Doc/index.rst +++ b/Doc/index.rst @@ -5,30 +5,35 @@ python-ldap What is python-ldap? -------------------- -* python-ldap provides an object-oriented API to access LDAP - directory servers from `Python`_ programs. -* For LDAP operations the module wraps `OpenLDAP`_'s - client library *libldap* for that purpose. -* Additionally the package contains modules for other LDAP-related stuff: +python-ldap provides an object-oriented API to access `LDAP`_ +directory servers from `Python`_ programs. - * LDIF +For LDAP operations the module wraps `OpenLDAP`_'s +client library, *libldap*. + +Additionally, the package contains modules for other LDAP-related stuff: + + * `LDIF`_ parsing and generation * LDAP URLs * LDAPv3 subschema +.. _LDAP: https://en.wikipedia.org/wiki/Ldap .. _Python: https://www.python.org/ .. _OpenLDAP: https://www.openldap.org/ +.. _LDIF: https://en.wikipedia.org/wiki/LDIF Get it! ------- -:ref:`Download information` is available for several platforms. +:ref:`Installation instructions ` are available for +several platforms. Mailing list ------------ -Discussion about the use and future of Python-LDAP occurs in +Discussion about the use and future of python-ldap occurs in the ``python-ldap@python.org`` mailing list. You can `subscribe or unsubscribe`_ to this list or browse the `list archive`_. @@ -43,7 +48,7 @@ Documentation The documentation for python-ldap 3.x is hosted at `Read the Docs`_. You can switch between versions of the library, or download PDF or HTML -versions for offline use, using the right sidebar. +versions for offline use, using the sidebar on the right. Documentation for some older versions is available for download at the `GitHub release page`_. diff --git a/Doc/installing.rst b/Doc/installing.rst index 2ea5594..f2dec81 100644 --- a/Doc/installing.rst +++ b/Doc/installing.rst @@ -1,4 +1,4 @@ -.. _Download information: +.. _installing: Installing python-ldap ###################### @@ -7,7 +7,7 @@ Installing from PyPI ==================== The preferred point for downloading the “official” source distribution -is now the `PyPI repository`_ which supports installing via `pip`_. +is the `PyPI repository`_ which supports installing via `pip`_. For example:: python -m pip install python-ldap @@ -15,7 +15,7 @@ For example:: .. _PyPI repository: https://pypi.python.org/pypi/python-ldap/ .. _pip: https://pip.pypa.io/en/stable/ -For installing from PyPI, you will need the :ref:`build prerequisites` +For installing from PyPI, you will need the same :ref:`build prerequisites` as when installing from source. We do not currently provide pre-built packages (wheels). @@ -94,7 +94,7 @@ 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. -See further instructions can be found in `Setuptools documentation`_. +Further instructions can be found in `Setuptools documentation`_. .. _Setuptools documentation: https://docs.python.org/3/distributing/index.html @@ -112,13 +112,13 @@ on the local system when building python-ldap: - `OpenLDAP`_ client libs version 2.4.11 or later It is not possible and not supported to build with prior versions. - `OpenSSL`_ (optional) -- `cyrus-sasl`_ (optional) +- `Cyrus SASL`_ (optional) - Kerberos libraries, MIT or Heimdal (optional) .. _Python: https://www.python.org/ .. _OpenLDAP: https://www.openldap.org/ .. _OpenSSL: https://www.openssl.org/ -.. _cyrus-sasl: https://www.cyrusimap.org/sasl/ +.. _Cyrus SASL: https://www.cyrusimap.org/sasl/ setup.cfg @@ -126,9 +126,9 @@ 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 the -documentation of Python's DistUtils. +software packages. Only section ``[_ldap]`` is described here. +More information about other sections can be found in +`Setuptools documentation`_. .. data:: library_dirs @@ -148,9 +148,10 @@ documentation of Python's DistUtils. .. data:: extra_objects -.. _libs-used-label: +.. _libs-used-label: + Libraries used --------------- @@ -159,7 +160,7 @@ Libraries used .. data:: ldap_r :noindex: - The LDAP protocol library of OpenLDAP. ldap_r is the reentrant version + The LDAP protocol library of OpenLDAP. ``ldap_r`` is the reentrant version and should be preferred. .. data:: lber @@ -170,25 +171,25 @@ Libraries used .. data:: sasl2 :noindex: - The Cyrus-SASL library if needed and present during build + The Cyrus-SASL library (optional) .. data:: ssl :noindex: - The SSL/TLS library of OpenSSL if needed and present during build + The SSL/TLS library of OpenSSL (optional) .. data:: crypto :noindex: - The basic cryptographic library of OpenSSL if needed and present during build + The basic cryptographic library of OpenSSL (optional) Example ------- The following example is for a full-featured build (including SSL and SASL support) of python-ldap with OpenLDAP installed in a different prefix directory -(here /opt/openldap-2.4) and SASL header files found in /usr/include/sasl. -Debugging symbols are preserved with compile option -g. +(here ``/opt/openldap-2.4``) and SASL header files found in /usr/include/sasl. +Debugging symbols are preserved with compile option ``-g``. :: diff --git a/Doc/spelling_wordlist.txt b/Doc/spelling_wordlist.txt index 39df00f..a8b7e16 100644 --- a/Doc/spelling_wordlist.txt +++ b/Doc/spelling_wordlist.txt @@ -31,7 +31,7 @@ controlType controlValue criticality cryptographic -cyrus +Cyrus defresult dereferenced dereferencing @@ -91,7 +91,7 @@ objectClass oc oid oids -openldap +OpenLDAP postalAddress pre previousDN