PyODB Quickstart Guide

The module is packaged using a gzip tar file. The files can be extracted using the command:

tar zxvf pyodb-0.6.tar.gz

This will create a top-level directory pyodb-0.6 which contains the module files. You will need to change to this directory to build and install the module.

The module has been packaged using the standard Python Distribution Utilities (Distutils). To build and install the module, first check the settings of runtime_library_dirs and library_dirs in the file setup.py. These should contain the directory location of the unixODBC library. Then run the following commands to build and install the module:

python setup.py build
python setup.py install (as root)

To help get started an example code file example.py is supplied. This will demonstrate some of the features of the module. See the comments in the source code for more information. You will need to have build and installed the pyodb module and have configured an ODBC data source named test1. The odbc.ini file that contains the data source definition should also contain UserName and Password entries for the data source to allow the connection to be successful. If you know the connection string for your database driver, then you can use this to directly access the driver without the need to define a DSN. It is assumed the user has some familiarity will setting up and configuring ODBC.

Run the sample code using:

python example.py

The output should look something like:

[['one', 'two', 'three'], ['four', 'five', 'six'], ['seven', 'eight', 'nine']]
one two three
four five six
seven eight nine

This section describes the programming interface for the pyodb module.

Class Connect

Description

The Connect class provides a way to connect to a database via an ODBC DSN or directly to the database driver using a connection string. The module allows multiple database connections. The connection remains active until the class instance is destroyed, or if an explicit call is made to the disconnect() method.

Synopsis

Connect([[data-source][,[username],[password]]])

Connect(conn=connection-string)

Return Value

A connection object

Exceptions

ConnectError - Failed to connect to the database

Comments

There are four ways to create a Connect class instance:

Connect()	Creates a connection to the default data source, using the username and password from the odbc.ini file
Connect(data-source)	Creates a connection to the named data source, using the username and password from the odbc.ini file
Connect(data-source, username)	Creates a connection to the named data source, using the supplied username and password from the odbc.ini file
Connect(data-source, username, password)	Creates a connection to the named data source, using the supplied username and password
Connect(conn=connection-string)	Creates a connection directly to the database driver, using the supplied connection string. The syntax for the connection string is driver-specific.

Method execute

Description

The execute method provides a way to execute an arbitary sql statement using the connection object.

Synopsis

execute(sql-statement)

Return Value

The number of rows affected by an updated, insert or delete sql statement.

Exceptions

NotConnectedError - The data source is not connected
ExecuteError - Failed to execute the sql statement

Method fetch

Description

The fetch method provides a way to retrieve the rows returned by a previous execute()

Synopsis

fetch([number-of-rows])

Return Value

A list of lists. With no argument, then all rows are returned. With a positive integer argument, then a maximum of this number of rows is returned.

Exceptions

NotConnectedError - The data source is not connected
FetchError - Failed to execute the sql statement

Comments

If there are still rows to return a successive call to fetch will return the next set of rows.

Method begin

Description

The begin method provides a way to start a transaction.

Synopsis

begin()

Return Value

None

Exceptions

NotConnectedError - The data source is not connected
TransactionError - Failed to begin transaction

Comments

The data source must support transactions.

Method commit

Description

The commit method provides a way to commit a transaction.

Synopsis

commit()

Return Value

None

Exceptions

NotConnectedError - The data source is not connected
TransactionError - Failed to commit transaction

Comments

The data source must support transactions.

Method rollback

Description

The rollback method provides a way to roll back a transaction.

Synopsis

rollback()

Return Value

None

Exceptions

NotConnectedError - The data source is not connected
TransactionError - Failed to roll back transaction

Comments

The data source must support transactions.

Method disconnect

Description

The disconnect method provides a way to perform an explicit disconnect of the data source.

Synopsis

disconnect()

Return Value

None

Exceptions

None

Comments

If no explicit disconnect is made, then the connection is terminated when the connection object is destroyed.

Error Messages

As far as possible all error messages will contain the SQLSTATE and a text message describing the error.

For example:

pyodb.ConnectError: Failed to connect to the data source (08S01:Communication link failure)