Usage

Loading a document

There are two functions that perform this task. For streams there is DocumentIO.load(), for simple strings there is DocumentIO.loads().

Each function does three things:

• read the document text
• deserialize it properly (using propert configuration for parsing floating point numbers).
• check the document by inspecting the format and validating it against a built-in schema

If you use this API there is no need to double-check the contents of the document you’ve got. It’s going to match the description of the schema.

Example of reading something from a file:

with open("bundle.json", "rt") as stream:
    format, bundle = DocumentIO.load(stream)
    print "Loaded document type: %s" % format

The error path is a little more complex. Loading can fail at the following levels:

1. You can get an IOError while reading from the stream
2. You can get a ValueError or JsonDecodeError depending on which version of simplejson you have while processing the text
3. You can get a DocumentFormatError when the format string is missing or has an unknown value
4. You can get a ValidationError when the document does not match the format

Saving a document

There is just one function for saving a document DocumentIO.dump(). It will always validate the document before saving it so there is little chance of producing invalid files this way.

Currently this function uses a hardcoded human-readable profile. If you care about representation efficiency use a compressed storage such as gzip.GzipFile.

Example of writing a bundle to a file:

with open("bundle.json", "wt") as stream:
    bundle = {"format": "Dashboard Bundle Format 1.0"}
    DocumentIO.dump(stream, bundle)

Checking document for errors

To validate document for correctness you can use DocumentIO.check().

Note

Most of the time you don’t need to validate a document explicitly. It is automatically validated when loading and saving.

Converting older documents to current format

To convert a document to the most recent format you can use DocumentEvolution.evolve_document(). It is safe to call this method on any valid document. If you just need to check if the document is using the most recent format call DocumentEvolution.is_latest().