This is the database package. Contained within are several separate modules:

4.1.1 mysql and pgsql

The user-visible API is the same in both access modules, so I have combined them into one section here to save space.

LoadDatabase(database, connection_data)

Loads a database (given by database) from a *SQL server specified by either the global Host, User, and Passwd or by the optional argument connection_data

NewDatabase(name, connection_data)

Creates a new database (name) and raises an exception if it cannot be done. connection_data is an optional dictionary holding the information needed to connect to the database server (i.e., it has keys host, user, and passwd).

ListDatabases(connection_data)

Returns a list of strings containing the names of all available databases on the server. connection_data is again the optional information needed to connect to the database server.

DropDatabase(database, connection_data)

Drops the database given by the string database from the database server optionally described by connection_data. New in release 0.6.0.

class DatabaseClass

This class encapsulates database properties and operations into a clean, object-oriented representation. Has variables name, the database name; Host, User, and Passwd: a copy of the global connection information; and Tables, a list of objects of class Table which represent the tables in the database.

DatabaseClass.__init__(name, env_data)

The constructor called by user code to generate a DatabaseClass object. name is the name of the database which to rerpesent; env_data is a dictionary with keys host, user, and passwd which holds a copy of the global connection data.

DatabaseClass.GetName()

Returns the name of the database.

DatabaseClass.AddTable(table_vars)

Adds a table to the database. table_vars is a dictionary of the following format:

{'name':table-name,
'fields':[{'name':first-field, 'type':field1-type} ... ]
}

where table-name is replaced by the actual table name, fields holds as many field descriptions as you wish, first-field is the field name, and field-type is any valid SQL type, complete with qualifiers.

DatabaseClass.Query(query_string)

This is the method to use when you cannot use any of the pre-built interface to complete your task. It executes the SQL query represented by query_string and returns any results. Some parsing of results list may be necessary.

DatabaseClass.Drop(table)

Drops a table (which must nominally be a member of the parent database) rerpesented by table, an object of class Table. Deletes self.[table.name].

DatabaseClass.Join(tables, fields, join_fields)

Executes a left outer join (arguably the most useful) on the tables specified in tables. It is worth noting here that there can be a maximum of three tables, though that may be expanded in the future. fields is an ordered list (or tuple) of the fields to be selected. join_fields is a list of the fields on which to join, containing the same number of fields as there are tables.

class Table

This is the table analogue of DatabaseClass; it encapsulates table properties and operations. Objects of this class possess variables name, the table name; parent, a copy of the parent DatabaseClass object; the connection information from parent; fields, a dictionary holding field names and types; and the variables field_count (the number of fields) and field_order, a list representing the order of fields in the table.

Table.__init__(name, parent)

The constructor for objects of class Table. Do not worry about this; it is called automatically by DatabaseClass for each table.

Table.Contents()

Returns the contents of the table as a list of dictionaries. Each dictionary represents a single row and has keys corresponding to the names of the table's fields.

Table.Insert(row)

Inserts a row (represented as a dictionary) into the table. row is a dictionary with keys equivalent to the names of the fields into which data will be inserted. The values of row are naturally the aforementioned data.

Table.Delete(search_value, field)

Deletes a row from the table. search_value is the key to search on; field is the field in which to search. When search_value is found in field, the containing row is deleted.

Table.Update(search_value, field, new_record)

Updates a record in the parent table which contains search_value in field. This target record will be updated with the key-value pairs in new_record.

Table.Search(search_values, fields, stype)

Searches for one or more value(s) in one or more field(s) using either the equality operator ('=') or the LIKE SQL statement. search_values is either a string or list of strings for which to search. fields is a string or list of strings representing the field(s) in which to search. stype is an optional argument specifying whether to use an equality search; valid values are 'equal' and None.

Returns a list of dictionaries representing rows found; returns an empty list if no matches are found.

Error(mesg, error_log)

Error handler. Writes mesg to file error_log.

4.1.2 persistence

Herein is covered the WebPython persist-to-database mechanism, contained within the module persistence.

It is worth mentioning at this point that all persistence tables (i.e., tables used to store persistent objects) should be declared in a very particular format. As follows:

{'name':'any-name',
'fields': [
	{'name':'ident', 'type':'varchar(100) primary key'},
	{'name':'creation_date', 'type':'datetime'},
	{'name':'last_modified', 'type':'datetime'},
	{'name':'object', 'type':'text'}
]}

where 'any-name' of course is anything you may wish to call the table.

The fields of this table are relatively self-explanatory, with ident being a unique key by which to retrieve object. It should be noted that currently, modifying persistent objects is not yet supported.

Store(table, obj_identifier, obj)

Inserts obj (any Python object or data structure) into persistence table table with identifying key obj_identifier (any alphanumeric string, inclusive of extra characters).

Load(table, obj_identifier)

Attempts to load an object (identified by obj_identifier) from persistence table table. Throws exception db_exceptions.QueryError on nonexistence of obj_identifer in table and exception db_exceptions.DatabaseError on database malfunction or inconsistency.

Delete(table, obj_identifer)

Attempts to delete the object identified by obj_identifer from table. Throws exception db_exceptions.DatabaseError on failure.

4.1.3 db_exceptions

This module holds the database-related exceptions which a developer may make use of in their code.

class DatabaseError(Exception)

General-purpose database exception. Raised in many different scenarios; usually means something has gone wrong with a user-initiated action in the database.

class MissingTableException(Exception)

Raised when a table expected to exist is missing.

class InsertError(Exception)

Raised when an insertion into a table fails.

class BadFieldError(Exception)

Raised when a user-supplied field does not exist in a given table.

class BadErrorFile(Exception)

Raised when a specified error log cannot be used (due to permissions, non-existent filename, etc.).

class QueryError(Exception)

Raised when a query is malformed or otherwise invalid.