[Note on the note below: Jeffrey C. Ollie says he's no longer
 maintaining the Python mSQL module, so this is version 2.0b of
 mSQLmodule, tested with Python 1.5.2 and mSQL 2.0.5, See the
 source for a list of changes. Vincent]

[Note: there is reputed to be a newer, 2.0 compliant version of the
 msql module at <http://www.ollie.clive.ia.us/python/msql/>.]

This is a brief overview of the mSQL module for Python.

CONTENTS

 1. History
 2. Compiling and installing the mSQL module
 3. Exported types, functions and classes
 3. Using the mSQL module
 4. Pointers to other information

HISTORY

Anthony Baxter wrote msqlmodule, an interface from Python to
the client library distributed with mSQL.  It was written for
early versions of the mSQL API and the Python interpreter, though
as far as I can tell still worked reasonably well.

Thanks, Anthony!

It did, however, have a few rough edges which this release
seeks to smooth over.  In particular,  some queries resulted in
inconsistent return values  (like a lisk of an empty tuple ;-),
and all returned valuesets came as lists of tuples of strings.

I commissioned David to clean this up,  and on the way a couple
of other things got fixed / added.  I'm told that both Python
and the existing msqlmodule.c made the job reasonably straightforward
(thanks,  Guido!).

The changes include  (see the source for a full list):

 - better return value handling, suing native types where appropriate
 - some initialisation fixes and cleanups  (*wierd* bug / feature)
 - memory allocation / deallocation fix(es)
 - now exports the database type for type comparisons
 - has its own exception, rather than using TypeError all the time

Please report all bugs / feature requests to marks@aztec.co.za
(Mark Shuttleworth)


COMPILING AND INSTALLING

Development took place on a Linux 1.2.13 a.out system, so please
send comments / patches if this isn't portable. I know one should
use the generalised extensions / makefile system,  but I got
confused... and this works for me, so there!

  i. I assume you've download the source from ftp.python.org or
     a mirror,  somewhere under pub/python/contrib

 ii. Uncompress and untar the package into its own directory.

iii. Copy mSQLmodule.c into your Modules subdirectory of the Python
     source distribution.

 iv. Add the following line to your Setup file in that directory:

mSQL mSQLmodule.c /usr/local/Minerva/lib/libmsql.a -I/usr/local/Minerva/include

     Note that the location of the mSQL library may be different on
     your particular system, as may the include directory.

  v. Recreate the Makefile by deleting it and running ./makesetup

 vi. Type make

You should end up with a python interpreter in the parent directory
which reports mSQL as a builtin module, unless you're using dynamically
loaded modules in which case you need to copy the .so file to a suitable
place in your PYTHONPATH.

Note that the module is case sensitive, and that the name has been changed
to mSQL *deliberately* so as not to break any existing code that uses
Anthony's modules.  Tough luck all you DOS / Mac insensitive people ;-)

EXPORTED TYPES AND OBJECTS

The module exports the following:

  DbType:   the type of the database object
  error:    an exception raised in certain circumstances (rather than TypeError)
  connect(host=None) 
            a function returning a database object.  The optional argument
            is the name of the host to connect to.  If left out the function
            will assume you mean the local host.

A database object as returned by mSQL.connect() exports the following
methods:

  db.listdbs()
    returns a list of strings giving the names of the databases on the
    mSQL host to which one has connected with mSQL.connect()

  db.selectdb(string)
    attaches this object to a particular database.  Queries executed
    will be directed to that database until another selectdb method
    call is made.

  db.listtables()
    return a list of strings giving the table names in the selected
    database.  Only valid after a selectdb call has been made.

  db.listfields(string)
    return a description of the fields in the given table, as a list
    of tuples,  where each tuple contains the same information as is
    given by the relshow command in the mSQL admin suite.

  db[QUERY_STRING]
    execute the given SQL query string against the selected database,
    returning a list of rows,  where each row is a tuple of native
    Python data objects  (string, int or real), or raising an exception
    if a parserror or type error occurred.

USING THE MSQL MODULE

Instruction by example:

import mSQL
aDataBase = mSQL.connect('phoenix.thawte.co.za')
print aDataBase.listdbs()
aDataBase.selectdb('testdb')
aDataBase.listfields('alltypes')
result = aDataBase['SELECT * FROM alltypes WHERE id=24']
print result


There,  hope that helps ;-)


POINTER TO OTHER INFORMATION AND CODE

The mSQL source is at:       ftp://ftp.bond.edu/pub/Minerva/msql
All of Python is at:         ftp://ftp.python.org/pub/python/src/
The module will reside in:   ftp://ftp.python.org/pub/contrib/database/

Mark Shuttleworth can be reached at marks@aztec.co.za