[PYTHON DB-SIG] Strawman API

Greg Stein greg_stein@eshop.com
Fri, 12 Jan 1996 18:58:36 -0800


Michael McLay posted a stawman on the Meta SIG while we were starting up
this list. I've lost that post (can somebody resend that, please?), but he
had the right idea. Let's get a strawman out that can be discussed and shot
full of holes and rebuilt. This strawman falls under the DB SIG's goal of
"Create a generic interface for tabular databases."

Here is a strawman for an API exposed by a database module, based on some
of my own experience with the Oracle module.

Some questions I pose are:
- do we need a close() method or can we just assume the user can clear out
all references?
- what should the format be for describe()
- does anything need to change for callproc() ?
- should we attempt to can we extend this API to include non-tabular
databases? e.g. DBM, object databases, etc. Is it even possible to?

Related to this... it looks like I'm going to be building an Informix
module in the next few weeks. I have no problem changing things later, but
I would hope that we can get a basic structure down for a database API that
wouldn't throw things off too much :-). I would think that I could release
the Informix module in about 8 weeks, and possibly some prereleases sooner.

-g

-----
class <modname>:
  def __init__(self, connection_string):
    "Open a connection to a database, returning a Connection instance"

    # last Cursor opened
    self.implicit_cursor = None

  def close(self):
    "Close the connection now (rather than whenever __del__ is called)."
    pass

  def commit(self):
    "Commit any pending transaction to the database."
    pass

  def rollback(self):
    "Roll the database back to the start of any pending transaction."
    pass

  def cursor(self):
    "Return a new cursor."
    pass

  def callproc(self, name, params=None):
    """\
Call a stored procedure with the given (optional) parameters.  Return the
result of the store procedure."""
    pass

  # Implement all Cursor methods (except close), by routing the methods
  # to self.implicit_cursor.  This cursor will be opened on the first
  # exec() on self.  If the database has no concept of cursors, then
  # simply perform the operation.


class Cursor:
  def close(self):
    "Close the cursor now (rather than whenever __del__ is called)."
    pass

  def exec(self, operation, params=None):
    """\
Execute (prepare) a database operation (query or command).  Parameters may
be provided (as a tuple) and will be bound to variables in the operation."""
    pass

  def execagain(self, params=None):
    """\
Rebind parameters to the current operation and execute again.  If
no parameters are passed, execute the same operation with the same
parameters again."""
    pass

  def fetchone(self):
    "Fetch the next row of a query result, returning a single tuple."
    pass

  def fetchmany(self):
    """\
Fetch the next set of rows of a query result, returning as a list of
tuples. An empty list is returned when no more rows are available. The
cursor's arraysize determines the number of rows attempted to be fetched."""
    pass

  def fetchall(self):
    "Fetch all rows of a query result, returning as a list of tuples."
    pass

  def describe(self):
    """\
Describe the row returned by the last prepared query. Format is a
7-element tuple giving (name, type_code, display_size, internal_size,
precision, scale, null_ok)."""
    pass

  def arraysize(self, size=None):
    "Get or set the arraysize (number of rows to fetch) for fetchmany()."
    pass

  def setbufsize(self, size, col=None):
    "Set a column buffer size for fetches of large columns (e.g. LONG)."
    pass


error = "<modname>.error"



=================
DB-SIG  - SIG on Tabular Databases in Python

send messages to: db-sig@python.org
administrivia to: db-sig-request@python.org
=================