Skip to content

Commit

Permalink
Merge pull request #44 – Doc: Include information from python-ldap.org
Browse files Browse the repository at this point in the history 
https://github.com/python-ldap/python-ldap/pull/44
  • Loading branch information
Petr Viktorin authored and GitHub committed Nov 28, 2017
2 parents 680c342 + 574c902 commit 1626749
Show file tree
Hide file tree
Showing 22 changed files with 563 additions and 186 deletions.
136 changes: 68 additions & 68 deletions Doc/Makefile
View file
Original file line number Diff line number Diff line change
@@ -1,68 +1,68 @@
# Makefile for Sphinx documentation
#

# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
PAPER =

# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d .build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .

.PHONY: help clean html web htmlhelp latex changes linkcheck

help:
@echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
@echo " web to make files usable by Sphinx.web"
@echo " htmlhelp to make HTML files and a HTML help project"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " changes to make an overview over all changed/added/deprecated items"
@echo " linkcheck to check all external links for integrity"

clean:
-rm -rf .build/*

html:
mkdir -p .build/html .build/doctrees
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) .build/html
@echo
@echo "Build finished. The HTML pages are in .build/html."

web:
mkdir -p .build/web .build/doctrees
$(SPHINXBUILD) -b web $(ALLSPHINXOPTS) .build/web
@echo
@echo "Build finished; now you can run"
@echo " python -m sphinx.web .build/web"
@echo "to start the server."

htmlhelp:
mkdir -p .build/htmlhelp .build/doctrees
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) .build/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in .build/htmlhelp."

latex:
mkdir -p .build/latex .build/doctrees
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) .build/latex
@echo
@echo "Build finished; the LaTeX files are in .build/latex."
@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
"run these through (pdf)latex."

changes:
mkdir -p .build/changes .build/doctrees
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) .build/changes
@echo
@echo "The overview file is in .build/changes."

linkcheck:
mkdir -p .build/linkcheck .build/doctrees
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) .build/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in .build/linkcheck/output.txt."
# Makefile for Sphinx documentation
#

# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
PAPER =

# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d .build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .

.PHONY: help clean html web htmlhelp latex changes linkcheck

help:
@echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
@echo " web to make files usable by Sphinx.web"
@echo " htmlhelp to make HTML files and a HTML help project"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " changes to make an overview over all changed/added/deprecated items"
@echo " linkcheck to check all external links for integrity"

clean:
-rm -rf .build/*

html:
mkdir -p .build/html .build/doctrees
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) .build/html
@echo
@echo "Build finished. The HTML pages are in .build/html."

web:
mkdir -p .build/web .build/doctrees
$(SPHINXBUILD) -b web $(ALLSPHINXOPTS) .build/web
@echo
@echo "Build finished; now you can run"
@echo " python -m sphinx.web .build/web"
@echo "to start the server."

htmlhelp:
mkdir -p .build/htmlhelp .build/doctrees
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) .build/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in .build/htmlhelp."

latex:
mkdir -p .build/latex .build/doctrees
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) .build/latex
@echo
@echo "Build finished; the LaTeX files are in .build/latex."
@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
"run these through (pdf)latex."

changes:
mkdir -p .build/changes .build/doctrees
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) .build/changes
@echo
@echo "The overview file is in .build/changes."

linkcheck:
mkdir -p .build/linkcheck .build/doctrees
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) .build/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in .build/linkcheck/output.txt."
2 changes: 1 addition & 1 deletion Doc/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@
# If your extensions are in another directory, add it here.
_doc_dir = os.path.dirname(__file__)
sys.path.append(_doc_dir)
sys.path.append(os.path.join(_doc_dir, '../Lib/'))
sys.path.insert(0, os.path.join(_doc_dir, '../Lib/'))
sys.path.insert(0, os.path.join(_doc_dir, '../Lib/ldap'))

# Import fake `_ldap` module
Expand Down
184 changes: 184 additions & 0 deletions Doc/faq.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,184 @@
python-ldap FAQ
===============

Project
-------

**Q**: Is python-ldap yet another abandon-ware project?

**A1**: “Jump on in.”

**A2**: “Jump into the C ;-)”

**A3**: see file CHANGES in source distribution
or `repository`_.

.. _repository: https://github.com/python-ldap/python-ldap/blob/master/CHANGES


Usage
-----

**Q**: Does it work with Python 3?

**A0**: Yes, from 3.0 on.

**A1**. For earlier versions, there's `pyldap`_, an independent fork
now merged into pyhon-ldap.

.. _pyldap: https://pypi.python.org/pypi/pyldap


**Q**: Does it work with Python 2.6? (1.5|2.0|2.1|2.2|2.3|2.4|2.5)?

**A**: No. Old versions of python-ldap are still available from PyPI, though.


**Q**: My code imports module ``_ldap``.
That used to work but from version 2.0.0pre that does not work anymore?

**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``
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."
What's happening here?

**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
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
chasing referrals received from and pointing to arbitrary LDAP servers.

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::

l = ldap.initialize('ldap://foobar')
l.set_option(ldap.OPT_REFERRALS,0)

**Q**: Why am I seeing ``ldap.SUCCESS`` traceback as output?

**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`.

**Q**: Can I use LDAPv2 via python-ldap?

**A**: Yes, by explicitly setting the class attribute
:attr:`~ldap.LDAPObject.protocol_version`.

You should not do that nowadays since
`LDAPv2 is considered historic <https://tools.ietf.org/html/rfc3494>`_
since many years.



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.


**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.
Patched builds of python-ldap linked to older libs are not supported by the
python-ldap project.


**Q**: During build there are warning messages displayed
telling Lib/ldap.py and Lib/ldap/schema.py are not found::

warning: build_py: file Lib/ldap.py (for module ldap) not found
warning: build_py: file Lib/ldap/schema.py (for module ldap.schema) not found

..
**A**: ``ldap`` and ``ldap.schema`` are both module packages
(directories containing various sub-modules).
The messages above are falsely produced by DistUtils.
Don't worry about it.

.. _install-macosx:

**Q**: What's the correct way to install on Mac OS X?

**A**::

xcode-select --install
pip install python-ldap \
--global-option=build_ext \
--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::

ImportError: ld.so.1: /usr/local/bin/python: fatal: liblber.so.2: open failed: No such file or directory

..
**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
``liblber.so.2`` and ``libldap.so.2`` to ``/etc/ld.so.conf``
and invoke command ``ldconfig`` afterwards.



Historic
--------

**Q**: Can python-ldap 2.x be built against Netscape, Mozilla or Novell libs?

**A**: Nope.


**Q**: My binary version of python-ldap was build with LDAP libs 3.3.
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
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.

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
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
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::

ImportError: /usr/local/lib/libldap.so.2: undefined symbol: res_query

..
**A**: Especially on older Linux systems you might have to explicitly link
against ``libresolv``.

Tweak ``setup.cfg`` to contain this line::

libs = lber ldap resolv
Loading

0 comments on commit 1626749

Please sign in to comment.