Merge pull request #75 from TWAC/connstring

add option to use preformatted ODBC connection string

README.md

@@ -124,6 +124,7 @@ To establish a connection, use any of the following commands:
     >>> connection = connect(dsn='My data source name as given by odbc.ini')
     >>> connection = connect(dsn='my dsn', user='my user has precedence')
     >>> connection = connect(dsn='my dsn', username='field names may depend on the driver')
+    >>> connection = connect(connection_string='Driver={PostgreSQL};Server=IP address;Port=5432;Database=myDataBase;Uid=myUsername;Pwd=myPassword;')
 
 To execute a query, you need a `cursor` object:
 

python/turbodbc/__init__.py

@@ -3,7 +3,7 @@
 from .api_constants import apilevel, threadsafety, paramstyle
 from .connect import connect
 from .constructors import Date, Time, Timestamp
-from .exceptions import Error, InterfaceError, DatabaseError
+from .exceptions import Error, InterfaceError, DatabaseError, ParameterError
 from .data_types import STRING, BINARY, NUMBER, DATETIME, ROWID
 from .options import make_options
 from turbodbc_intern import Rows, Megabytes

python/turbodbc/connect.py

@@ -5,7 +5,7 @@
 
 from turbodbc_intern import connect as intern_connect
 
-from .exceptions import translate_exceptions
+from .exceptions import translate_exceptions, ParameterError
 from .connection import Connection
 from .options import make_options
 
@@ -16,12 +16,14 @@ def _make_connection_string(dsn, **kwargs):
 
 
 @translate_exceptions
-def connect(dsn=None, turbodbc_options=None, read_buffer_size=None, parameter_sets_to_buffer=None, use_async_io=False, **kwargs):
+def connect(dsn=None, turbodbc_options=None, read_buffer_size=None, parameter_sets_to_buffer=None, use_async_io=False, connection_string=None, **kwargs):
     """
     Create a connection with the database identified by the dsn
     :param dsn: Data source name as given in the odbc.ini file
     :param turbodbc_options: Options that control how turbodbc interacts with the database.
      Create such a struct with `turbodbc.make_options()` or leave this blank to take the defaults.
+    :param connection_string: Preformatted ODBC connection string.
+     Specifying this and dsn or kwargs at the same time raises ParameterError.
     :param \**kwargs: You may specify additional options as you please. These options will go into
      the connection string that identifies the database. Valid options depend on the specific database you
      would like to connect with (e.g. `user` and `password` or `uid` and `pwd`)
@@ -43,7 +45,13 @@ def connect(dsn=None, turbodbc_options=None, read_buffer_size=None, parameter_se
         warnings.warn("Calling turbodbc.connect() with parameter use_async_io is deprecated. "
                       "Please use make_options() instead.", DeprecationWarning)
 
-    connection = Connection(intern_connect(_make_connection_string(dsn, **kwargs),
+    if connection_string is not None and (dsn is not None or len(kwargs) > 0):
+        raise ParameterError("Both connection_string and dsn or kwargs specified")
+
+    if connection_string is None:
+        connection_string = _make_connection_string(dsn, **kwargs)
+
+    connection = Connection(intern_connect(connection_string,
                                            turbodbc_options))
 
     return connection

python/turbodbc/exceptions.py

@@ -24,6 +24,10 @@ class DatabaseError(Error):
     pass 
 
 
+class ParameterError(Error):
+    pass
+
+
 def translate_exceptions(f):
     @wraps(f)
     def wrapper(*args, **kwds):

python/turbodbc_test/test_connect.py

@@ -1,6 +1,6 @@
 import pytest
 
-from turbodbc import connect, DatabaseError
+from turbodbc import connect, DatabaseError, ParameterError
 from turbodbc.connect import _make_connection_string
 from turbodbc.connection import Connection
 
@@ -49,3 +49,20 @@ def test_connect_raises_on_invalid_additional_option(dsn, configuration):
     additional_option = {configuration['capabilities']['connection_user_option']: 'invalid user'}
     with pytest.raises(DatabaseError):
         connect(dsn=dsn, **additional_option)
+
+
+def test_connect_raises_on_ambiguous_parameters():
+    with pytest.raises(ParameterError):
+        connect("foo", connection_string="DRIVER=bar;SERVER=baz;")
+    with pytest.raises(ParameterError):
+        connect(connection_string="DRIVER=foo;SERVER=bar;", baz="qux")
+
+
+@for_one_database
+def test_connect_with_connection_string(dsn, configuration):
+    connection_string = "DSN=%s;" % dsn
+    for para, val in get_credentials(configuration).items():
+        connection_string = connection_string + "%s=%s;" % (para, val)
+    connection = connect(connection_string=connection_string)
+    connection.cursor().execute("SELECT 'foo'")
+    connection.close()