gavo.formats.votablewrite module

Generating VOTables from internal data representations.

This is glue code to the more generic GAVO votable library. In particular, it governs the application of base.SerManagers and their column descriptions (which are what is passed around as colDescs in this module to come up with VOTable FIELDs and the corresponding values.

You should access this module through formats.votable.

exception gavo.formats.votablewrite.Error(msg: str = '', hint: Optional[str] = None)

Bases: Error

class gavo.formats.votablewrite.VOTableContext(mfRegistry=<gavo.utils.serializers.ValueMapperFactoryRegistry object>, tablecoding='binary', version=None, acquireSamples=True, suppressNamespace=False, overflowElement=None)

Bases: IdManagerMixin

A context object for writing VOTables.

The constructor arguments work as keyword arguments to getAsVOTable. Some other high-level functions accept finished contexts.

This class provides management for unique ID attributes, the value mapper registry, and possibly additional services for writing VOTables.

VOTableContexts optionally take

• a value mapper registry (by default, valuemappers.defaultMFRegistry)

• the tablecoding (currently, td, binary, or binary2)

• version=(1,1) to order a 1.1-version VOTable, (1,2) for 1.2. (default is now 1.4).

• acquireSamples=False to suppress reading some rows to get samples for each column

• suppressNamespace=False to leave out a namespace declaration (mostly convenient for debugging)

• overflowElement (see votable.tablewriter.OverflowElement)

There’s also an attribute produceVODML that will automatically be set for VOTable 1.5; you can set it to true manually, but the resulting VOTables will probably be invalid.

If VO-DML processing is enabled, the context also manages models declared; that’s the modelsUsed dictionary, mapping prefix -> dm.Model instances

activeContainer(container)

a context manager to be called by VOTable builders when they open a new TABLE or RESOURCE.

addID(rdEl, votEl)

adds an ID attribute to votEl if rdEl has an id managed by self.

Also, if a ref has been noted for rdEl, a ref attribute is being added, too. This is a special hack for params and coosys; and I suspect we shouldn’t go beyond that.

addVODMLMaterial(stuff)

adds VODML annotation to this VOTable.

Note that it will only be rendered if produceVODML is true (in general, for target versions >1.4).

addVODMLPrefix(prefix)

arranges the DM with prefix to be included in modelsUsed.

buildingFromTable(table)

a context manager to control code that works on a DaCHS table.

property curDMAttr

returns the V.ATTRIBUTE element currently worked on.

This will raise an IndexError if not ATTRIBUTE is being built at the moment.

property currentTable

the DaCHS table object from which things are currently built.

If no builder has declared a table being built (using buildingFromTable), it’s a value error.

getEnclosingContainer()

returns the innermost container element the builders have declared.

getEnclosingResource()

returns the xmlstan element of the resource currently built.

This returns a ValueError if the context isn’t aware of a resource being built.

(This depends builders using activeContainer)

getEnclosingTable()

returns the xmlstan element of the table currently built.

This returns a ValueError if the context isn’t aware of a table being built.

(This depends builders using activeContainer)

makeTable(table)

returns xmlstan for a table.

This is exposed as a method of context as the dm subpackage needs it, but I don’t want to import formats there (yet).

This may go away as I fix the interdependence of dm, votable, and format.

pushRefFor(rdEl, refVal)

orders refVal to be set as ref on rdEl’s VOTable representation if such a thing is being serialised.

This currently is more a hack for PARAMs with COOSYS than something that should be really used; if this were to become a general pattern, we should work out a way to assign the ref if rdEl’s representation already is in the tree…

settingAttribute(dmAttr)

a context manager controlling the curDMAttr attribute.

This is used by the DM annotators that sometimes need to directly manipulate the ATTRIBUTE element.

gavo.formats.votablewrite.defineField(ctx, element, colDesc)

adds attributes and children to element from colDesc.

element can be a V.FIELD or a V.PARAM instance and is changed in place.

This function returns None to remind people we’re changing in place here.

gavo.formats.votablewrite.format(data, outputFile, **ctxargs)

gavo.formats.votablewrite.getAsVOTable(data, ctx=None, **kwargs)

returns a string containing a VOTable representation of data.

kwargs can be constructor arguments for VOTableContext.

gavo.formats.votablewrite.makeFieldFromColumn(ctx, colType, rscCol)

returns a VOTable colType for a rscdef column-type thing.

This function lets you make PARAM and FIELD elements (colType) from column or param instances.

gavo.formats.votablewrite.makeResource(ctx, data)

returns a Resource node for the rsc.Data instance data.

gavo.formats.votablewrite.makeTable(ctx, table, isMeta=False)

returns a Table node for the table.Table instance table.

gavo.formats.votablewrite.makeVOTable(data, ctx=None, **kwargs)

returns a votable.V.VOTABLE object representing data.

data can be an rsc.Data or an rsc.Table. data can be a data or a table instance, tablecoding any key in votable.tableEncoders.

You may pass a VOTableContext object; if you don’t a context with all defaults will be used.

A deprecated alternative is to directly pass VOTableContext constructor arguments as additional keyword arguments. Don’t do this, though, we’ll probably remove the option to do so at some point.

You will usually pass the result to votable.write. The object returned contains DelayedTables, i.e., most of the content will only be realized at render time.

gavo.formats.votablewrite.writeAsVOTable(data, outputFile, ctx=None, **kwargs)

writes data to the outputFile.

data can be a table or Data item.

ctx can be a VOTableContext instance; alternatively, VOTableContext constructor arguments can be passed in as kwargs.