Merge branch 'feature/db-properties-more-documentation'

.travis.yml

@@ -46,6 +46,7 @@ install:
 script:
   - if [ -z "$JYTHON" ]; then PY="coverage run --source jaydebeapi"; else PY="python" ;fi
   - $PY test/testsuite.py $TESTNAME
+  - if [ "$JDBC_DRIVER" == "org.hsqldb:hsqldb:1.8.0.10" ] ; then $PY test/doctests.py ;fi
 
 after_success:
   - if [ -z "$JYTHON" ]; then coveralls ;fi

README.rst

@@ -88,10 +88,10 @@ environment.
 Here is an example:
 
 >>> import jaydebeapi
->>> conn = jaydebeapi.connect('org.hsqldb.jdbcDriver',
+>>> conn = jaydebeapi.connect("org.hsqldb.jdbcDriver",
-...                           'jdbc:hsqldb:mem:.',
+...                           "jdbc:hsqldb:mem:.",
-...                           ['SA', ''],
+...                           ["SA", ""],
-...                           '/path/to/hsqldb.jar',)
+...                           "/path/to/hsqldb.jar",)
 >>> curs = conn.cursor()
 >>> curs.execute('create table CUSTOMER'
 ...                '("CUST_ID" INTEGER not null,'
@@ -102,12 +102,24 @@ Here is an example:
 >>> curs.execute("select * from CUSTOMER")
 >>> curs.fetchall()
 [(1, u'John')]
+>>> curs.close()
+>>> conn.close()
+
+An alternative way to establish connection using connection
+properties:
+
+>>> conn = jaydebeapi.connect("org.hsqldb.jdbcDriver",
+...                           "jdbc:hsqldb:mem:.",
+...                           {'user': "SA", 'password': "",
+...                            'other_property': "foobar"},
+...                           "/path/to/hsqldb.jar",)
+
 
 If you're having trouble getting this work check if your ``JAVA_HOME``
 environmentvariable is set correctly. For example I have to set it on
 my Ubuntu machine like this ::
 
-    $ JAVA_HOME=/usr/lib/jvm/java-6-openjdk python
+    $ JAVA_HOME=/usr/lib/jvm/java-8-openjdk python
 
 Supported databases
 ===================

test/doctests.py

@@ -0,0 +1,32 @@
+#!/usr/bin/env python
+"""Run doctests."""
+
+import doctest
+import sys
+
+try:
+    import unittest2 as unittest
+except ImportError:
+    import unittest
+
+class Py23DocChecker(doctest.OutputChecker):
+    """Doctest checker to avoid Python 2/3 unicode comparison
+    issues. Code taken from Dirkjan Ochtman"""
+    def check_output(self, want, got, optionflags):
+        if sys.version_info[0] > 2:
+            want = re.sub("u'(.*?)'", "'\\1'", want)
+            want = re.sub('u"(.*?)"', '"\\1"', want)
+        return doctest.OutputChecker.check_output(self, want, got, optionflags)
+
+def suite():
+    suite = unittest.TestSuite()
+    suite.addTest(doctest.DocFileSuite('../README.rst',
+                                       checker=Py23DocChecker()))
+    return suite;
+
+def main():
+    runner = unittest.TextTestRunner()
+    runner.run(suite())
+
+if __name__ == '__main__':
+    sys.exit(main())