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"))

upconvert ¶

upconvert(xml_str)

Replace an SBGN-ML 0.1 or 0.2 namespace with the 0.3 namespace.

The bindings are generated from the SBGN-ML 0.3 schema, the earlier versions are read by upconverting the document.

Parameters:

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

Returns:

Type	Description
`str`	The document in the `SBGN_NAMESPACE`.

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.

Raises:

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

read_sbgn_from_string ¶

read_sbgn_from_string(xml_str)

Read an SBGN document from a string.

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 valid 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

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.

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 entry is no render information