more docs

README.rst

@@ -0,0 +1,59 @@
+ldappool
+========
+
+A simple connector pool for python-ldap.
+
+The pool keeps LDAP connectors alive and let you reuse them,
+drastically reducing the time spent to initiate a ldap connection.
+
+The pool has useful features like:
+
+- transparent reconnection on failures or server restarts
+- configurable pool size and connectors timeouts
+- configurable max lifetime for connectors
+- a context manager to simplify acquiring and releasing a connector
+
+
+Quickstart
+::::::::::
+
+To work with the pool, you just need to create it, then use it as a
+context manager with the *connection* method::
+
+    from ldappool import ConnectionManager
+
+    cm = ConnectionManager('ldap://localhost')
+
+    with cm.connection('uid=adminuser,ou=logins,dc=mozilla', 'password') as conn:
+        .. do something with conn ..
+
+
+The connector returned by *connection* is a LDAPObject, that's binded to the
+server. See http://www.python-ldap.org/ for details on how to use a connector.
+
+
+ConnectionManager options
+:::::::::::::::::::::::::
+
+Here are the options you can use when instanciating the pool:
+
+- **uri**: ldap server uri **[mandatory]**
+- **bind**: default bind that will be used to bind a connector.
+  **default: None**
+- **passwd**: default password that will be used to bind a connector.
+  **default: None**
+- **size**: pool size. **default: 10**
+- **retry_max**: number of attempts when a server is down. **default: 3**
+- **retry_delay**: delay in seconds before a retry. **default: .1**
+- **use_tls**: activate TLS when connecting. **default: False**
+- **timeout**: connector timeout. **default: -1**
+- **use_pool**: activates the pool. If False, will recreate a connector
+  each time. **default: True**
+
+
+The **connection** method takes two options:
+
+- **bind**: bind used to connect. If None, uses the pool default's.
+  **default: None**
+- **passwd**: password used to connect. If None, uses the pool default's.
+  **default: None**

ldappool/__init__.py

@@ -118,8 +118,8 @@ class ConnectionManager(object):
     Provides a context manager for LDAP connectors.
     """
     def __init__(self, uri, bind=None, passwd=None, size=10, retry_max=3,
-                 retry_delay=.1, use_tls=False, single_box=False, timeout=-1,
-                 connector_cls=StateConnector, use_pool=False,
+                 retry_delay=.1, use_tls=False, timeout=-1,
+                 connector_cls=StateConnector, use_pool=True,
                  max_lifetime=600):
         self._pool = []
         self.size = size

setup.py

@@ -38,8 +38,13 @@ from setuptools import setup, find_packages
 
 install_requires = ['python-ldap']
 
+with open('README.rst') as f:
+    README = f.read()
+
 
 setup(name='ldappool', version='0.9', packages=find_packages(),
       author='Mozilla Services', author_email='services-dev@mozilla.org',
+      description="A connection pool for python-ldap",
+      long_description=README,
       url='https://github.com/mozilla-services/ldappool',
       install_requires=install_requires)