io¶

Reading and writing of SBGN documents.

The functions in this module are the entry points of the package: an SBGN document is read into the Sbgn object tree of libsbgnpy.sbgn and serialized back to SBGN-ML with xsdata.

from pathlib import Path

from libsbgnpy import read_sbgn_from_file, write_sbgn_to_file

sbgn = read_sbgn_from_file(Path("map.sbgn"))
write_sbgn_to_file(sbgn, Path("map_copy.sbgn"))

parse_xml ¶

parse_xml(source)

Parse an untrusted XML document.

Entities are not resolved, nothing is loaded from the network, comments, processing instructions and unresolved entity references are dropped. A string is already decoded, so an encoding declared in it is ignored; bytes are decoded with the declared encoding, UTF-8 by default.

Parameters:

Name	Type	Description	Default
`source`	`str \| bytes`	XML document	required

Returns:

Type	Description
`_Element`	The root element.

Raises:

Type	Description
`XMLSyntaxError`	if the document is no well-formed XML

upconvert_tree ¶

upconvert_tree(root)

Move an SBGN-ML 0.1 or 0.2 tree into the 0.3 namespace.

Parameters:

Name	Type	Description	Default
`root`	`_Element`	root element of an SBGN-ML document, see `parse_xml`	required

Returns:

Type	Description
`_Element`	The tree in the `SBGN_NAMESPACE`, see `upconvert`: a copy for a 0.1 or 0.2 document, the tree itself otherwise.

upconvert ¶

upconvert(xml_str)

Move a document from the SBGN-ML 0.1 or 0.2 into the 0.3 namespace.

The bindings are generated from the SBGN-ML 0.3 schema, the earlier versions are read by upconverting the document. Only the names of the elements and attributes are changed, text and attribute values which mention a namespace are left as they are.

Parameters:

Name	Type	Description	Default
`xml_str`	`str`	SBGN-ML document	required

Returns:

Type	Description
`str`	The document in the `SBGN_NAMESPACE`, without XML declaration.

Raises:

Type	Description
`XMLSyntaxError`	if the document is no well-formed XML

read_sbgn_from_file ¶

read_sbgn_from_file(f)

Read an SBGN document from a file.

The document is not validated against the schema, see validate_xsd. SBGN-ML 0.1 and 0.2 documents are upconverted while reading.

Parameters:

Name	Type	Description	Default
`f`	`Path`	path of the SBGN file	required

Returns:

Type	Description
`Sbgn`	The SBGN document.

The file is decoded with the encoding its XML declaration names, UTF-8 by default.

Raises:

Type	Description
`OSError`	if the file cannot be read
`ParserError`	if the content is no SBGN-ML

read_sbgn_from_string ¶

read_sbgn_from_string(xml_str)

Read an SBGN document from a string.

The string is already decoded, an encoding named by its XML declaration is ignored. SBGN-ML 0.1 and 0.2 documents are upconverted while reading.

Parameters:

Name	Type	Description	Default
`xml_str`	`str`	SBGN-ML document	required

Returns:

Type	Description
`Sbgn`	The SBGN document.

Raises:

Type	Description
`ParserError`	if the content is no SBGN-ML

write_sbgn_to_file ¶

write_sbgn_to_file(sbgn, f)

Write an SBGN document to a file.

Parameters:

Name	Type	Description	Default
`sbgn`	`Sbgn`	SBGN document	required
`f`	`Path`	path of the file to write	required

Raises:

Type	Description
`OSError`	if the file cannot be written

write_sbgn_to_string ¶

write_sbgn_to_string(sbgn)

Serialize an SBGN document to an SBGN-ML string.

The raw XML of the notes and extension elements is converted into element trees first, see element_from_string, so that it is written as markup instead of as escaped text.

Parameters:

Name	Type	Description	Default
`sbgn`	`Sbgn`	SBGN document	required

Returns:

Type	Description
`str`	The SBGN-ML document, indented with two spaces.

read_render_from_string ¶

read_render_from_string(xml_str)

Read render information from a string.

Render information is stored in the extension of an SBGN element, see libsbgnpy.render.

Parameters:

Name	Type	Description	Default
`xml_str`	`str`	`renderInformation` document	required

Returns:

Type	Description
`RenderInformation`	The render information.

Raises:

Type	Description
`ParserError`	if the content is no render information

write_render_to_string ¶

write_render_to_string(render_info)

Serialize render information to a string.

The result is written without an XML declaration and without a namespace prefix, so that it can be stored in the extension of an SBGN element.

Parameters:

Name	Type	Description	Default
`render_info`	`RenderInformation`	render information	required

Returns:

Type	Description
`str`	The `renderInformation` document.

element_to_string ¶

element_to_string(element)

Serialize the raw XML of a notes or extension entry.

The content of notes and extension is arbitrary XML. It is set as a string, but read back as an AnyElement tree, so this function turns such an entry back into XML.

Parameters:

Name	Type	Description	Default
`element`	`object`	entry of `Sbgnbase.Notes` or `Sbgnbase.Extension`	required

Element-only content is indented with two spaces, mixed content (text next to elements, as in XHTML notes) is written as it is.

Returns:

Type	Description
`str`	The XML of the entry.

Raises:

Type	Description
`TypeError`	if the entry is neither a string nor an element tree
`ValueError`	if the element tree carries no element name

Examples:

>>> from libsbgnpy import element_to_string, read_sbgn_from_file
>>> sbgn = read_sbgn_from_file(f)
>>> notes = sbgn.map[0].glyph[0].notes
>>> element_to_string(notes.w3_org_1999_xhtml_element[0])
'<html:body xmlns:html="http://www.w3.org/1999/xhtml">note</html:body>'

element_from_string ¶

element_from_string(xml_str)

Parse raw XML into an entry of a notes or extension element.

Parameters:

Name	Type	Description	Default
`xml_str`	`str`	XML of a single element	required

Returns:

Type	Description
`AnyElement`	The element tree.

Raises:

Type	Description
`XMLSyntaxError`	if the string is no well-formed XML

read_render_from_extension ¶

read_render_from_extension(extension)

Read the render information stored in an extension.

Render information is stored as raw XML in the extension of an SBGN element, see libsbgnpy.render; the first renderInformation entry of the extension is returned. Render information in the namespace of the earlier EML render extension is upconverted to RENDER_NAMESPACE.

Parameters:

Name	Type	Description	Default
`extension`	`Extension \| None`	extension of an SBGN element, e.g., of a map	required

Returns:

Type	Description
`RenderInformation \| None`	The render information, or `None` if the extension contains none.

Raises:

Type	Description
`ParserError`	if the `renderInformation` entry is no valid render information
`XMLSyntaxError`	if an entry set as a string is no well-formed XML