Basic XML Components

psims.xml.element(xml_file, _tag_name, *args, **kwargs)

Construct and immediately write a subclass instance of TagBase with the given tag name. All other arguments are forwarded to the TagBase constructor

Parameters

• xml_file (XMLWriterMixin) – The XML writer to write to

• _tag_name (str) – The name of the tag type to create

• *args – Arbitrary arguments for the tag

• **kwargs – Key word arguments for the tag

psims.xml._element(_tag_name, *args, **kwargs)

Construct a subclass instance of TagBase with the given tag name. All other arguments are forwarded to the TagBase constructor

Parameters

• _tag_name (str) – The name of the tag type to create

• *args – Arbitrary arguments for the tag

• **kwargs – Key word arguments for the tag

Returns

Return type

TagBase

class psims.xml.TagBase(tag_name=None, text='', **attrs)

Represent a single XML element with arbitrary attributes.

Mocks the Mapping interface

attrs

The attributes of the element. __getattr__() falls back to querying attrs, trying both requested name and camelCase versions of the name

Type

dict

is_open

Whether the element has been opened as a context manager

Type

bool

tag_name

The name of the element

Type

str

text

The body text of the element

Type

str

type_attrs

Attributes common to all elements of this type

Type

dict

id

The @id attribute of the element.

Type

str

class psims.xml.CVParam(accession=None, name=None, ref=None, value=None, **attrs)

Represents a <cvParam />

Note

This element holds additional data or annotation. Only controlled values are allowed here

name

The human-readable name of the parameter

Type

str

accession

The within-vocabulary unique identifier of the parameter

Type

str

value

The value of the parameter, to be converted to text

Type

object

XSD Description

This element holds additional data or annotation. Only controlled values are allowed here.

class psims.xml.UserParam(accession=None, name=None, ref=None, value=None, **attrs)

Represents a <userParam /> element

Note

Uncontrolled user parameters (essentially allowing free text). Before using these, one should verify whether there is an appropriate CV term available, and if so, use the CV term instead

XSD Description

Uncontrolled user parameters (essentially allowing free text). Before using these, one should verify whether there is an appropriate CV term available, and if so, use the CV term instead

class psims.xml.ParamGroupReference(ref)

class psims.xml.CV(full_name, id, uri, version=None, resolver=None, **kwargs)

Represent a Controlled Vocabulary associated with the current document.

The controlled vocabulary referenced must specify a URI that will be used to either download the definitions from, to be matched to a cache of pre-built vocabularies, or to be matched with a set of special resolution rules for handled by the resolver.

This object acts as a lazy-loading proxy for ControlledVocabulary.

full_name

The full name of the controlled vocabulary, which may or may not be identical to the id

Type

str

id

A short unique identifier for the controlled vocabulary

Type

str

options

Additional information that may be used during resolution

Type

dict

resolver

The resolver which will handle all requests for this controlled vocabulary

Type

VocabularyResolver

uri

The location where the definition can be found

Type

str

version

The version of the vocabulary resolved

Type

str

vocabulary

The parsed term graph defining this vocabulary

Type

ControlledVocabulary

XSD Description

Information about an ontology or CV source and a short 'lookup' tag to refer to.

class psims.xml.ProvidedCV(id, uri, converter=<function identity>, **kwargs)

A wrapper around another object that provides the same basic interface as CV from that object, provided through the converter function

converter

A function that converts elements of the provided vocabulary into something matching the Entity interface.

Type

Callable

class psims.xml.XMLWriterMixin

A mixin class to provide methods for writing XML elements and aggregate Components.

verbose

Controls debug printing

Type

bool

writer

The low-level XML writer used by xmlfile

Type

lxml.etree._IncrementalFileWriter

element(element_name, **kwargs)

Construct and immediately open a subclass instance of TagBase with the given tag name. All other arguments are forwarded to the TagBase constructor.

Parameters

• element_name (str) – The name of the tag type to create

• *args – Arbitrary arguments for the tag

• **kwargs – Key word arguments for the tag

See also

element()

write(*args, **kwargs)

Either write a complete XML sub-tree or add free text to the file stream

Parameters

arg (str or lxml.etree.Element) – The entity to be written out.

class psims.xml.XMLDocumentWriter(outfile, close=None, encoding=None, **kwargs)

A base class for types which are used to write complete XML documents.

outfile

A writable file object

Type

file

toplevel

The top-level XML tag

Type

TagBase

xmlfile

The XML formatter

Type

lxml.etree.xmlfile

writer

The low-level XML writer used by xmlfile

Type

lxml.etree._IncrementalFileWriter

begin()

Writes the doctype and starts the low-level writing machinery

controlled_vocabularies()

Write out the <cvList> element and all its children, including both this format’s default controlled vocabularies and those passed as arguments to this method.this

This method requires writing to have begun.

element(element_name, **kwargs)

Construct and immediately open a subclass instance of TagBase with the given tag name. All other arguments are forwarded to the TagBase constructor.

Parameters

• element_name (str) – The name of the tag type to create

• *args – Arbitrary arguments for the tag

• **kwargs – Key word arguments for the tag

See also

element()

end(exc_type=None, exc_value=None, traceback=None)

Ends the XML document, and flushes and closes the file if appropriate.

format(outfile=None)

This method is deprecated. Previously, the serialization process did not indent the XML in-place and the lxml pretty printer had to be invoked separately. With the addition of XMLFormattingStreamWriter, the XML stream is formatted in-place as it is being streamed to file.

static toplevel_tag()

Overridable method to construct the appropriate tag for toplevel

Returns

Return type

TagBase

validate()

Attempt to perform XSD validation on the XML document this writer wrote

Returns

• bool – Whether or not the document was valid

• lxml.etree.XMLSchema – The schema object where errors are logged

Raises

TypeError – When the file cannot be recovered from the writer object, a TypeError is thrown

write(*args, **kwargs)

Either write a complete XML sub-tree or add free text to the file stream

Parameters

arg (str or lxml.etree.Element) – The entity to be written out.