exporting.org

Exporting gegede objects.

A GeGeDe exporter is a Python module following the interface described here. The conversion process is broken up into a number of steps, some optional, in order to give the user (or client code) some finer grained control.

Required Exporter Module Methods

A GeGeDe exporter module must supply a method convert(geom) which is called like:

from MyConverterModule import convert
geom = ...
obj = convert(geom)

The geom object is an instance of gegede.construct.Geometry. The convert() method should return an object holding any transient information related to the conversion. This object will be treated as opaque by GeGeDe.

Optional Exporter Module Methods

Validating exported object

The module may provide an optional method validate_object to validate the transient object obj returned as part of its conversion process. It is called like:

from MyConverterModule import validate_object
validate_object(obj)

The method should raise ValueError if the object obj is not valid.

Producing an output file

The main job of an exporter module is to produce a file from the information held in the geom object. This method is optional. If the module implements such functionality it should provide a output() method which would be called like:

from MyConverterModule import output
filename = ...
output(obj, filename)

Validating the output file

It is often useful to be able to write an invalid file in order to test the nature of its validity in other tools. It is also useful to encode tests for known failure modes. This requires an explicit “hook” to be called after writing the output file and one which the user may want control over its inclusion or exclusion. For that is validate_file()

from MyConverterModule import validate_file
validate_file(obj, filename)

The same transient object obj is passed in as it may be useful in comparing the written representation.

String representation

An exporter may provide the optional dumps() method to return a string representation of the obj object returned by its convert() method.

obj = myexporter.convert(geom)
text = myexporter.dumps(obj)
print text

API

An instance of the class gegede.export.Exporter can be created with the name of an exporter (relative to gegede.export or a fully qualified module name). It then provides a simple API expressing the above conventions.

Some considerations

The gegede.construct.Geometry data object’s store member contains a per-section collection of all objects created under that section. Most exporter’s work by walking through this store and converting each object into whatever the target form is. Object values that are held as collections.namedtuple or pint.Quantity will likely need special consideration when serializing. For a simple example see the module gegede.export.pod.