b678b6883a
If a LDAP connection is initialized without explicitly setting ``bytes_mode`` to either True or False, show warnings instead of raising a TypeError.
175 lines
5.9 KiB
Plaintext
175 lines
5.9 KiB
Plaintext
======
|
|
pyldap
|
|
======
|
|
|
|
pyldap is a fork of the excellent ``python-ldap`` Python project.
|
|
|
|
The goals of this fork are the following:
|
|
|
|
* Bring Python 3 support to ``python-ldap`` while keeping a PY2-compatible codebase
|
|
* Improve tooling and code quality
|
|
* Keep backwards compatibility whenever possible
|
|
|
|
-----------------------
|
|
Backwards compatibility
|
|
-----------------------
|
|
|
|
Users should be able to replace ``python-ldap`` with ``pyldap`` with minimal impact on their code.
|
|
According to this, releases of ``pyldap`` will stick to the numbering of the upstream ``python-ldap`` releases they are based on.
|
|
|
|
However, some compatibility toggles will be added to bring cleaner APIs for PY3 code.
|
|
|
|
Please note the ``pyldap`` installs under the same ``ldap`` module as ``python-ldap``; it **CANNOT** be installed alongside.
|
|
|
|
|
|
--------------------------
|
|
Upgrading from python-ldap
|
|
--------------------------
|
|
|
|
``pyldap`` brings some improvements on top of ``python-ldap``.
|
|
|
|
|
|
Bytes/text management
|
|
=====================
|
|
|
|
The LDAP protocol states that some fields (distinguised names, relative distinguished names,
|
|
attribute names, queries) be encoded in UTF-8; some other (mostly attribute *values*) **MAY**
|
|
contain any type of data, and thus be treated as bytes.
|
|
|
|
However, ``python-ldap`` used bytes for all fields, including those guaranteed to be text.
|
|
In order to support Python 3, ``pyldap`` needs to make this distinction explicit; this is done
|
|
through the ``bytes_mode`` flag to ``ldap.initialize()``.
|
|
|
|
When porting from ``python-ldap``, users are advised to update their code to set ``bytes_mode=False``
|
|
on calls to these methods.
|
|
Under Python 2, ``pyldap`` checks aggressively the type of provided arguments, and will raise a ``TypeError``
|
|
for any invalid parameter; however, if the ``bytes_mode`` kwarg isn't provided, ``pyldap`` will only
|
|
raise warnings.
|
|
|
|
The typical usage is as follow; note that only the result's *values* are of the bytes type:
|
|
|
|
.. code-block:: pycon
|
|
|
|
>>> import ldap
|
|
>>> con = ldap.initialize('ldap://localhost:389', bytes_mode=False)
|
|
>>> con.simple_bind_s('login', 'secret_password')
|
|
>>> results = con.search_s('ou=people,dc=example,dc=org', ldap.SCOPE_SUBTREE, "(cn=Raphaël)")
|
|
>>> results
|
|
[
|
|
("cn=Raphaël,ou=people,dc=example,dc=org", {
|
|
'cn': [b'Rapha\xc3\xabl'],
|
|
'sn': [b'Barrois'],
|
|
}),
|
|
]
|
|
|
|
|
|
---------------------------------------
|
|
python-ldap: LDAP client API for Python
|
|
---------------------------------------
|
|
|
|
What is python-ldap?
|
|
====================
|
|
|
|
python-ldap provides an object-oriented API to access LDAP
|
|
directory servers from Python programs. Mainly it wraps the
|
|
OpenLDAP client libs for that purpose.
|
|
|
|
Additionally the package contains modules for other LDAP-related
|
|
stuff (e.g. processing LDIF, LDAPURLs, LDAPv3 sub-schema, etc.).
|
|
|
|
Not included: Direct BER support
|
|
|
|
See INSTALL for version compability
|
|
|
|
See TODO for planned features. Contributors welcome.
|
|
|
|
For module documentation, see:
|
|
|
|
http://www.python-ldap.org/
|
|
|
|
Quick usage example:
|
|
====================
|
|
|
|
.. code-block:: python
|
|
|
|
import ldap
|
|
l = ldap.initialize("ldap://my_ldap_server.my_domain")
|
|
l.simple_bind_s("","")
|
|
l.search_s("o=My Organisation, c=AU", ldap.SCOPE_SUBTREE, "objectclass=*")
|
|
|
|
See directory ``Demo/`` of source distribution package for more
|
|
example code.
|
|
|
|
Author(s) contact and documentation:
|
|
====================================
|
|
|
|
http://www.python-ldap.org/
|
|
|
|
If you are looking for help, please try the mailing list archives
|
|
first, then send a question to the mailing list.
|
|
Be warned that questions will be ignored if they can be
|
|
trivially answered by referring to the documentation.
|
|
|
|
If you are interested in helping, please contact the mailing list.
|
|
If you want new features or upgrades, please check the mailing list
|
|
archives and then enquire about any progress.
|
|
|
|
Acknowledgements:
|
|
=================
|
|
|
|
Thanks to Konstantin Chuguev <Konstantin.Chuguev at dante.org.uk>
|
|
and Steffen Ries <steffen.ries at sympatico.ca> for working
|
|
on support for OpenLDAP 2.0.x features.
|
|
|
|
Thanks to Michael Stroeder <michael at stroeder.com> for the
|
|
modules ``ldif``, ``ldapurl``, ``ldap/schema/*.py``, ``ldap/*.py`` and ``ldap/controls/*.py``.
|
|
|
|
Thanks to Hans Aschauer <Hans.Aschauer at Physik.uni-muenchen.de>
|
|
for the C wrapper schema and SASL support.
|
|
|
|
Thanks to Mauro Cicognini <mcicogni at siosistemi.it> for the
|
|
WIN32/MSVC6 bits, and the pre-built WIN32 ``ldap.pyd``.
|
|
|
|
Thanks to Waldemar Osuch <waldemar.osuch at gmail.com> for contributing
|
|
the new-style docs based on reStructuredText.
|
|
|
|
Thanks to Torsten Kurbad <torsten at tk-webart.de> for the
|
|
easy_install support.
|
|
|
|
Thanks to James Andrewartha <jamesa at daa.com.au> for
|
|
significant contribution to ``Doc/*.tex``.
|
|
|
|
Thanks to Rich Megginson <rmeggins at redhat.com> for extending
|
|
support for LDAPv3 controls and adding support for LDAPv3 extended
|
|
operations.
|
|
|
|
Thanks to Peter Gietz, DAASI for funding some control modules.
|
|
|
|
Thanks to Chris Mikkelson for various fixes and ldap.syncrepl.
|
|
|
|
These very kind people have supplied patches or suggested changes:
|
|
|
|
* Federico Di Gregorio <fog at mixadlive.com>
|
|
* John Benninghoff <johnb at netscape.com>
|
|
* Donn Cave <donn at u.washington.edu>
|
|
* Jason Gunthorpe <jgg at debian.org>
|
|
* gurney_j <gurney_j at 4j.lane.edu>
|
|
* Eric S. Johansson <esj at harvee.billerica.ma.us>
|
|
* David Margrave <davidma at premier1.net>
|
|
* Uche Ogbuji <uche.ogbuji at fourthought.com>
|
|
* Neale Pickett <neale at lanl.gov>
|
|
* Blake Weston <weston at platinum1.cambridge.scr.slb.com>
|
|
* Wido Depping <wido.depping at gmail.com>
|
|
* Deepak Giridharagopal <deepak at arlut.utexas.edu>
|
|
* Ingo Steuwer <steuwer at univention.de>
|
|
* Andreas Hasenack <ahasenack at terra.com.br>
|
|
* Matej Vela <vela at debian.org>
|
|
|
|
Thanks to all the guys on the python-ldap mailing list for
|
|
their contributions and input into this package.
|
|
|
|
Thanks! We may have missed someone: please mail us if we have omitted
|
|
your name.
|
|
|
|
.. $Id: README,v 1.25 2011/10/26 18:43:21 stroeder Exp $
|