File Read and Write through ndm_io
Top Level Interface ndm_io
The ndm_io module is the single unified interface to handle the read and write functionalities for the data in XML or KVN format. It reads the data, converts it to a string, determines the format and calls the lower level XML and KML modules to handle the input string. These modules then automatically determine the data type (e.g. CDM or OMM) and process the file accordingly.
While the nominal use is
reading the data file through the NdmIo.from_path(), it is also possible to read from
a string (with the contents of the file) through NdmIo.from_string() and also from bytes
through NdmIo.from_bytes().
Similarly, writing an output XML or KVN file through NdmIo.to_file() is probably the most common operation.
This requires the object tree, the data format NDMFileFormats and the output file
path as well as optional arguments, if available. For example, for the case of XML, the URL for the schema
can be provided through the keywords schema_location or no_namespace_schema_location.
NdmIo().to_file(ndm, NDMFileFormats.XML, xml_write_path,
no_namespace_schema_location="http://cwe.ccsds.org/moims/docs/MOIMS-NAV/Schemas/ndmxml-1.0-master.xsd")
It is still possible to generate a string output of the file contents through NdmIo.to_string().
NdmIo acts as a thin interface and the actual output of the data is handled by the lower level
NdmKvnIo.from_path() or NdmXmlIo.from_path() classes.
Lower Level Modules ndm_xml_io and ndm_kvn_io
The actual parsing and output of the data is carried out in the XML and KVN specific modules. If the user is
sure of the input data type, these modules can be used directly. The interface is the same as the NdmIo class;
a KVN or XML file would be parsed via NdmKvnIo.from_path() or NdmXmlIo.from_path(), skipping the file
type specification. Once the data is read, the data type is automatically determined and the file is read into the
object tree.
The XML data read and write is simple and is handled by the underlying xsdata`engine. The `ndm_xml_io module simply provides a simple I/O interface and makes sure the ndm data type is handled correctly, which is not always read properly.
On the other hand, for the parsing of the KVN data, a template object tree is created using the nested class structure of the object tree and is then populated by the contents of the data. As such, the KVN parser is agnostic, in the sense that it does not know how a CDM KVN file looks like, but, inspecting the object tree derived from the XSD file, it finds out how to read it. Therefore there are no individual parsers for each file type, but a single “parsing engine”. There are a lot of exceptions to the standard KVN input (such as data lines in AEM and OEM files), which requires these special cases to be handled separately.
KVN output is possible through NdmKvnIo.to_file() or NdmKvnIo.to_string() methods, to a file or to
a string, respectively. Similar to the parsing engine, there is an output engine that prepares the output string. For
many output types this simply outputs the data in the NDM object in standard KVN format. However, many exceptions exist
(such as OEM, AEM and TDM files) and they have to be handled separately.
Reference/API
CCSDS Navigation Data Messages XML File I/O.
- class ccsds_ndm.ndm_io.NdmIo
Unified I/O Model for CCSDS Navigation Data Message (NDM) input and output.
- from_bytes(ndm_data_source)
Reads the input bytes array to extract contents to an object of correct type.
- from_path(input_file_path)
Reads the file to extract contents to an object of correct type.
- Parameters
input_file_path (Path or AnyStr) – Path of the file to be read (path or pathlike accepted)
- Returns
NDM Object tree from the file contents
- Return type
- from_string(ndm_data_source)
Reads the input string to extract contents to an object of correct type.
- Parameters
ndm_data_source (str) – input string data
- Raises
NotImplementedError – JSON input not implemented in CCSDS NDM Standard yet.
- Returns
NDM Object tree from the file contents
- Return type
- to_file(ndm_obj, data_format, xml_write_file_path, **kwargs)
Convert and return the given object tree as output file.
- Parameters
ndm_obj – input object tree
data_format (NDMFileFormats) – output data format (KVN, XML or JSON)
xml_write_file_path (Path or AnyStr) – Path of the file to be written (path or pathlike accepted)
kwargs – other keywords to be passed on to individual writers (e.g. schema_location and no_namespace_schema_location for XML output)
- to_string(ndm_obj, data_format, **kwargs)
Convert and return the given object tree as xml string.
- Parameters
ndm_obj – input object tree
data_format (NDMFileFormats) – output data format (KVN, XML or JSON)
kwargs – other keywords to be passed on to individual writers (e.g. schema_location and no_namespace_schema_location for XML output)
- Returns
given object tree as string in the requested format
- Return type
CCSDS Navigation Data Messages XML File I/O.
- class ccsds_ndm.ndm_xml_io.NdmXmlIo
Unified I/O Model for XML input and output.
- from_bytes(xml_source)
Reads the input bytes array to extract contents to an object of correct type.
- from_path(xml_read_file_path)
Reads the file to extract contents to an object of correct type.
- Parameters
xml_read_file_path (Path or AnyStr) – Path of the XML file to be read
- Returns
Object tree from the file contents
- Return type
- from_string(xml_source)
Reads the input string to extract contents to an object of correct type.
- to_file(ndm_obj, xml_write_file_path, schema_location=None, no_namespace_schema_location=None)
Convert and return the given object tree as xml file.
- to_string(ndm_obj, schema_location=None, no_namespace_schema_location=None)
Convert and return the given object tree as xml string.
CCSDS Navigation Data Messages KVN File I/O.
- class ccsds_ndm.ndm_kvn_io.NdmKvnIo
Unified I/O Model for KVN input and output.
- from_path(kvn_read_file_path)
Reads the file to extract contents to an object of correct type.
- Parameters
kvn_read_file_path (Path) – Path of the KVN file to be read
- Returns
Object tree from the file contents
- Return type
- from_string(kvn_source)
Reads the input string to extract contents to an object of correct type.
- to_file(ndm_obj, kvn_write_file_path)
Convert and return the given object tree as xml file.
- Parameters
ndm_obj – input object tree
kvn_write_file_path (Path) – Path of the XML file to be written
- to_string(ndm_obj)
Convert and return the given object tree as xml string.
- Parameters
ndm_obj – input object tree
- Returns
given object tree as KVN string
- Return type
- Raises
NotImplementedError – Combined NDM input for KVN not implemented in CCSDS NDM Standard.