Data Types

Provides functionality for validation of the data-types specified for odML

class odml.dtypes.DType

The DType class enumerates all data types supported by odML.

boolean = 'boolean'

date = 'date'

datetime = 'datetime'

float = 'float'

int = 'int'

person = 'person'

string = 'string'

text = 'text'

time = 'time'

url = 'url'

odml.dtypes.bool_get(string)

Handles an input string value and escapes None and empty collections and provides the default boolean value in these cases. String values “true”, “1”, True, “t” are interpreted as boolean True, string values “false”, “0”, False, “f” are interpreted as boolean False. A ValueError is raised if the input value cannot be interpreted as boolean.

Parameters:string – value to convert to boolean. Returns:boolean value.

odml.dtypes.bool_set(string)

Handles an input string value and escapes None and empty collections and provides the default boolean value in these cases. String values “true”, “1”, True, “t” are interpreted as boolean True, string values “false”, “0”, False, “f” are interpreted as boolean False. A ValueError is raised if the input value cannot be interpreted as boolean.

Parameters:string – value to convert to boolean. Returns:boolean value.

odml.dtypes.boolean_get(string)

Handles an input string value and escapes None and empty collections and provides the default boolean value in these cases. String values “true”, “1”, True, “t” are interpreted as boolean True, string values “false”, “0”, False, “f” are interpreted as boolean False. A ValueError is raised if the input value cannot be interpreted as boolean.

Parameters:string – value to convert to boolean. Returns:boolean value.

odml.dtypes.boolean_set(string)

Handles an input string value and escapes None and empty collections and provides the default boolean value in these cases. String values “true”, “1”, True, “t” are interpreted as boolean True, string values “false”, “0”, False, “f” are interpreted as boolean False. A ValueError is raised if the input value cannot be interpreted as boolean.

Parameters:string – value to convert to boolean. Returns:boolean value.

odml.dtypes.date_get(string)

Checks an input string against the required date format and converts it to a date object with the default format. If string is empty the default value for date is returned.

Parameters:string – string value to convert to date. Returns:date object.

odml.dtypes.date_set(string)

Checks an input string against the required date format and converts it to a date object with the default format. If string is empty the default value for date is returned.

Parameters:string – string value to convert to date. Returns:date object.

odml.dtypes.datetime_get(string)

Checks an input string against the required datetime format and converts it to a datetime object with the default format. If string is empty the default value for datetime is returned.

Parameters:string – string value to convert to datetime. Returns:datetime object.

odml.dtypes.datetime_set(string)

Checks an input string against the required datetime format and converts it to a datetime object with the default format. If string is empty the default value for datetime is returned.

Parameters:string – string value to convert to datetime. Returns:datetime object.

odml.dtypes.default_values(dtype)

Returns the default value for a provided odml data type.

Parameters:dtype – odml.DType or string corresponding to an odml data type. Returns:default value for an identified odml data type or empty string.

odml.dtypes.float_get(string)

Converts an input string to a float value. If string is empty the default value for float is returned.

Parameters:string – string value to convert to int. Returns:Float value.

odml.dtypes.get(string, dtype=None)

Converts string to the corresponding dtype. The appropriate function is derived from the provided dtype. If no dtype is provided, the string conversion function is used by default.

Parameters:

• string – string to be converted into an odml specific value.
• dtype – odml.DType or string corresponding to an odml data type. If provided it is used to identify the appropriate conversion function.

Returns:

value converted to the appropriate data type.

odml.dtypes.infer_dtype(value)

Tries to identify the odml data type for a provided value.

Parameters:value – single value to infer the odml datatype from. Returns:The identified dtype name. If it cannot be identified, “string” is returned.

odml.dtypes.int_get(string)

Converts an input string to an integer value. If string is empty the default value for int is returned.

Parameters:string – string value to convert to int. Returns:Integer value.

odml.dtypes.set(value, dtype=None)

Serializes a value of type dtype to a unicode string. The appropriate function is derived from the provided dtype.

Parameters:

• value – odml specific value to be converted into a string.
• dtype – odml.DType or string corresponding to an odml data type. If provided it is used to identify the appropriate conversion function.

Returns:

value converted to an appropriately formatted string.

odml.dtypes.str_get(string)

Handles an input string value and escapes None and empty collections.

Parameters:string – value to check for None value or empty collections. Returns:string value.

odml.dtypes.str_set(string)

Handles an input string value and escapes None and empty collections.

Parameters:string – value to check for None value or empty collections. Returns:string value.

odml.dtypes.string_get(string)

Handles an input string value and escapes None and empty collections.

Parameters:string – value to check for None value or empty collections. Returns:string value.

odml.dtypes.string_set(string)

Handles an input string value and escapes None and empty collections.

Parameters:string – value to check for None value or empty collections. Returns:string value.

odml.dtypes.time_get(string)

Checks an input string against the required time format and converts it to a time object with the default format. If string is empty the default value for time is returned.

Parameters:string – string value to convert to time. Returns:time object.

odml.dtypes.time_set(string)

Checks an input string against the required time format and converts it to a time object with the default format. If string is empty the default value for time is returned.

Parameters:string – string value to convert to time. Returns:time object.

odml.dtypes.tuple_get(string, count=None)

Parses a tuple string like “(1024;768)” and return a list of strings with the individual tuple elements.

Parameters:

• string – string to be parsed into odML style tuples.
• count – list of strings.

odml.dtypes.tuple_set(value)

Serializes odml style tuples to a string representation.

Parameters:value – odml style tuple values. Returns:string.

odml.dtypes.valid_type(dtype)

Checks if dtype is a valid odML value data type.

Parameters:dtype – odml.DType or string corresponding to an odml data type. Returns:Boolean.

Tools

Several tools are provided with the odml.tools package.

DictParser

The dict_parser module provides access to the DictWriter and DictReader class. Both handle the conversion of odML documents from and to Python dictionary objects.

class odml.tools.dict_parser.DictReader(show_warnings=True, ignore_errors=False)

A reader to parse dictionaries with odML content into an odml.Document.

error(msg)

If the parsers ignore_errors property is set to False, a ParserException will be raised. Otherwise the message is passed to the parsers warning method.

Parameters:msg – Error message.

is_valid_attribute(attr, fmt)

Checks whether a provided attribute is valid for a provided odml class (Document, Section, Property).

Parameters:

• attr – Python dictionary tag that will be checked if it is a valid attribute for the provided format class.
• fmt – required odml format class format.Document, format.Section or format.Property against which the attribute is checked.

Returns:

the attribute if the attribute is valid, None otherwise.

parse_properties(props_list)

Parses a list of Python dictionary objects containing odML properties to the odml.Property equivalents.

Parameters:props_list – list of Python dictionary objects containing odML properties. Returns:list of parsed odml.Properties

parse_sections(section_list)

Parses a list of Python dictionary objects containing odML sections to the odml.Section equivalents including any subsections and properties.

Parameters:section_list – list of Python dictionary objects containing odML sections. Returns:list of parsed odml.Sections

to_odml(parsed_doc)

Parses a Python dictionary object containing an odML document to an odml.Document. Will raise a ParserException if the Python dictionary does not contain a valid odML document. Also raises an InvalidVersionException if the odML document is of a previous odML format version.

Parameters:parsed_doc – Python dictionary object containing an odML document. Returns:parsed odml.Document.

warn(msg, label='Warning')

Adds a message to the parsers warnings property. If the parsers show_warnings property is set to True, an additional error message will be written to sys.stderr.

Parameters:

• msg – Warning message.
• label – Defined message level, can be ‘Error’ or ‘Warning’. Default is ‘Warning’.

class odml.tools.dict_parser.DictWriter

A writer to parse an odml.Document to a Python dictionary object equivalent.

static get_properties(props_list)

Parses a list of odml.Properties to a Python dict object.

Parameters:props_list – list of odml.Properties. Returns:list of parsed odml.Properties as a single Python dict object.

get_sections(section_list)

Parses a list of odml.Sections to a Python dict object. Will also parse any contained subsections and odml.Properties.

Parameters:section_list – list of odml.Sections. Returns:list of parsed odml.Sections as a single Python dict object.

to_dict(odml_document)

Parses a full odml.Document to a Python dict object. Will also parse any contained odml.Sections, their subsections and odml.Properties.

Parameters:odml_document – an odml.Document. Returns:parsed odml.Document as a Python dict object.

odml.tools.dict_parser.parse_cardinality(vals)

Parses an odml specific cardinality from an input value.

If the input content is valid, returns an appropriate tuple. Returns None if the input is empty or the content cannot be properly parsed.

Parameters:vals – list or tuple Returns:None or 2-tuple

ODMLParser

A generic odML parsing module. It parses odML files and documents. All supported formats can be found in parser_utils.SUPPORTED_PARSERS.

class odml.tools.odmlparser.JSONDateTimeSerializer(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

Required to serialize datetime objects as string objects when working with JSON as output format.

default(o)

Implement this method in a subclass such that it returns a serializable object for o, or calls the base implementation (to raise a TypeError).

For example, to support arbitrary iterators, you could implement default like this:

def default(self, o):
    try:
        iterable = iter(o)
    except TypeError:
        pass
    else:
        return list(iterable)
    # Let the base class default method raise the TypeError
    return JSONEncoder.default(self, o)

encode(o)

Return a JSON string representation of a Python data structure.

>>> from json.encoder import JSONEncoder
>>> JSONEncoder().encode({"foo": ["bar", "baz"]})
'{"foo": ["bar", "baz"]}'

item_separator = ', '

iterencode(o, _one_shot=False)

Encode the given object and yield each string representation as available.

For example:

for chunk in JSONEncoder().iterencode(bigobject):
    mysocket.write(chunk)

key_separator = ': '

class odml.tools.odmlparser.ODMLReader(parser='XML', show_warnings=True)

A reader to parse odML files or strings into odml documents, based on the given data exchange format, like XML, YAML, JSON or RDF.

Usage:

yaml_odml_doc = ODMLReader(parser=’YAML’).from_file(“odml_doc.yaml”) json_odml_doc = ODMLReader(parser=’JSON’).from_file(“odml_doc.json”)

from_file(file, doc_format=None)

Loads an odML document from a file. The ODMLReader.parser specifies the input file format. If the input file is an RDF file, the specific RDF format has to be provided as well. Available RDF formats: ‘xml’, ‘n3’, ‘turtle’, ‘nt’, ‘pretty-xml’, ‘trix’, ‘trig’, ‘nquads’.

Parameters:

• file – file path to load an odML document from.
• doc_format – Required for RDF files only and provides the specific format of an RDF file.

Returns:

parsed odml.Document

from_string(string, doc_format=None)

Loads an odML document from a string object. The ODMLReader.parser specifies the input file format. If the input string contains an RDF format, the specific RDF format has to be provided as well. Available RDF formats: ‘xml’, ‘n3’, ‘turtle’, ‘nt’, ‘pretty-xml’, ‘trix’, ‘trig’, ‘nquads’.

Parameters:

• string – file path to load an odML document from.
• doc_format – Required for RDF files only and provides the specific format of an RDF file.

Returns:

parsed odml.Document

class odml.tools.odmlparser.ODMLWriter(parser='XML')

A generic odML document writer for JSON, XML, YAML and RDF. The output format is specified on init.

Usage:

xml_writer = ODMLWriter(parser=’XML’) xml_writer.write_file(odml_document, filepath)

to_string(odml_document, **kwargs)

Parses an odml.Document to a string in the file format defined in the ODMLWriter.parser property. Supported formats are JSON, YAML and RDF.

Parameters:

• odml_document – odml.Document.
• kwargs – Writer backend keyword arguments e.g. for adding specific stylesheets for xml documents or specifying an RDF format. Refer to the documentation of the available parsers to check which arguments are supported.

Returns:

string containing the content of the odml.Document in the specified format.

write_file(odml_document, filename, **kwargs)

Writes an odml.Document to a file using the format defined in the ODMLWriter.parser property. Supported formats are JSON, XML, YAML and RDF. Will raise a ParserException if the odml.Document is not valid.

Parameters:

• odml_document – odml.Document.
• filename – path and filename of the output file.
• kwargs – Writer backend keyword arguments. Refer to the documentation of the available parsers to check which arguments are supported.

odml.tools.odmlparser.unicode_loader_constructor(_, node)

Constructor for PyYAML to load unicode characters

odml.tools.odmlparser.yaml_time_serializer(dumper, data)

This function is required to serialize datetime.time as string objects when working with YAML as output format.

RDFConverter

The RDF converter module provides conversion of odML documents to RDF and the conversion of odML flavored RDF to odML documents.

class odml.tools.rdf_converter.RDFReader(filename=None, doc_format=None)

A reader to parse odML RDF files or strings into odML documents.

Usage:

file = RDFReader().from_file(“/path_to_input_rdf”, “rdf_format”) file = RDFReader().from_string(“rdf file as string”, “rdf_format”) RDFReader().write_file(“/input_path”, “rdf_format”, “/output_path”)

from_file(filename, doc_format)

from_file loads an odML RDF file and converts all odML documents from this RDF graph into individual odML documents.

Parameters:

• filename – Path of the input odML RDF file.
• doc_format – RDF format of the input odML RDF file.

Returns:

list of converted odML documents

from_string(file, doc_format)

from_string loads an odML RDF file or string object and converts all odML documents from this RDF graph into individual odML documents.

Parameters:

• file – Path of the input odML RDF file or an RDF graph string object.
• doc_format – RDF format of the input odML RDF graph.

Returns:

list of converted odML documents

parse_document(doc_uri)

parse_document parses an odML RDF Document node into an odML Document.

Parameters:doc_uri – RDF URI of an odML Document node within an RDF graph. Returns:dict containing an odML Document

parse_property(prop_uri)

parse_property parses an odML RDF Property node into an odML Property.

Parameters:prop_uri – RDF URI of an odML Property node within an RDF graph. Returns:dict containing an odML Property

parse_section(sec_uri)

parse_section parses an odML RDF Section node into an odML Section.

Parameters:sec_uri – RDF URI of an odML Section node within an RDF graph. Returns:dict containing an odML Section

to_odml()

to_odml converts all odML documents from a common RDF graph into individual odML documents.

Returns:list of converted odML documents

class odml.tools.rdf_converter.RDFWriter(odml_documents, rdf_subclassing=True, custom_subclasses=None)

A writer to parse odML files into RDF documents.

Use the ‘rdf_subclassing’ flag to disable default usage of Section type conversion to RDF Subclasses. Provide a custom Section type to RDF Subclass Name mapping dictionary via the ‘custom_subclasses’ attribute to add custom or overwrite default RDF Subclass mappings.

Usage:

RDFWriter(odml_docs).get_rdf_str(‘turtle’) RDFWriter(odml_docs).write_file(“/output_path”, “rdf_format”)

RDFWriter(odml_docs, rdf_subclassing=False).write_file(“path”, “rdf_format”) RDFWriter(odml_docs, custom_subclasses=custom_dict).write_file(“path”, “rdf_format”)

convert_to_rdf()

convert_to_rdf converts all odML documents to RDF, connects them via a common “Hub” RDF node and returns the created RDF graph.

Returns:An RDF graph.

get_rdf_str(rdf_format='turtle')

Convert the current odML content of the parser to a common RDF graph and return the graph as a string object in the specified RDF format.

Parameters:rdf_format – RDF output format. Default format is ‘turtle’. Available formats: ‘xml’, ‘n3’, ‘turtle’, ‘nt’, ‘pretty-xml’, ‘trix’, ‘trig’, ‘nquads’, ‘json-ld’. Returns:string object

save_document(doc, curr_node=None)

Add the current odML Document to the RDF graph and handle all child elements recursively.

Parameters:

• doc – An odml Document that should be added to the RDF graph.
• curr_node – An RDF node that is used to append the current odml element to the Hub node of the current RDF graph.

save_odml_list(parent_node, rdf_predicate, odml_list)

save_odml_list adds all odml elements in a list to the current parent node and handles all child items via save_element.

Parameters:

• parent_node – current parent node in the RDF graph.
• rdf_predicate – RDF predicate used to add all odml entities to the parent node.
• odml_list – list of odml entities.

save_odml_values(parent_node, rdf_predicate, values)

save_odml_values adds an RDF seq node to the parent RDF node and creates a value leaf node for every odml value.

Parameters:

• parent_node – current parent node in the RDF graph.
• rdf_predicate – RDF predicate used to add the Seq node to the current parent node.
• values – list of odml values.

save_property(prop, curr_node)

Add the current odML Property to the RDF graph and handle all child elements.

Parameters:

• prop – An odml Section that should be added to the RDF graph.
• curr_node – An RDF node that is used to append the current odml element to the current RDF graph.

save_repository_node(parent_node, rdf_predicate, leaf_value)

save_repository_node adds a node with a given repository url to the current graphs terminology node. If the current graph does not yet contain a terminology node, it creates one and attaches the current node to it.

Parameters:

• parent_node – current parent node in the RDF graph.
• rdf_predicate – RDF predicate used to add the terminology to the parent node.
• leaf_value – Value that will be added to the RDF graph.

save_section(sec, curr_node)

Add the current odML Section to the RDF graph and handle all child elements recursively.

Parameters:

• sec – An odml Section that should be added to the RDF graph.
• curr_node – An RDF node that is used to append the current odml element to the current RDF graph.

write_file(filename, rdf_format='turtle')

Convert the current odML content of the parser to a common RDF graph and write the resulting graph to an output file using the provided RDF output format.

Parameters:

• filename –
• rdf_format – RDF output format. Default format is ‘turtle’. Available formats: ‘xml’, ‘n3’, ‘turtle’, ‘nt’, ‘pretty-xml’, ‘trix’, ‘trig’, ‘nquads’, ‘json-ld’.

odml.tools.rdf_converter.load_rdf_subclasses()

load_rdf_subclasses loads odml section types to RDF Section subclass types mappings from a file and returns the mapping as a dictionary. Will return an empty dictionary, if the Subclasses file cannot be loaded.

Returns:Dictionary of the form {‘Section type’: ‘RDF class type’}

odml.tools.rdf_converter.rdflib_version_major()

XMLParser

The xmlparser module provides access to the XMLWriter and XMLReader classes. Both handle the conversion of odML documents from and to XML files and strings.

The parser can be invoked standalone:

python -m odml.tools.xmlparser file.odml

class odml.tools.xmlparser.XMLReader(ignore_errors=False, show_warnings=True, filename=None)

A reader to parse XML files or strings into odML data structures.

Usage:

>>> doc = XMLReader().from_file("file.odml")

check_mandatory_arguments(data, arg_class, tag_name, node)

Checks if a passed attribute is required for a specific odML class. If the attribute is required and not present in the data, the parsers error method is called.

Parameters:

• data – list of mandatory arguments.
• arg_class – odML class corresponding to the content of the parent node.
• tag_name – name of the current XML node.
• node – XML node.

error(msg, elem)

If the parsers ignore_errors property is set to False, a ParserException will be raised. Otherwise the message is passed to the parsers warning method.

Parameters:

• msg – Error message.
• elem – XML node corresponding to the error.

from_file(xml_file)

Parses the datastream from a file like object and return an odML data structure. If the file cannot be parsed, a ParserException is raised.

Parameters:xml_file – file path to an XML input file or file like object. Returns:a parsed odml.Document.

from_string(string)

Parses an XML string and return an odML data structure. If the string cannot be parsed, a ParserException is raised.

Parameters:string – XML string. Returns:a parsed odml.Document.

is_valid_argument(tag_name, arg_class, parent_node, child=None)

Checks if an argument is valid in the scope of a specific odML class. If the attribute is not valid, the parsers error method is called.

Parameters:

• tag_name – string containing the name of the current XML node.
• arg_class – odML class corresponding to the content of the parent node.
• parent_node – the parent XML node.
• child – current XML node.

parse_element(node)

Identifies the odML object corresponding to the current XML node e.g. odml.Document, odml.Section or odml.Property. It will call the parsers method corresponding to the identified odML object e.g. parse_odML, parse_section, parse_property and return the results.

Parameters:node – XML node.

parse_odML(root, fmt)

Parses the content of an XML node into an odml.Document including all subsections and odml.Properties.

Parameters:

• root – XML node
• fmt – odML class corresponding to the content of the XML node.

Returns:

parsed odml.Document

parse_property(root, fmt)

Parses the content of an XML node into an odml.Property.

Parameters:

• root – XML node
• fmt – odML class corresponding to the content of the XML node.

Returns:

parsed odml.Property

parse_section(root, fmt)

Parses the content of an XML node into an odml.Section including all subsections and odml.Properties.

Parameters:

• root – XML node
• fmt – odML class corresponding to the content of the XML node.

Returns:

parsed odml.Section

parse_tag(root, fmt, insert_children=True)

Parse an odml node based on the format description fmt and instantiate the corresponding object. :param root: lxml.etree node containing an odML object or object tree. :param fmt: odML class corresponding to the content of the root node. :param insert_children: Bool value. When True, child elements of the root node

will be parsed to their odML equivalents and appended to the odML document. When False, child elements of the root node will be ignored.

warn(msg, elem)

Adds a message to the parsers warnings property. If the parsers show_warnings property is set to True, an additional error message will be written to sys.stderr.

Parameters:

• msg – Warning message.
• elem – XML node corresponding to the warning.

class odml.tools.xmlparser.XMLWriter(odml_document)

Creates XML nodes storing the information of an odML Document.

header = '<?xml version="1.0" encoding="UTF-8"?>\n<?xml-stylesheet type="text/xsl" href="odmlDocument.xsl"?>\n'

static save_element(curr_el)

Returns an XML node for the odML object curr_el.

Parameters:curr_el – odML object. Supported objects are odml.Document, odml.Section, odml.Property. Returns:parsed XML Node.

write_file(filename, local_style=False, custom_template=None)

write_file saves the XMLWriters odML document to an XML file.

Parameters:

• filename – location and name where the file will be written to.
• local_style – Optional boolean. By default an odML XML document is saved with a default header containing an external stylesheet for viewing with a local or remote server. Set up for local viewing with the ‘odmlview’ command line script. When set to True, the saved XML file will contain a default XSL stylesheet to render the XML file in a web-browser. Note that Chrome requires the ‘.odml’ extension to be registered as “application/xml” in the Mime-type database.
• custom_template – Optional string. Provide a custom XSL template to render the odML XML file in a web-browser. Please note, that the custom XSL template must not be a full XSL stylesheet, but has to start and end with the tag: ‘<xsl:template match=”odML”>[custom]</xsl:template>’.

odml.tools.xmlparser.from_csv(value_string)

Reads a string containing odML values and parses them into a list.

Parameters:value_string – string of odML values. Returns:list of values.

odml.tools.xmlparser.load(filename)

Shortcut function for XMLReader().from_file(filename).

odml.tools.xmlparser.parse_cardinality(val)

Parses an odml specific cardinality from a string.

If the string content is valid, returns an appropriate tuple. Returns None if the string is empty or the content cannot be properly parsed.

Parameters:val – string Returns:None or 2-tuple

odml.tools.xmlparser.to_csv(val)

Modifies odML values for serialization to strings and files.

Parameters:val – odML value. Returns:modified value string.

Convenience converters

Several convenience converters are provided with the odml.tools.converters package.

FormatConverter

The FormatConverter can be used from the command line and within scripts to convert between the different odML formats and update previous file format versions to the most recent one.

A full list of the available odML output formats is available via the CONVERSION_FORMATS constant.

Command line usage: python -m <in_dir> <odml_out_format> [-out <out_dir>] [-r]

Examples: 1) >> python -m odml.tools.converters.format_converter <in_dir> v1_1 -out <out_dir> -r

Convert files from the path <in_dir> to .xml odml version 1.1, writes them to <out_dir> including subdirectories and its files from the input path.

2. >> python -m odml.tools.converters.format_converter <in_dir> odml

   Converts files from path <in_dir> to .odml and writes them to <in_dir_odml> not including subdirectories.

class odml.tools.converters.format_converter.FormatConverter

Class for converting between the different odML file formats.

classmethod convert(args=None)

Enables usage of the argparse for calling convert_dir(…)

Usage: python -m <in_dir> <odml_out_format> [-out <out_dir>] [-r]

Examples:

1. >> python -m odml.tools.converters.format_converter <in_dir> v1_1 -out <out_dir> -r

Convert files from the path <in_dir> to .xml odml version 1.1, writes them to <out_dir> including subdirectories and its files from the input path.

2. >> python -m odml.tools.converters.format_converter <in_dir> odml

Converts files from path <in_dir> to .odml and writes them to <in_dir_odml> not including subdirectories.

Parameters:args – Command line arguments. See usage for details.

classmethod convert_dir(input_dir, output_dir, parse_subdirs, res_format)

Convert files from given input directory to the specified res_format.

Parameters:

• input_dir – Path to input directory
• output_dir – Path for output directory. If None, new directory will be created on the same level as input
• parse_subdirs – If True enable converting files from subdirectories
• res_format –

  Format of output files. Possible choices: “v1_1” (version 1 to version 1.1 xml files)

  ”odml” (version 1.1 .xml to .odml files) “turtle”, “nt” etc. (version 1.1 to RDF files) (full list of RDF serializers in CONVERSION_FORMATS)

VersionConverter

This module provides the class VersionConverter to convert odML XML files from version 1.0 to 1.1.

class odml.tools.converters.version_converter.VersionConverter(filename)

Class for converting odML XML files from version 1.0 to 1.1.

convert(backend='XML')

This method returns the content of the provided file object converted to odML version 1.1 as a string object which is directly consumable by the odml.tools.ODMLReader. Will raise an Exception, if the backend format is not supported.

Parameters:backend – File format of the source file. ‘JSON’, ‘YAML’ and ‘XML’ are supported. Default backend is ‘XML’.

:returns an odML v1.1 document as an XML string

write_to_file(filename, backend='XML')

This method converts the content of the provided converter file object to odML version 1.1 and writes the results to filename.

Parameters:

• filename – Output file.
• backend – Format of the source file, default is XML.

Command line scripts

Several cli convenience scripts are automatically installed and are available from the command line.

odML conversion script

odmlConvert

odmlConvert searches for odML files within a provided SEARCHDIR and converts them to the newest odML format version. Original files will never be overwritten. New files will be written either to a new directory at the current or a specified location.

Usage: odmlconvert [-r] [-o OUT] SEARCHDIR

Arguments:

SEARCHDIR Directory to search for odML files.

Options:

-o OUT	Output directory. Must exist if specified. If not specified, output files will be written to the current directory.
-r	Search recursively. Directory structures will not be retained.

-h –help Show this screen. –version Show version.

odml.scripts.odml_convert.dep_note(args=None)

Print deprecation warning and call main function.

Parameters:args – Command line arguments

odml.scripts.odml_convert.main(args=None)

Convenience script to automatically convert odML files within a directory (tree) to the newest file version. Check the cli help for details. :param args: Command line arguments

odml.scripts.odml_convert.run_conversion(file_list, output_dir, report, source_format='XML')

Convert a list of odML files to the latest odML version. :param file_list: list of files to be converted. :param output_dir: Directory where odML files converted to

the latest odML version will be saved.

Parameters:

• report – Reporting StringIO.
• source_format – Original file format of the odML source files. XML, JSON and YAML are supported, default is XML.

odML to RDF script

odmlToRDF

odmlToRDF searches for odML files within a provided SEARCHDIR and converts them to the newest odML format version and exports all found and resulting odML files to XML formatted RDF. Original files will never be overwritten. New files will be written either to a new directory at the current or a specified location.

Usage: odmltordf [-r] [-o OUT] SEARCHDIR

Arguments:

SEARCHDIR Directory to search for odML files.

Options:

-o OUT	Output directory. Must exist if specified. If not specified, output files will be written to the current directory.
-r	Search recursively. Directory structures will not be retained.

-h –help Show this screen. –version Show version.

odml.scripts.odml_to_rdf.main(args=None)

Convenience script to automatically convert odML files within a directory (tree) to RDF. Check the cli help for details. :param args: Command line arguments

odml.scripts.odml_to_rdf.run_conversion(file_list, output_dir, rdf_dir, report, source_format='XML')

Convert a list of odML files to the latest odML version if required and export all files to XML RDF files in a specified output directory. :param file_list: list of files to be exported to RDF. :param output_dir: Directory where odML files converted to

the latest odML version will be saved.

Parameters:

• rdf_dir – Directory where exported RDF files will be saved.
• report – Reporting StringIO.
• source_format – Original file format of the odML source files. XML, JSON and YAML are supported, default is XML.

odml.scripts.odml_to_rdf.run_rdf_export(odml_file, export_dir)

Convert an odML file to an XML RDF file and export it to an export directory with the same name as the original file and a ‘.rdf’ file ending. :param odml_file: odML file to be converted to RDF. :param export_dir:

odML view (browse odml files locally)

odmlview

odmlview sets up a minimal webserver to view odml files saved in the XML format via the webbrowser. After it is started, the webserver will open a new tab in the default webbrowser and display the content of the directory the server was started from. odML files can then be viewed from there. To properly render XML, an odML file may contain the element ‘<?xml-stylesheet type=”text/xsl” href=”odmlDocument.xsl”?>’ where the ‘odmlDocument.xsl’ stylesheet should reside in the same directory as the odML file to be rendered. By using the ‘–fetch’ flag the latest version of this stylesheet will be downloaded from ‘templates.g-node.org’ to the current directory when starting up the service.

Usage: odmlview [-p PORT] [–fetch]

Options:

-p PORT	Port the server will use. Default: 8000
--fetch	Fetch latest stylesheet from templates.g-node.org to current directory

-h –help Show this screen –version Show version

odml.scripts.odml_view.download_file(repo, filename)

download_file fetches ‘filename’ from url ‘repo’ and saves it in the current directory as file ‘filename’.

odml.scripts.odml_view.main(args=None)

odml.scripts.odml_view.run(port=8000, extensions=None)

run starts a simple webserver on localhost serving the current directory. Once started, it will open a tab on the default webbrowser and will continue to serve until manually stopped.

Parameters:

• port – server port
• extensions – dictionary containing additional file extension - mime type mappings the server should be aware of. e.g. {‘.xml’: ‘application/xml’}