glue.ligolw.table

While the ligolw module provides classes and parser support for reading and writing LIGO Light Weight XML documents, this module supplements that code with classes and parsers that add intelligence to the in-RAM document representation.

In particular, the document tree associated with a Table element is enhanced. During parsing, the Stream element in this module converts the character data contained within it into a list of objects. The list contains one object for each row of the table, and the objects' attributes are the names of the table's columns. When the document is written out again, the Stream element serializes the row objects back into character data.

The Table element exports a list-like interface to the rows. The Column elements also provide list-like access to the values in the corresponding columns of the table.

Version: git id 8cbd1b7187ce3ed9a825d6ed11cc432f3cfde9a5

Date: 2017-12-05 15:29:36 +0000

Author: Kipp Cannon <kipp.cannon@ligo.org>

get_table(xmldoc, name)

source code

Scan xmldoc for a Table element named name. Raises ValueError if not exactly 1 such table is found.

NOTE: if a Table sub-class has its .tableName attribute set, then its .get_table() class method can be used instead. This is true for all Table classes in the glue.ligolw.lsctables module, and it is recommended to always use the .get_table() class method of those classes to retrieve those standard tables instead of calling this function and passing the .tableName attribute. The example below shows both techniques.

Example:

>>> import ligolw
>>> import lsctables
>>> xmldoc = ligolw.Document()
>>> xmldoc.appendChild(ligolw.LIGO_LW()).appendChild(lsctables.New(lsctables.SnglInspiralTable))
[]
>>> # find table with this function
>>> sngl_inspiral_table = get_table(xmldoc, lsctables.SnglInspiralTable.tableName)
>>> # find table with .get_table() class method (preferred)
>>> sngl_inspiral_table = lsctables.SnglInspiralTable.get_table(xmldoc)

See also the .get_table() class method of the Table class.

reassign_ids(elem)

source code

Recurses over all Table elements below elem whose next_id attributes are not None, and uses the .get_next_id() method of each of those Tables to generate and assign new IDs to their rows. The modifications are recorded, and finally all ID attributes in all rows of all tables are updated to fix cross references to the modified IDs.

This function is used by ligolw_add to assign new IDs to rows when merging documents in order to make sure there are no ID collisions. Using this function in this way requires the .get_next_id() methods of all Table elements to yield unused IDs, otherwise collisions will result anyway. See the .sync_next_id() method of the Table class for a way to initialize the .next_id attributes so that collisions will not occur.

Example:

>>> import ligolw
>>> import lsctables
>>> xmldoc = ligolw.Document()
>>> xmldoc.appendChild(ligolw.LIGO_LW()).appendChild(lsctables.New(lsctables.SnglInspiralTable))
[]
>>> reassign_ids(xmldoc)

use_in(ContentHandler)

source code

Modify ContentHandler, a sub-class of glue.ligolw.LIGOLWContentHandler, to cause it to use the Table, Column, and Stream classes defined in this module when parsing XML documents.

Example:

>>> from glue.ligolw import ligolw
>>> class LIGOLWContentHandler(ligolw.LIGOLWContentHandler):
...     pass
...
>>> use_in(LIGOLWContentHandler)
<class 'glue.ligolw.table.LIGOLWContentHandler'>

Module table

get_table(xmldoc, name)

reassign_ids(elem)

use_in(ContentHandler)