dip.io.codecs.xml

The dip.io.codecs.xml module implements support for XML encoders and decoders used with streaming storage.

IXmlDecoder

class dip.io.codecs.xml.IXmlDecoder

Base class: Interface

The IXmlDecoder interface defines the interface to be implemented by models being decoded by the XmlCodec codec.

IXmlEncoder

class dip.io.codecs.xml.IXmlEncoder

Base class: Interface

The IXmlEncoder interface defines the interface to be implemented by models being encoded by the XmlCodec codec.

XmlCodec

class dip.io.codecs.xml.XmlCodec

Base class: Model

The XmlCodec class implements a codec that decodes and encodes instances of Model as XML. The codec does not set the format attribute. This should be defined in a sub-class or passed as an argument when the codec is created.

decoder = Any()

The decoder itself. It must have a decode method with the same signature as the decode method.

decoder_interface = IXmlDecoder

The decoder interface.

encoder = Any()

The encoder itself. It must have a decode method with the same signature as the encode method.

encoder_interface = IXmlEncoder

The encoder interface.

decode(model, source, location)

A model is decoded from a byte stream.

Parameters:
  • model – is the model.
  • source – is an iterator that will return the byte stream to be decoded.
  • location – is the storage location where the encoded model is being read from. It is mainly used for error reporting.
Returns:

the decoded model. This may be the original model populated from the storage location, or it may be a different model (of an appropriate type) created from the storage location.
encode(model, location)

A model is encoded as a byte stream.

Parameters:
  • model – is the model.
  • location – is the storage location where the encoded model will be written to. It is mainly used for error reporting.
Returns:

a generator that will return sections of the encoded byte stream.

XmlDecoder

class dip.io.codecs.xml.XmlDecoder

Base class: Model

The XmlDecoder class implements a model decoder that decodes a Model instance from XML.

format = Str()

The identifier of the format.

decode(model, source, location)

A model is decoded from an XML byte stream.

Parameters:
  • model – is the model to populate from the decoded byte stream.
  • source – is an iterator that will return the byte stream to be decoded.
  • location – is the storage location where the encoded model is being read from. It is mainly used for error reporting.
Returns:

the decoded model.
decode_attribute(model, model_types, reader, source, location)

Decode the current element as an attribute.

Parameters:
  • model – is the model to populate from the decoded byte stream.
  • model_types – is the dict of the model’s types.
  • reader – is the QXmlStreamReader instance.
  • source – is an iterator that will return the byte stream to be decoded.
  • location – is the storage location where the encoded model is being read from. It is mainly used for error reporting.
decode_document_element(model, reader, location)

Decode the document element (i.e. the outermost element).

Parameters:
  • model – is the model to populate from the decoded byte stream.
  • reader – is the QXmlStreamReader instance.
  • location – is the storage location where the encoded model is being read from. It is mainly used for error reporting.
decode_model(model, reader, source, location)

Decode the next element as a model.

Parameters:
  • model – is the model to populate from the decoded byte stream.
  • reader – is the QXmlStreamReader instance.
  • source – is an iterator that will return the byte stream to be decoded.
  • location – is the storage location where the encoded model is being read from. It is mainly used for error reporting.

XmlEncoder

class dip.io.codecs.xml.XmlEncoder

Base class: Model

The XmlEncoder class implements a model encoder that encodes a Model instance as XML.

Note that, by default, pickle is used to encode any attributes that don’t have a value corresponding to a fundamental Python type (i.e. Int, List etc.). It is recommended (but not required) that the model is defined fully in terms of these fundamental types or that the encoder is sub-classed to handle attributes with non-fundamental types explicitly.

declaration = Str('<?xml version="1.0" encoding="UTF-8"?>')

The XML declaration.

document_start = Str()

The text to open the outermost element.

document_end = Str('</DipModel>')

The text to close the outermost element.

encoding = Str('utf8')

The encoding to use.

exclude = List(Str())

The list of names of attributes to exclude.

format = Str()

The identifier of the format.

include = List(Str())

The list of names of attributes to include. If this is empty then all attributes are included unless they have been explicitly excluded.

indentation_spaces = Int(2)

The number of spaces used for a single level of indentation.

encode(model, location)

A model is encoded as an XML byte stream.

Parameters:
  • model – is the model to encode.
  • location – is the storage location where the encoded model will be written to. It is mainly used for error reporting.
Returns:

the next section of the encoded XML byte stream.
encode_attribute(model, name, value, attribute_type, location, indent_level)

A single attribute is encoded as an XML byte stream.

Parameters:
  • model – is the model containing the attribute to encode.
  • name – is the name of the attribute. It may be ‘’ if the value is a member of a collection attribute.
  • value – is the value of the attribute.
  • attribute_type – is the type of the attribute.
  • location – is the storage location where the encoded attribute will be written to. It is mainly used for error reporting.
  • indent_level – is the current indentation level as a number.
Returns:

the next section of the encoded XML byte stream.
encode_model(model, location, indent_level)

A model is encoded as an XML byte stream.

Parameters:
  • model – is the model to encode.
  • location – is the storage location where the encoded model will be written to. It is mainly used for error reporting.
  • indent_level – is the current indentation level as a number.
static escape(value)

Replace any characters with their corresponding entities.

Parameters:value – is the string to escape.
Returns:the escaped string.
indentation(indent_level)

Return a string that will indent a line to a particular level.

Parameters:indent_level – is the indentation level as a number.
Returns:the string.