gavo.adql.annotations module

Adding field infos to columns and other objects in an ADQL parse tree.

When we want to generate VOTables from ADQL queries, we must know types, units, ucds, and the like, and we need to know STC information for all columns in a query.

To do that, we traverse the parse tree postorder looking for nodes that have an addFieldInfos method (note the plural). These then get called, which causes one of the classes in adql.fieldinfos to be constructed and assigned to the node’s fieldInfos attribute. The source for these infos is either an AnnotationContext (and thus typically the user-supplied retrieveFieldInfos function) or derived annotations. These are computed by the nodes themselves, using their addFieldInfo (singular!) method.

class gavo.adql.annotations.AnnotationContext(retrieveFieldInfos, equivalencePolicy=<gavo.stc.eq.EquivalencePolicy object>)

Bases: object

An context object for the annotation process.

It is constructed with a FieldInfoGetter implementation and an equivalence policy for STC objects.

It has errors and warnings attributes consisting of user-exposable error strings accrued during the annotation process.

The annotation context also manages the namespaces for column reference resolution. It maintains a stack of getters; is is maintained using the customResolver context manager.

withTables, if passed, must be a sequence of already annotated WithQuery objects.

Finally, the annotation context provides a ancestors attribute that, at any time, gives a list of the current node’s ancestor nodes.

addWithTable(withTable)

adds a nodes.WithQuery to use in column resolution.

withTable must already be annotated for this to work.

customResolver(getter)

a context manager temporarily installing a different field info getter.

getFieldInfo(colName, tableName)

returns the (colName, fieldInfo) for colName within tableName in the current context.

gavo.adql.annotations.annotate(node, context)

adds annotations to all nodes wanting some.

This is done by a postorder traversal of the tree, identifying all annotable objects.

context can be an AnnotationContext instance. You can also just pass in a adql.FieldInfoGetter instance. In that case, annotation runs with the default stc equivalence policy.

The function returns the context used in any case.

gavo.adql.annotations.dumpFieldInfoedTree(tree)

dumps an ADQL parse tree, giving the computed annotations.

For debugging.

gavo.adql.annotations.optimize(node)

iterates postorder over the tree below, calling optimize(stack) methods where they exist.