RETIRED, further work has moved to Debian project infrastructure
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Petr Viktorin 37fd75aa12 Merge branch '2016-06-01-better-error-message' of https://github.com/Firstyear/pyldap 2 years ago
Build FWIW corrected typo in MAINTAINER=leonard@users.sourceforge.net 4 years ago
Demo Merge branch 'cvs' 3 years ago
Doc Merge from CVS 3 years ago
Lib Merge pull request #33 from Firstyear/2016-02-18-python-ldap-id-clean 3 years ago
Modules Improve the error message to specifically refer to byte string for the benefit of python 3 3 years ago
Tests Add tests for ldap.add_ext. 3 years ago
.cvsignore *** empty log message *** 17 years ago
.gitignore Automate testing with tox 3 years ago
.travis.yml Travis CI: Use tox-travis to make .travis.yml more readable 3 years ago
CHANGES Release v2.4.25.1 3 years ago
INSTALL Updated/completed dependencies 8 years ago
LICENCE Readd LICENCE 3 years ago
MANIFEST.in Added PKG-INFO 9 years ago
README Add travis-ci status to README page. 3 years ago
README.rst Update README with project goals. 3 years ago
TODO Extract response controls in SASL bind responses 4 years ago
setup.cfg Update packaging informations to point at pyldap. 3 years ago
setup.py Added trove classifiers to setup.setup() 3 years ago
tox.ini Add tests for ldap.add_ext. 3 years ago

README

======
pyldap
======

.. image:: https://travis-ci.org/pyldap/pyldap.svg?branch=master
:target: https://travis-ci.org/pyldap/pyldap
:alt: Continuous integration status

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 $