gavo.utils.serializers module

A framework for pluggable serialisation of (python) values.

This module collects a set of basic (looking primarily towards VOTables) serialiser factories. These are just functions receiving AnnotatedColumn objects and returning either None (“not responsible”) or a function taking a value and returning a string. They may change the AnnotatedColumn objects, for instance, when an MJD (float) becomes a datetime.

These factories are registered in ValueMapperFactoryRegistry classes; the one used for “normal” VOTables is the defaultMFRegistry.

Most factories are created here. However, some depend on advance functionality not available here; they will be registered on import of the respective modules (for instance, stc).

In DaCHS, a second such factory registry is created in web.htmltable.

class gavo.utils.serializers.AnnotatedColumn(column, votCast=None)

Bases: object

A collection of annotations for a column.

ColumnAnntotations are constructed with columns and retain a reference to them (“original”).

In addition, they provide a getitem/setitem interface to a dictionary that contains “digested” information on the column. This dictionary serves as an accumulator for information useful during the serialization process.

The main reason for this class is that Columns are supposed to be immutable; thus, any ephemeral information needs to be kept in a different place. In particular, the mapper factories receive such annotations.

As a special service to coerce internal tables to external standards, you can pass a votCast dictionary to AnnotatedColumn. Give any key/value pairs in there to override what AnnotatedColumn guesses or infers. This is used to force the sometimes a bit funky SCS/SIAP types to standard values.

The castMapperFactory enabled by default checks for the presence of a castFunction in an AnnotatedColumn. If it is there, it will be used for mapping the values, so this is another thing you can have in votCast.

The SerManager tries to obtain votCasts from a such-named attribute on the table passed in.

Though of course clients can access original, the mapping facets should only be accessed through getitem/setitem since they may be updated wrt what is in original.

Attributes available via the setitem/getitem interface include:

• nullvalue – a suitable nullvalue for this column, if provided by the column’s values or otherwise obtained

• name – a name for the column

• dbtype – the column’s database type

• xtype – the column’s xtype (e.g., “timestamp”)

• datatype, arraysize – a VOTable type for the column

• displayHint – a parsed display hint

• note – a reference to a table not (these get entered by SerManager)

• ucd, utype, unit, description – as for column

• id – a string suitable as XML id (externally managed)

• votablewrite would evaluate min and max (but right now nothing adds this)

get(key, default=None)

class gavo.utils.serializers.ValueMapperFactoryRegistry(factories=None)

Bases: object

An object clients can ask for functions fixing up values for encoding.

A mapper factory is just a function that takes an AnnotatedColumn instance. It must return either None (for “I don’t know how to make a function for this combination these column properties”) or a callable that takes a value of the given type and returns a mapped value.

To add a mapper, call registerFactory. To find a mapper for a set of column properties, call getMapper – column properties should be an instance of AnnotatedColumn, but for now a dictionary with the right keys should mostly do.

Mapper factories are tried in the reverse order of registration, and the first that returns non-None wins, i.e., you should register more general factories first. If no registered mapper declares itself responsible, getMapper returns an identity function. If you want to catch such a situation, you can use something like res = vmfr.getMapper(…); if res is utils.identity …

appendFactory(factory)

clone()

returns a clone of the factory.

This is a copy, i.e., factories added will not change the original.

getFactories()

returns the list of factories.

This is not a copy. It may be manipulated to remove or add factories.

getMapper(colDesc)

returns a mapper for values with the python value instance, according to colDesc.

This method may change colDesc.

We do a linear search here, so you shouldn’t call this function too frequently.

registerFactory(factory)

gavo.utils.serializers.getMapperRegistry()

returns a copy of the default value mapper registry.

gavo.utils.serializers.registerDefaultMF(factory)