gavo.votable.common module

Common definitions for the GAVO VOTable modules.

exception gavo.votable.common.BadVOTableData(msg, val, fieldName, hint=None)

Bases: VOTableError

Raised when something is wrong with a value being inserted into a VOTable.

exception gavo.votable.common.BadVOTableLiteral(type, literal, hint=None, originalException=None, name=None)

Bases: VOTableError

Raised when a literal in a VOTable is invalid.

class gavo.votable.common.NULLFlags(nFields)

Bases: object

an interface to the BINARY2 NULL flags.

Construct it with the number of fields, then use

deserialize(toDecode)

returns a sequence of booleans giving for each element in a row if there’s a NULL there.

getFromFile(file)

returns a sequence of booleans giving for each element in a row if there’s a NULL there.

masks = [128, 64, 32, 16, 8, 4, 2, 1]

serialize(nullMap)

returns null bytes for nullMap, which is a sequence of booleans with Trues where the field is NULL.

It is an error to pass in nullMaps with lengths!=nFields.

serializeFromRow(row)

returns null bytes for a row, which is a sequence of values. Everything that’s None is flagged as NULL.

exception gavo.votable.common.VOTableError(msg: str = '', hint: Optional[str] = None)

Bases: Error

The base class of VOTable-related errors.

exception gavo.votable.common.VOTableParseError(msg: str = '', hint: Optional[str] = None)

Bases: VOTableError

Raised when something is grossly wrong with the document structure.

Note that the message passed already contains line and position. I’d like to have them in separate attributes, but the expat library mashes them up. iterparse.getParseError is the canonical way of obtaining these when you have no positional information.

gavo.votable.common.getLength(arraysize)

returns the number of elements expected for an array described with the VOTable attribute arraysize.

A 1-element array isn’t told apart from a scalar here. Both return 1. For variable-length arrays, this returns None.

Bad arraysize specs will give ValueErrors (perhaps not always with the most helpful messages).

>>> getLength(None)
1
>>> getLength("*")
>>> getLength("5")
5
>>> getLength("5x*")
>>> getLength("5x6*")
>>> getLength("7x5x6")
210
>>> getLength("7*x5x6")
Traceback (most recent call last):
ValueError: invalid literal for int() with base 10: '7*'

gavo.votable.common.getLoopifier(field)

returns a function to map code over arrays.

This is used by *XtypeEncoderCode functions below, and for now only deals with 1D arrays of xtyped things, which right now means 2D arrays of votable arrays.

This will return a callable accepting a list of lines (the xtype decoder for an elementary thing), nor None if the array is too complex.

gavo.votable.common.getShape(datatype, arraysize)

returns a numpy-compatible shape for a VOTable arraysize.

For variable length 1D arrays, this returns None; for 2+D arrays, the last dimension is currently replaced by 1. Which doesn’t sound smart.

gavo.votable.common.getXtypeDecoderCode(field)

returns code that turns generic VOTable arrays into special internal representations based on xtype.

This returns a list of lines or an empty list if no known xtype is found. The code is executed with the unpacked array seen as val, and it should set val to the special representation.

This will handle 1D arrays of xtyped things but nothing more deeply nested. More deeply nested structures will be left alone (which is ok for round-tripping but probably will fail when DaCHS components want to process stuff).

gavo.votable.common.getXtypeEncoderCode(field)

returns code that turns special internal representations for xtyped fields to what’s serialised in VOTables.

For None or unknown xtypes, this will return an empty list. Otherwise, it expects the value in a local variable val and will leave the transformed value there.

This is currently only called for char and float arrays, as no xtypes are defined for other types. If that changes, you’ll have to change the *_enc modules.

This will handle 1D arrays of xtyped things but nothing more deeply nested. More deeply nested structures will be left alone (which will only work under very special conditions and yield ugly error messages otherwise).

gavo.votable.common.hasVarLength(arraysize)

returns True if the VOTable arraysize denotes a variable-length array.

This is, of course, False for None arraysizes,

gavo.votable.common.indentList(lines, indent)

prepens indent to all elements in lines.

gavo.votable.common.isMultiDim(arraysize)

returns True if the VOTable arraysize denotes a >1D-array.

gavo.votable.common.qmreplace(exc)

a dumb handler for decoder errors.

This is like python’s “replace” handler except that we’ll always return question marks rather than ufffd. The latter makes sense in a unicode environment, but we need this for VOTable chars, and there that’s just a nuisance.

gavo.votable.common.validateTDComplex(val)

gavo.votable.common.validateVOTInt(val)

raise an error if val is not a legal int for VOTables.

Actually, this is for tabledata, and after the relaxed 1.3 rules, we allow the empty string (“NULL”), too.