Package glue :: Package ligolw :: Module dbtables :: Class DBTable
[hide private]
[frames] | no frames]

Class DBTable

source code

     object --+                
              |                
 ligolw.Element --+            
                  |            
ligolw.EmptyElement --+        
                      |        
           ligolw.Table --+    
                          |    
             object --+   |    
                      |   |    
                   list --+    
                          |    
                table.Table --+
                              |
                             DBTable
Known Subclasses:

A special version of the Table class using an SQL database for storage. Many of the features of the Table class are not available here, but instead the user can use SQL to query the table's contents.

The constraints attribute can be set to a text string that will be added to the table's CREATE statement where constraints go, for example you might wish to set this to "PRIMARY KEY (event_id)" for a table with an event_id column.

Note: because the table is stored in an SQL database, the use of this class imposes the restriction that table names be unique within a document.

Also note that at the present time there is really only proper support for the pre-defined tables in the lsctables module. It is possible to load unrecognized tables into a database from LIGO Light Weight XML files, but without developer intervention there is no way to indicate the constraints that should be imposed on the columns, for example which columns should be used as primary keys and so on. This can result in poor query performance. It is also possible to extract a database' contents to a LIGO Light Weight XML file even when the database contains unrecognized tables, but without developer intervention the column types will be guessed using a generic mapping of SQL types to LIGO Light Weight types.

Each instance of this class must be connected to a database. The (Python DBAPI 2.0 compatible) connection object is passed to the class via the connection parameter at instance creation time.

Example:

>>> import sqlite3
>>> connection = sqlite3.connection()
>>> tbl = dbtables.DBTable(AttributesImpl({u"Name": u"process:table"}), connection = connection)

A custom content handler must be created in order to pass the connection keyword argument to the DBTable class when instances are created, since the default content handler does not do this. See the use_in() function defined in this module for information on how to create such a content handler

If a custom glue.ligolw.Table subclass is defined in glue.ligolw.lsctables whose name matches the name of the DBTable being constructed, the lsctables class is added to the list of parent classes. This allows the lsctables class' methods to be used with the DBTable instances but not all of the methods will necessarily work with the database-backed version of the class. Your mileage may vary.

Nested Classes [hide private]

Inherited from table.Table: RowType, TableName

Instance Methods [hide private]
new empty list
__init__(self, *args, **kwargs)
Initialize
source code
 
__iter__(self)
iter(x)
source code
 
__len__(self)
len(x)
source code
 
_append(self, row)
Standard .append() method.
source code
 
_end_of_columns(self)
Called during parsing to indicate that the last Column child element has been added.
source code
 
_end_of_rows(self)
Called during parsing to indicate that the last row has been added.
source code
 
_remapping_append(self, row)
Replacement for the standard .append() method.
source code
 
_row_from_cols(self, values)
Given an iterable of values in the order of columns in the database, construct and return a row object.
source code
 
append(self, row)
Standard .append() method.
source code
 
applyKeyMapping(self)
Used as the second half of the key reassignment algorithm.
source code
 
copy(self, *args, **kwargs)
This method is not implemented.
source code
 
maxrowid(self) source code
 
row_from_cols(self, values)
Given an iterable of values in the order of columns in the database, construct and return a row object.
source code
 
sync_next_id(self)
Determines the highest-numbered ID in this table, and sets the table's .next_id attribute to the next highest ID in sequence.
source code
 
unlink(self)
Break internal references within the document tree rooted on this element to promote garbage collection.
source code

Inherited from table.Table: appendColumn, appendRow, endElement, getColumnByName, removeChild, updateKeyMapping

Inherited from table.Table (private): _update_column_info, _verifyChildren

Inherited from ligolw.EmptyElement: appendData

Inherited from ligolw.Element: appendChild, end_tag, getAttribute, getChildrenByAttributes, getElements, getElementsByTagName, hasAttribute, insertBefore, removeAttribute, replaceChild, setAttribute, start_tag, write

Inherited from list: __add__, __contains__, __delitem__, __delslice__, __eq__, __ge__, __getattribute__, __getitem__, __getslice__, __gt__, __iadd__, __imul__, __le__, __lt__, __mul__, __ne__, __repr__, __reversed__, __rmul__, __setitem__, __setslice__, __sizeof__, count, extend, index, insert, pop, remove, reverse, sort

Inherited from object: __delattr__, __format__, __reduce__, __reduce_ex__, __setattr__, __str__, __subclasshook__

Class Methods [hide private]

Inherited from table.Table: CheckElement, CheckProperties, getTablesByName, get_next_id, get_table, reset_next_id, set_next_id

Inherited from ligolw.Element: validattributes

Static Methods [hide private]
a new object with type S, a subtype of T
__new__(cls, *args, **kwargs) source code
Class Variables [hide private]

Inherited from table.Table: constraints, how_to_index, interncolumns, loadcolumns, next_id, validcolumns

Inherited from ligolw.Table: tagName, validchildren

Inherited from list: __hash__

Properties [hide private]

Inherited from table.Table: Name

Inherited from ligolw.Table: Type

Inherited from object: __class__

Method Details [hide private]

__init__(self, *args, **kwargs)
(Constructor)

source code 

Initialize

Returns: new empty list
Overrides: object.__init__
(inherited documentation)

__iter__(self)

source code 

iter(x)

Overrides: list.__iter__
(inherited documentation)

__len__(self)
(Length operator)

source code 

len(x)

Overrides: list.__len__
(inherited documentation)

__new__(cls, *args, **kwargs)
Static Method

source code 
Returns: a new object with type S, a subtype of T
Overrides: object.__new__
(inherited documentation)

_append(self, row)

source code 

Standard .append() method. This method is for intended for internal use only.

_end_of_columns(self)

source code 

Called during parsing to indicate that the last Column child element has been added. Subclasses can override this to perform any special action that should occur following the addition of the last Column element.

Overrides: table.Table._end_of_columns
(inherited documentation)

_end_of_rows(self)

source code 

Called during parsing to indicate that the last row has been added. Subclasses can override this to perform any special action that should occur following the addition of the last row.

Overrides: table.Table._end_of_rows
(inherited documentation)

_remapping_append(self, row)

source code 

Replacement for the standard .append() method. This version performs on the fly row ID reassignment, and so also performs the function of the updateKeyMapping() method. SQLite does not permit the PRIMARY KEY of a row to be modified, so it needs to be done prior to insertion. This method is intended for internal use only.

_row_from_cols(self, values)

source code 

Given an iterable of values in the order of columns in the database, construct and return a row object. This is a convenience function for turning the results of database queries into Python objects.

append(self, row)

source code 

Standard .append() method. This method is for intended for internal use only.

Overrides: list.append

applyKeyMapping(self)

source code 

Used as the second half of the key reassignment algorithm. Loops over each row in the table, replacing references to old row keys with the new values from the _idmap_ table.

Overrides: table.Table.applyKeyMapping

copy(self, *args, **kwargs)

source code 

This method is not implemented. See glue.ligolw.table.Table for more information.

Overrides: table.Table.copy

row_from_cols(self, values)

source code 

Given an iterable of values in the order of columns in the database, construct and return a row object. This is a convenience function for turning the results of database queries into Python objects.

sync_next_id(self)

source code 

Determines the highest-numbered ID in this table, and sets the table's .next_id attribute to the next highest ID in sequence. If the .next_id attribute is already set to a value greater than the highest value found, then it is left unmodified. The return value is the ID identified by this method. If the table's .next_id attribute is None, then this function is a no-op.

Note that tables of the same name typically share a common .next_id attribute (it is a class attribute, not an attribute of each instance) so that IDs can be generated that are unique across all tables in the document. Running sync_next_id() on all the tables in a document that are of the same type will have the effect of setting the ID to the next ID higher than any ID in any of those tables.

Example:

>>> import lsctables
>>> tbl = lsctables.New(lsctables.ProcessTable)
>>> print(tbl.sync_next_id())
process:process_id:0
Overrides: table.Table.sync_next_id
(inherited documentation)

unlink(self)

source code 

Break internal references within the document tree rooted on this element to promote garbage collection.

Overrides: ligolw.Element.unlink
(inherited documentation)