Document Manipulation APIs

class linaro_dashboard_bundle.io.DocumentIO

Document IO encapsulates various (current and past) file formats and provides a single entry point for analyzing a document, determining its format and validating the contents.

classmethod check(doc)

Check document format and validate the contents against a schema.

Discussion :

The document is validated against a set of known versions and their schemas.

Return value:

String identifying document format

Exceptions :
linaro_json.ValidationError

When the document does not match the appropriate schema.

linaro_dashboard_bundle.errors.DocumentFormatError

When the document format is not in the known set of formats.

classmethod dump(stream, doc, human_readable=True, sort_keys=False)

Check and save a JSON document to the specified stream

Discussion :

The document is validated against a set of known formats and schemas and saved to the specified stream.

If human_readable is True the serialized stream is meant to be read by humans, it will have newlines, proper indentation and spaces after commas and colons. This option is enabled by default.

If sort_keys is True then resulting JSON object will have sorted keys in all objects. This is useful for predictable format but is not recommended if you want to load-modify-save an existing document without altering it’s general structure. This option is not enabled by default.

Return value:

None

Exceptions :
Other exceptions

This method can also raise exceptions raised by DocumentIO.check()

classmethod dumps(doc, human_readable=True, sort_keys=False)

Check and save a JSON document as string

Discussion :

The document is validated against a set of known formats and schemas and saved to a string.

If human_readable is True the serialized value is meant to be read by humans, it will have newlines, proper indentation and spaces after commas and colons. This option is enabled by default.

If sort_keys is True then resulting JSON object will have sorted keys in all objects. This is useful for predictable format but is not recommended if you want to load-modify-save an existing document without altering it’s general structure. This option is not enabled by default.

Return value:

JSON document as string

Exceptions :
Other exceptions

This method can also raise exceptions raised by DocumentIO.check()

classmethod load(stream, retain_order=True)

Load and check a JSON document from the specified stream

Discussion :

The document is read from the stream and parsed as JSON text. It is then validated against a set of known formats and their schemas.

Return value:

Tuple (format, document) where format is the string identifying document format and document is a JSON document loaded from the passed text. If retain_order is True then the resulting objects are composed of ordered dictionaries. This mode is slightly slower and consumes more memory.

Exceptions :
ValueError

When the text does not represent a correct JSON document.

Other exceptions

This method can also raise exceptions raised by DocumentIO.check()

classmethod loads(text, retain_order=True)

Same as load() but reads data from a string

exception linaro_dashboard_bundle.errors.DocumentFormatError(format)

Exception raised when document format is not in the set of known values.

You can access the :format: property to inspect the format that was found in the document

class linaro_dashboard_bundle.evolution.DocumentEvolution

Document Evolution encapsulates format changes between subsequent document format versions. This is useful when your code is designed to handle single, for example the most recent, format of the document but would like to interact with any previous format transparently.

classmethod evolve_document(doc, one_step=False)

Evolve document to the latest known version.

Runs an in-place evolution of the document doc converting it to more recent versions. The conversion process is lossless.

Parameters:
  • doc (JSON document, usually python dictionary) – document (changed in place)
  • one_step – if true then just one step of the evolution path is taken before exiting.
Return type:

None

classmethod is_latest(doc)

Check if the document is at the latest known version

Project Versions

Previous topic

Code Documentation

Next topic

Version History

This Page