MivotAnnotations

class pyvo.mivot.writer.MivotAnnotations[source]

Bases: object

This module provides a class to construct, validate, and insert MIVOT blocks into VOTable files. The MIVOT block, represented as an XML structure, is used for data model annotations in the IVOA ecosystem.

The main features are:

  • Construct the MIVOT block step-by-step with various components.

  • Validate the MIVOT block against the MIVOT XML schema (if xmlschema is installed).

  • Embed the MIVOT block into an existing VOTable file.

The MIVOT block is constructed as a string to maintain compatibility with the Astropy API.

Attributes:
suggested_space_frames: string array, class attribute

A warning is emitted if a frame not in this list is used to build a space frame. This list matches https://www.ivoa.net/rdf/refframe/2022-02-22/refframe.html.

suggested_ref_positions: string array, class attribute

A warning is emitted if a reference position not in this list is used to build a space or a time frame.

suggested_time_frames: string array, class attribute

A warning is emitted if a frame not in this list is used to build a space frame. This list matches https://www.ivoa.net/rdf/timescale/2019-03-15/timescale.html.

Attributes Summary

mivot_block

Getter for the whole MIVOT block.

Methods Summary

add_globals(globals_instance)

Add an <INSTANCE> block to the <GLOBALS> block.

add_model(model_name, *[, vodml_url])

Add a <MODEL> element to the MIVOT block.

add_templates(templates_instance)

Add an <INSTANCE> element to the <TEMPLATES> block.

build_mivot_block(*[, templates_id, ...])

Build a complete MIVOT block from the declared components and validates it against the MIVOT XML schema.

check_xml()

Validate the MIVOT block against the MIVOT XML schema v1.0.

insert_into_votable(votable_file[, override])

Insert the MIVOT block into a VOTable.

set_report(status, message)

Set the <REPORT> element of the MIVOT block.

Attributes Documentation

mivot_block

Getter for the whole MIVOT block.

Returns:
str

Complete MIVOT block as a string.

Methods Documentation

add_globals(globals_instance)[source]

Add an <INSTANCE> block to the <GLOBALS> block.

Parameters:
globals_instancestr or MivotInstance

The <INSTANCE> block to be added.

Raises:
MappingError

If globals_instance is neither a string nor an instance of MivotInstance.

add_model(model_name, *, vodml_url=None)[source]

Add a <MODEL> element to the MIVOT block.

Parameters:
model_namestr

The short name of the model.

vodml_urlstr, optional

The URL of the VO-DML file associated with the model.

add_templates(templates_instance)[source]

Add an <INSTANCE> element to the <TEMPLATES> block.

Parameters:
templates_instancestr or MivotInstance

The <INSTANCE> element to be added.

Raises:
MappingError

If templates_instance is neither a string nor an instance of MivotInstance.

build_mivot_block(*, templates_id=None, schema_check=True)[source]

Build a complete MIVOT block from the declared components and validates it against the MIVOT XML schema.

Parameters:
templates_idstr, optional

The ID to associate with the <TEMPLATES> block. Defaults to None.

schema_checkboolean, optional

Skip the XSD validation if False (use to make test working in local mode).

Raises:
Any exceptions raised during XML validation are not caught and must
be handled by the caller.
check_xml()[source]

Validate the MIVOT block against the MIVOT XML schema v1.0.

Raises:
MappingError

If the validation fails.

Notes

The schema (mivot 1.0) is loaded from a local file to avoid dependency on a remote service.

insert_into_votable(votable_file, override=False)[source]

Insert the MIVOT block into a VOTable.

Parameters:
votable_filestr or VOTableFile

The VOTable to be annotated, either as a file path or a VOTableFile instance.

overridebool

If True, overrides any existing annotations in the VOTable.

Raises:
MappingError

If a mapping block already exists and override is False.

set_report(status, message)[source]

Set the <REPORT> element of the MIVOT block.

Parameters:
statusbool

The status of the annotation process. True for success, False for failure.

messagestr

The message associated with the REPORT.

Notes

If status is False, all components of the MIVOT block except MODEL and REPORT are cleared.