Connection API
James William Pye
pgsql at jwp.name
Sat Jan 26 18:46:55 UTC 2008
I've changed how I'm defining the connection APIs. Before I tried to formalize
it in a DocBook document. However, this has proven tedious, and somewhat
inhibiting for more rapid development.
So, I added a module to pg_greentrunk which defines classes and functions that
represent the attributes of a connection. Each class has doc-strings describing
the interface of the attribute and whether it's a property or constructor.
pg_greentrunk also includes an aptly named script, pg_greentrunk, that simply
runs help() on the module to show the APIs and their documentation.
Currently, this is in CVS, so if you want to look at what's there so far, you'll
have to checkout head of the 'ip' module.
Attached is the output of that script.
-------------- next part --------------
Help on module postgresql.protocol.greentrunk.connection in postgresql.protocol.greentrunk:
NAME
postgresql.protocol.greentrunk.connection
FILE
/src/org/pgfoundry/python/pkg/prefix/python1/lib/python/pg_greentrunk-1.0dev-py2.5.egg/postgresql/protocol/greentrunk/connection.py
DESCRIPTION
pg_greentrunk is a Python API to the PostgreSQL RDBMS. It is designed to take
full advantage of the database elements provided by PostgreSQL to provide the
Python programmer with substantial convenience.
This module is used to define the GreenTrunk API. The attributes of the module
represent the attributes on a connection object. Most of the time, when a class
is defined, it represents the interface of the object that's created by calling
the method or callable attribute on the connection. Implementations are only
required to take the parameters described by the ``__init__`` method of the
class and return an object that provides the interface described by the class.
Connection objects aren't required to be a part in any special class hierarchy.
Merely, the Python protocol described here must be supported. For instance, a
module object could be a connection to the database.
CLASSES
__builtin__.object
cursor
path
proc
query
cquery
statement
settings
type
version_info
xact
class cquery(query)
| A cquery object is a query object whose query is cached using using a finite
| map of query strings to query objects. Once instantiated, the query object
| is held until the connection is closed.
|
| Usually, ``query`` is the more appropriate attribute to make use of as it
| allows program to leverage garbage collection to dispose of unused statements.
|
| Method resolution order:
| cquery
| query
| __builtin__.object
|
| Methods inherited from query:
|
| __call__(self, *args)
| Execute the prepared statement with the given arguments as parameters. If
| the query returns rows, a cursor object should be returned, otherwise a
| resulthandle object.
|
| Usage:
| >>> con.query("SELECT table_name FROM information_schema.tables WHERE
| table_schema = $1")('public')
| <cursor object>
|
| __del__(self)
| Close the prepared statement on the server as the only reference to its
| existence is gone.
|
| __init__(self, sql, *default_args)
| Create an object referencing a prepared statement that provides an
| interface to the prepared statement.
|
| Given a single SQL statement, and optional default arguments, create the
| prepared statement. The object returned is the interface to the
| prepared statement.
|
| __invert__(self)
| Shorthand for a call to the first() method without any arguments.
| Useful for resolving static queries.
|
| Usage:
| >>> ~con.query("INSERT INTO ttable VALUES ('value')")
| 1
| >>> ~con.query("SELECT 'somestring'")
| 'somestring'
|
| close(self)
| Close the prepraed statement releasing resources associated with it.
|
| first(self, *args)
| Execute the prepared statement with the given arguments as parameters. If
| the query returns rows with multiple columns, return the first row. If the
| query returns rows with a single column, return the first column in the
| first row.
|
| Usage:
| >>> con.query("SELECT * FROM ttable WHERE key = $1").first("somekey")
| ('somekey', 'somevalue')
|
| prepare(self)
| Prepare the already instantiated query for use. This method would only be
| used if the query closed.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from query:
|
| __dict__
| dictionary for instance variables (if defined)
|
| __weakref__
| list of weak references to the object (if defined)
class cursor(__builtin__.object)
| A cursor object is an interface to a sequence of tuples(rows). A result set.
| Cursors publish a file like interface for reading tuples from the database.
|
| Methods defined here:
|
| __getitem__(self, idx)
| Get the rows at the given absolute position.
|
| __init__(self, portal_id)
| Create a reference object to an already created cursor. In this case,
| losing the cursor object does *not* result in the cursor being closed.
| Explicitly referenced cursors must be explicitly closed for their
| resources to be released. This is in contrast to cursor objects created
| from query invocation, which will closed after __del__ is called on the
| object.
|
| __next__(self)
| Get the next item tuple in the cursor.
|
| close(self)
| Close the cursor to release its resources.
|
| next = __next__(self)
|
| read(self, quantity=-1)
| Read the specified number of tuples and return them in a list.
| This advances the cursor's position.
|
| scroll(self, rows)
| Set the cursor's position relative to the current position.
| Negative numbers can be used to scroll backwards.
|
| seek(self, offset, whence=0)
| Set the cursor's position to the given offset with respect to the
| whence parameter.
| 0 - being absolute.
| 1 - being relative.
| 2 - begin absolute from end.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables (if defined)
|
| __weakref__
| list of weak references to the object (if defined)
class path(__builtin__.object)
| path is a property providing access to a structured version of search_path.
|
| >>> con.path
| ['public', 'pg_catalog']
|
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables (if defined)
|
| __weakref__
| list of weak references to the object (if defined)
class proc(__builtin__.object)
| A proc object is an interface to a stored procedure.
|
| Methods defined here:
|
| __call__(self, *args, **kw)
| Execute the procedure with the given arguments. If keyword arguments are
| passed they must be mapped to the argument whose name matches the key. If
| any positional arguments are given, they must fill in any gaps created by
| the filled keyword arguments. If too few or too many arguments are given,
| a TypeError must be raised. If a keyword argument is passed where the
| procudure does not have a corresponding argument name, then, likewise, a
| TypeError must be raised.
|
| __init__(self, procid)
| Create a reference to a stored procedure on the database. The given
| identifier can be either an Oid or a valid regprocedure string pointing at
| the desired function.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables (if defined)
|
| __weakref__
| list of weak references to the object (if defined)
class query(__builtin__.object)
| A query object is an interface to a prepared statement.
|
| Methods defined here:
|
| __call__(self, *args)
| Execute the prepared statement with the given arguments as parameters. If
| the query returns rows, a cursor object should be returned, otherwise a
| resulthandle object.
|
| Usage:
| >>> con.query("SELECT table_name FROM information_schema.tables WHERE
| table_schema = $1")('public')
| <cursor object>
|
| __del__(self)
| Close the prepared statement on the server as the only reference to its
| existence is gone.
|
| __init__(self, sql, *default_args)
| Create an object referencing a prepared statement that provides an
| interface to the prepared statement.
|
| Given a single SQL statement, and optional default arguments, create the
| prepared statement. The object returned is the interface to the
| prepared statement.
|
| __invert__(self)
| Shorthand for a call to the first() method without any arguments.
| Useful for resolving static queries.
|
| Usage:
| >>> ~con.query("INSERT INTO ttable VALUES ('value')")
| 1
| >>> ~con.query("SELECT 'somestring'")
| 'somestring'
|
| close(self)
| Close the prepraed statement releasing resources associated with it.
|
| first(self, *args)
| Execute the prepared statement with the given arguments as parameters. If
| the query returns rows with multiple columns, return the first row. If the
| query returns rows with a single column, return the first column in the
| first row.
|
| Usage:
| >>> con.query("SELECT * FROM ttable WHERE key = $1").first("somekey")
| ('somekey', 'somevalue')
|
| prepare(self)
| Prepare the already instantiated query for use. This method would only be
| used if the query closed.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables (if defined)
|
| __weakref__
| list of weak references to the object (if defined)
class settings(__builtin__.object)
| A mapping interface to the session's settings. This dictionary-like object
| provides a direct interface to SHOW/SET commands. Identifiers and values need
| not be quoted specially as the implementation must do that work for the user.
|
| Methods defined here:
|
| __getitem__(self, key)
| Return the setting corresponding to the given key. The result should be
| consistent with what the SHOW command returns. If the key does not exist,
| raise a KeyError.
|
| __setitem__(self, key, value)
| Set the setting with the given key to the given value. The action should
| be consisten with the effect of the SET command.
|
| get(self, key, default=None)
| Get the setting with the corresponding key. If the setting does not exist,
| return the default(defaults to None).
|
| items(self)
| Return an iterator to all of the setting value pairs.
|
| iteritems(self)
| Return an iterator to all of the setting value pairs.
| This method is provided for compatibility with dictionary objects.
|
| iterkeys(self)
| Return an iterator to all of the settings' keys.
| This method is provided for compatibility with dictionary objects.
|
| itervalues(self)
| Return an iterator to all of the settings' values.
| This method is provided for compatibility with dictionary objects.
|
| keys(self)
| Return an iterator to all of the settings' keys.
|
| update(self, mapping)
| For each key-value pair, incur the effect of the __setitem__ method.
|
| values(self)
| Return an iterator to all of the settings' values.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables (if defined)
|
| __weakref__
| list of weak references to the object (if defined)
class statement(query)
| A query object that was prepared on the server side. The distinction between
| this and a regular query is that it must be explicitly closed if it is no
| longer desired, and it is instantiated using the statement identifier as
| opposed to the SQL statement itself.
|
| Method resolution order:
| statement
| query
| __builtin__.object
|
| Methods defined here:
|
| __del__(self)
| Nothing happens if a server prepared statement reference is lost.
|
| __init__(self, statement_id)
| Create a ``query`` object from the given statement identifier.
|
| ----------------------------------------------------------------------
| Methods inherited from query:
|
| __call__(self, *args)
| Execute the prepared statement with the given arguments as parameters. If
| the query returns rows, a cursor object should be returned, otherwise a
| resulthandle object.
|
| Usage:
| >>> con.query("SELECT table_name FROM information_schema.tables WHERE
| table_schema = $1")('public')
| <cursor object>
|
| __invert__(self)
| Shorthand for a call to the first() method without any arguments.
| Useful for resolving static queries.
|
| Usage:
| >>> ~con.query("INSERT INTO ttable VALUES ('value')")
| 1
| >>> ~con.query("SELECT 'somestring'")
| 'somestring'
|
| close(self)
| Close the prepraed statement releasing resources associated with it.
|
| first(self, *args)
| Execute the prepared statement with the given arguments as parameters. If
| the query returns rows with multiple columns, return the first row. If the
| query returns rows with a single column, return the first column in the
| first row.
|
| Usage:
| >>> con.query("SELECT * FROM ttable WHERE key = $1").first("somekey")
| ('somekey', 'somevalue')
|
| prepare(self)
| Prepare the already instantiated query for use. This method would only be
| used if the query closed.
|
| ----------------------------------------------------------------------
| Data descriptors inherited from query:
|
| __dict__
| dictionary for instance variables (if defined)
|
| __weakref__
| list of weak references to the object (if defined)
class type(__builtin__.object)
| type is a property providing the name of the database type. 'PostgreSQL'
| would be the usual case. However, other "kinds" of Postgres exist in the
| wild. Greenplum for example.
|
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables (if defined)
|
| __weakref__
| list of weak references to the object (if defined)
class version_info(__builtin__.object)
| version_info is a version tuple of the database software similar Python's
| sys.version_info. It should be an instance of
| ``postgresql.utility.version.one``.
|
| >>> con.version_info
| (8, 1, 3, '', 0)
|
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables (if defined)
|
| __weakref__
| list of weak references to the object (if defined)
class xact(__builtin__.object)
| A xact object is the connection's transaction manager. It is already
| instantiated for every connection. It keeps the state of the transaction and
| provides methods for managing the state thereof.
|
| Normal usage would merely entail the use of with-statement:
|
| with con.xact:
| ...
|
| If no prior starts or blocks have been opened, that results in a transaction
| block being started.
|
| Methods defined here:
|
| __call__(self, gid=None, isolation=None, readonly=None)
| Configure the transaction block using the given arguments.
|
| The ``isolation`` keyword must be a character string stating the ISOLATION
| LEVEL of the transaction block.
|
| The ``readonly`` keyword must be a boolean signifying whether the
| transaction should be started in read-only mode.
|
| The ``gid`` keyword and first positional argument states the transaction
| identifier to be used for a prepared transaction. When this option is not
| None, the transaction will not issue a COMMIT on an invocation to the
| ``commit`` method. Rather, a PREPARE TRANSACTION statement will be issued
| with the ``gid`` parameter.
|
| __context__(self)
| Return self
|
| __enter__ = start(self)
|
| __exit__(self, typ, obj, tb)
| Commit the transaction, or abort if the given exception is not None. If
| the transaction level is greater than one, then the savepoint
| corresponding to the current level will be released or rolled back in
| cases of an exception.
|
| If an exception was raised, then the return value must indicate the need
| to further raise the exception, unless the exception is an
| AbortTransaction. In which case, the transaction will be rolled back
| accordingly, but the exception will not be raised.
|
| abort = rollback(self)
|
| begin = start(self)
|
| checkpoint(self)
| Commit and start a transaction block or savepoint. Not to be confused with
| the effect of the CHECKPOINT command.
|
| commit(self)
| Commit the transaction block, release a savepoint, or prepare the
| transaction for commit. If the number of running transactions is greater
| than one, then the corresponding savepoint is released. If no savepoints
| are set and the transaction is configured with a 'gid', then the
| transaction is prepared instead of committed, otherwise the transaction is
| simply committed.
|
| restart(self)
| Abort and start the transaction or savepoint.
|
| rollback(self)
| Abort the current transaction or rollback to the last started savepoint.
| ``rollback`` and ``abort`` are synonyms.
|
| start(self)
| Start a transaction block. If a transaction block has already been
| started, set a savepoint.
| ``start``, ``begin``, and ``__enter__`` are synonyms.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables (if defined)
|
| __weakref__
| list of weak references to the object (if defined)
FUNCTIONS
execute(sql)
Execute an arbitrary block of SQL. Always returns None and raises an
exception on error.
DATA
__loader__ = <zipimporter object "/src/org/pgfoundry/python/p....0dev-...
More information about the Python-general
mailing list