Allow pool status to be printed as a table

This patch adds a __str__() method to the ConnectionManager class,
which allows for a nice readible table to be obtained that shows
the current state of the connection pool.  This can be very useful
for troubleshooting or monitoring issues related to connection
pooling.  The table will contain a row for each connection within
the pool, with columns showing the connection slot, connectivity
status, activity status, URI, connection lifetime, and bind DN.
The header row will also indicate the pool size and maximum
connection lifetime setting.

Note that this adds a dependency on the prettytable module.  This
new dependency seems worth it for the nice readible table format
it produces.

Change-Id: If0abfef405d05ecd499bdf6201ff465bd845957b

README.rst

@@ -32,6 +32,25 @@ context manager with the *connection* method::
 The connector returned by *connection* is a LDAPObject, that's binded to the
 server. See https://pypi.org/project/python-ldap/ for details on how to use a connector.
 
+It is possible to check the state of the pool by representing the pool as a string::
+
+    from ldappool import ConnectionManager
+
+    cm = ConnectionManager('ldap://localhost', size=2)
+
+    .. do something with cm ..
+
+    print(cm)
+
+This will result in output similar to this table::
+
+    +--------------+-----------+----------+------------------+--------------------+------------------------------+
+    | Slot (2 max) | Connected |  Active  |       URI        | Lifetime (600 max) |           Bind DN            |
+    +--------------+-----------+----------+------------------+--------------------+------------------------------+
+    |      1       | connected | inactive | ldap://localhost |  0.00496101379395  | uid=tuser,dc=example,dc=test |
+    |      2       | connected | inactive | ldap://localhost |  0.00532603263855  | uid=tuser,dc=example,dc=test |
+    +--------------+-----------+----------+------------------+--------------------+------------------------------+
+
 
 ConnectionManager options
 :::::::::::::::::::::::::

ldappool/__init__.py

@@ -43,6 +43,7 @@ import time
 
 import ldap
 from ldap.ldapobject import ReconnectLDAPObject
+from prettytable import PrettyTable
 import re
 import six
 from six import PY2
@@ -423,3 +424,20 @@ class ConnectionManager(object):
                     log.debug('Failure attempting to unbind on purge; '
                               'should be harmless', exc_info=True)
                 self._pool.remove(conn)
+
+    def __str__(self):
+        table = PrettyTable()
+        table.field_names = ['Slot (%d max)' % self.size,
+                             'Connected', 'Active', 'URI',
+                             'Lifetime (%d max)' % self.max_lifetime,
+                             'Bind DN']
+
+        with self._pool_lock:
+            for slot, conn in enumerate(self._pool):
+                table.add_row([
+                    slot + 1,
+                    'connected' if conn.connected else 'not connected',
+                    'active' if conn.active else 'inactive',
+                    conn._uri, conn.get_lifetime(), conn.who])
+
+        return str(table)

lower-constraints.txt

@@ -17,6 +17,7 @@ openstackdocstheme==1.18.1
 pbr==2.0.0
 pep257==0.7.0
 pep8==1.5.7
+prettytable==0.7.2
 pyflakes==0.8.1
 Pygments==2.2.0
 python-ldap==3.0.0

requirements.txt

@@ -2,3 +2,4 @@
 # of appearance. Changing the order has an impact on the overall integration
 # process, which may cause wedges in the gate later.
 python-ldap>=3.0.0 # PSF
+PrettyTable<0.8,>=0.7.2