1.5.9.2 The Table Object

class Database( [ignoreCreateAndDrop=False])

If ignoreCreateAndDrop is True then the table is not created or dropped when the database methods createTables() or dropTables() are called.

addColumn( column): Add a web.database.object column object to the table.

addMultiple( name, foreignTable): Add a column named by the string name to the table. The column will be used to reference multiple rows from the table named by the string foreignTable. The foreign table will have a corresponding addSingle() entry for this table.

addSingle( name, foreignTable): Add a column named by the string name to the table. The column will contain a reference to a row in the foreign table named by the string foreignTable. The foreign table will have a corresponding addMultiple() entry for this table.

addRelated( name, foreignTable): Add a column named by the string name to the table. The column will contain a reference to any number of rows in the foreign table named by the string foreignTable. The foreign table will have a corresponding addRelated() entry for this table and will contain a reference to any number of rows from this table.

columns( ): Return a tuple of the column names of the table.

keys( ): Return a tuple containing the keys of the rows in the table.

values( ): Return a tuple containing the web.database.object.Row objects in the table.

items( ): Return a tuple containing 2-tuples of (str(key), value) pairs where the key is the web.database.object.Row key and the value is the web.database.object.Row object.

has_key( key): Returns True if the table has a row with a key key, False otherwise

dict( [rows=False]): Return the rows in the table as a dictionary indexed by string representations of their keys. If rows is True then each Row object is made into a dictionary of column name : value pairs, except for single, multiple and related joins columns, since this could result in circular references.

create( ): Create the table. Note: Usually this is done automatically through the createTables() method of the Database class.

drop( ): Drop the table. Note: Usually this is done automatically through the dropTables() method of the Database class.

exists( ): Return True if the table exists in the database, False otherwise.

rowExists( rowid): Return True if the row specified by the integer rowid exists in the table, False otherwise.

columnExists( name): Return True if the column name exists in the table, False otherwise.

insert( [all=None], [**params]): Insert a new row to the table. Either specify the values as a dictionary as the all parameter with the column names as keys and the values as the column values or specify each column value pair in the form colName=value,. You must use one of the two methods. Note: all is a reserved word so there should be no confusion between using the two notations.

delete( rowid): Delete a row by specifying the rowid of the row with the rowid parameter. Warning: This method does not delete corresponding rows in foreign tables. If you delete a row there will still be references to it in other tables if it contains any colums added by addMultiple or addSingle() for example. These should be deleted manually. XXX is this a bug or a useful feature?

row( rowid): Return the Row with the rowid specified by the rowid parameter.

__getitem__( key): Return the Row with the key specified by the key parameter. Note: Certain objects such as class objects cannot be used as dictionary keys. All keys are converted to strings using the str() function so any object to be used as a key must return a unique value when its __str__() is called. This also means that

select( where[,order=None][,rowids=False]): Select the Row objects specified by the where parameter in the oreder specified by the order parameter. If rowids is True then a list of rowids is returned rather than a dictionary of Row objects.

form( [action=''][, method='post'][, stickyData={}][, enctype='multipart/form-data'][, submit='Submit'][, modeDict={'mode':'mode', 'table':'table', 'submode':'submode'}][, submode='add']): Return an empty web.form Form object to allow data to be added to the table.

max( column[, rows='post']): Returns the highest value of column in the current table. If rows is True returns a list of rows which have the maximum value of column.

min( column[, rows='post']): Returns the lowest value of column in the current table. If rows is True returns a list of rows which have the minimum value of column.

column

Magic attribute which allows you to build SQL where clauses in natural Python language. For example:

>>> print database['table'].column['column1'] == 23 \
... && database['table'].column['column2'] < datetime.date(2004,12,04)
column1=23 AND column2<'2004-12-24'

See the "Building Queries" section for more information.

Table rows can be accessed using the row() method or by using the __getitem__() method as follows. To return the row with where the key is surname and you want the row with surname 'Smith' from the 'Person' table of the database wrapped by database you would do this:

>>> database['Person']['Smith']
<web.database.object.Row from 'Person' Table, rowid=1, firstName='John', surname='Smith'>

See About this document... for information on suggesting changes.