suds.sax package

Submodules

suds.sax.attribute module

Provides XML attribute classes.

class suds.sax.attribute.Attribute(name, value=None)

Bases: suds.UnicodeMixin

An XML attribute object.

Variables:
  • parent – The node containing this attribute.
  • prefix – The optional namespace prefix.
  • name – The unqualified attribute name.
  • value – The attribute’s value.
clone(parent=None)

Clone this object.

Parameters:parent (element.Element) – The parent for the clone.
Returns:A copy of this object assigned to the new parent.
Return type:Attribute
getValue(default=)

Get the attributes value with optional default.

Parameters:default (basestring) – An optional value to return when the attribute’s value has not been set.
Returns:The attribute’s value, or default.
Return type:Text
hasText()

Get whether the attribute has a non-empty text string value.

Returns:True when has text.
Return type:boolean
match(name=None, ns=None)

Match by (optional) name and/or (optional) namespace.

Parameters:
  • name (str) – The optional attribute tag name.
  • ns ((prefix, name)) – An optional namespace.
Returns:

True if matched.
Return type:

boolean
namespace()

Get the attribute’s namespace. This may either be the namespace defined by an optional prefix, or the default namespace.

Returns:The attribute’s namespace.
Return type:(prefix, name)
qname()

Get this attribute’s B{fully} qualified name.

Returns:The fully qualified name.
Return type:basestring
resolvePrefix(prefix)

Resolve the specified prefix to a known namespace.

Parameters:prefix (basestring) – A declared prefix.
Returns:The namespace mapped to prefix.
Return type:(prefix, name)
setValue(value)

Set the attribute’s value.

Parameters:value (basestring) – The new value (may be None).
Returns:self
Return type:Attribute

suds.sax.date module

Classes for conversion between XML dates and Python objects.

class suds.sax.date.Date(value)

Bases: suds.UnicodeMixin

An XML date object supporting the xsd:date datatype.

Variables:value – The object value.
class suds.sax.date.DateTime(value)

Bases: suds.UnicodeMixin

An XML datetime object supporting the xsd:dateTime datatype.

Variables:value – The object value.
class suds.sax.date.FixedOffsetTimezone(offset)

Bases: datetime.tzinfo, suds.UnicodeMixin

A timezone with a fixed offset and no daylight savings adjustment.

http://docs.python.org/library/datetime.html#datetime.tzinfo

dst(dt)

http://docs.python.org/library/datetime.html#datetime.tzinfo.dst

tzname(dt)

http://docs.python.org/library/datetime.html#datetime.tzinfo.tzname

utcoffset(dt)

http://docs.python.org/library/datetime.html#datetime.tzinfo.utcoffset

class suds.sax.date.LocalTimezone

Bases: datetime.tzinfo

The local timezone of the operating system.

http://docs.python.org/library/datetime.html#datetime.tzinfo

dst(dt)

http://docs.python.org/library/datetime.html#datetime.tzinfo.dst

tzname(dt)

http://docs.python.org/library/datetime.html#datetime.tzinfo.tzname

utcoffset(dt)

http://docs.python.org/library/datetime.html#datetime.tzinfo.utcoffset

class suds.sax.date.Time(value)

Bases: suds.UnicodeMixin

An XML time object supporting the xsd:time datatype.

Variables:value – The object value.
class suds.sax.date.UtcTimezone

Bases: suds.sax.date.FixedOffsetTimezone

The UTC timezone.

http://docs.python.org/library/datetime.html#datetime.tzinfo

tzname(dt)

http://docs.python.org/library/datetime.html#datetime.tzinfo.tzname

suds.sax.document module

Provides XML document classes.

class suds.sax.document.Document(root=None)

Bases: suds.UnicodeMixin

An XML Document

DECL = '<?xml version="1.0" encoding="UTF-8"?>'
append(node)

Append (set) the document root. :param node: A root Element or name used to build

the document root element.
childAtPath(path)

Get a child at path where path is a (/) separated list of element names that are expected to be children. :param path: A (/) separated list of element names. :type path: basestring :return: The leaf node at the end of path :rtype: Element

childrenAtPath(path)

Get a list of children at path where path is a (/) separated list of element names that are expected to be children. :param path: A (/) separated list of element names. :type path: basestring :return: The collection leaf nodes at the end of path :rtype: [Element,…]

getChild(name, ns=None, default=None)

Get a child by (optional) name and/or (optional) namespace. :param name: The name of a child element (may contain prefix). :type name: basestring :param ns: An optional namespace used to match the child. :type ns: (prefix, name) :param default: Returned when child not-found. :type default: Element :return: The requested child, or default when not-found. :rtype: Element

getChildren(name=None, ns=None)

Get a list of children by (optional) name and/or (optional) namespace. :param name: The name of a child element (may contain prefix). :type name: basestring :param ns: An optional namespace used to match the child. :type ns: (prefix, name) :return: The list of matching children. :rtype: [Element,…]

plain()

Get a string representation of this XML document. :return: A plain string. :rtype: basestring

root()

Get the document root element (can be None) :return: The document root. :rtype: Element

str()

Get a string representation of this XML document. :return: A pretty string. :rtype: basestring

suds.sax.element module

XML element classes.

class suds.sax.element.Element(name, parent=None, ns=None)

Bases: suds.UnicodeMixin

An XML element object.

Variables:
  • parent – The node containing this attribute.
  • prefix – The optional namespace prefix.
  • name – The unqualified name of the attribute.
  • expns – An explicit namespace (xmlns=”…”).
  • nsprefixes – A mapping of prefixes to namespaces.
  • attributes – A list of XML attributes.
  • text – The element’s text content.
  • children – A list of child elements.
  • matcher – A collection of lambda for string matching.
  • specialprefixes – A dictionary of builtin-special prefixes.
addPrefix(p, u)

Add or update a prefix mapping.

Parameters:
  • p (basestring) – A prefix.
  • u (basestring) – A namespace URI.
Returns:

self
Return type:

Element
ancestors()

Get a list of ancestors.

Returns:A list of ancestors.
Return type:[Element,…]
append(objects)

Append the specified child based on whether it is an element or an attribute.

Parameters:objects ((Element`|:class:`Attribute)) – A (single|collection) of attribute(s) or element(s) to be added as children.
Returns:self
Return type:Element
applyns(ns)

Apply the namespace to this node.

If the prefix is None then this element’s explicit namespace expns is set to the URI defined by ns. Otherwise, the ns is simply mapped.

Parameters:ns ((prefix, URI)) – A namespace.
branch()

Get a flattened representation of the branch.

Returns:A flat list of nodes.
Return type:[Element,…]
classmethod buildPath(parent, path)

Build the specified path as a/b/c.

Any missing intermediate nodes are built automatically.

Parameters:
  • parent (Element) – A parent element on which the path is built.
  • path (basestring) – A simple path separated by (/).
Returns:

The leaf node of path.
Return type:

Element
childAtPath(path)

Get a child at path where path is a (/) separated list of element names that are expected to be children.

Parameters:path (basestring) – A (/) separated list of element names.
Returns:The leaf node at the end of path.
Return type:Element
childrenAtPath(path)

Get a list of children at path where path is a (/) separated list of element names expected to be children.

Parameters:path (basestring) – A (/) separated list of element names.
Returns:The collection leaf nodes at the end of path.
Return type:[Element,…]
clearPrefix(prefix)

Clear the specified prefix from the prefix mappings.

Parameters:prefix (basestring) – A prefix to clear.
Returns:self
Return type:Element
clone(parent=None)

Deep clone of this element and children.

Parameters:parent (Element) – An optional parent for the copied fragment.
Returns:A deep copy parented by parent
Return type:Element
defaultNamespace()

Get the default (unqualified namespace).

This is the expns of the first node (looking up the tree) that has it set.

Returns:The namespace of a node when not qualified.
Return type:(prefix, name)
detach()

Detach from parent.

Returns:This element removed from its parent’s child list and parent``=``None.
Return type:Element
detachChildren()

Detach and return this element’s children.

Returns:The element’s children (detached).
Return type:[Element,…]
findPrefix(uri, default=None)

Find the first prefix that has been mapped to a namespace URI.

The local mapping is searched, then walks up the tree until it reaches the top or finds a match.

Parameters:
  • uri (basestring) – A namespace URI.
  • default (basestring) – A default prefix when not found.
Returns:

A mapped prefix.
Return type:

basestring
findPrefixes(uri, match='eq')

Find all prefixes that have been mapped to a namespace URI.

The local mapping is searched, then walks up the tree until it reaches the top, collecting all matches.

Parameters:
  • uri (basestring) – A namespace URI.
  • match (basestring) – A matching function Element.matcher.
Returns:

A list of mapped prefixes.
Return type:

[basestring,..]
get(name, ns=None, default=None)

Get the value of an attribute by name.

Parameters:
  • name (basestring) – The name of the attribute.
  • ns ((prefix, name)) – The optional attribute’s namespace.
  • default (basestring) – An optional value to be returned when either the attribute does not exist or has no value.
Returns:

The attribute’s value or default.
Return type:

basestring

@see: __getitem__()

getAttribute(name, ns=None, default=None)

Get an attribute by name and (optional) namespace.

Parameters:
  • name (basestring) – The name of a contained attribute (may contain prefix).
  • ns ((prefix, name)) – An optional namespace
  • default (Attribute) – Returned when attribute not-found.
Returns:

The requested attribute object.
Return type:

Attribute
getChild(name, ns=None, default=None)

Get a child by (optional) name and/or (optional) namespace.

Parameters:
  • name (basestring) – The name of a child element (may contain prefix).
  • ns ((prefix, name)) – An optional namespace used to match the child.
  • default (Element) – Returned when child not-found.
Returns:

The requested child, or default when not-found.
Return type:

Element
getChildren(name=None, ns=None)

Get a list of children by (optional) name and/or (optional) namespace.

Parameters:
  • name (basestring) – The name of a child element (may contain a prefix).
  • ns ((prefix, name)) – An optional namespace used to match the child.
Returns:

The list of matching children.
Return type:

[Element,…]
getRoot()

Get the root (top) node of the tree.

Returns:The top node of this tree.
Return type:Element
getText(default=None)

Get the element’s Text content with optional default.

Parameters:default (basestring) – A value to be returned when no text content exists.
Returns:The text content, or default.
Return type:Text
hasText()

Get whether the element has non-empty text string.

Returns:True when has text.
Return type:boolean
insert(objects, index=0)

Insert an Element content at the specified index.

Parameters:
  • objects ((Element`|:class:`Attribute)) – A (single|collection) of attribute(s) or element(s) to be added as children.
  • index (int) – The position in the list of children to insert.
Returns:

self
Return type:

Element
isempty(content=True)

Get whether the element has no children.

Parameters:content (boolean) – Test content (children & text) only.
Returns:True when element has not children.
Return type:boolean
isnil()

Get whether the element is nil as defined by having an xsi:nil="true" attribute.

Returns:True if nil, else False
Return type:boolean
match(name=None, ns=None)

Match by (optional) name and/or (optional) namespace.

Parameters:
  • name (str) – The optional element tag name.
  • ns ((prefix, name)) – An optional namespace.
Returns:

True if matched.
Return type:

boolean
matcher = {'contains': <function <lambda>>, 'endswith': <function <lambda>>, 'eq': <function <lambda>>, 'startswith': <function <lambda>>}
namespace()

Get the element’s namespace.

Returns:The element’s namespace by resolving the prefix, the explicit namespace or the inherited namespace.
Return type:(prefix, name)
normalizePrefixes()

Normalize the namespace prefixes.

This generates unique prefixes for all namespaces. Then retrofits all prefixes and prefix mappings. Further, it will retrofix attribute values that have values containing (:).

Returns:self
Return type:Element
nsdeclarations()

Get a string representation for all namespace declarations as xmlns=”” and xmlns:p=””.

Returns:A separated list of declarations.
Return type:basestring
plain()

Get a string representation of this XML fragment.

Returns:A plain string.
Return type:basestring
promotePrefixes()

Push prefix declarations up the tree as far as possible.

Prefix mapping are pushed to its parent unless the parent has the prefix mapped to another URI or the parent has the prefix. This is propagated up the tree until the top is reached.

Returns:self
Return type:Element
prune()

Prune the branch of empty nodes.

qname()

Get this element’s B{fully} qualified name.

Returns:The fully qualified name.
Return type:basestring
refitPrefixes()

Refit namespace qualification by replacing prefixes with explicit namespaces. Also purges prefix mapping table.

Returns:self
Return type:Element
remove(child)

Remove the specified child element or attribute.

Parameters:child (Element`|:class:`Attribute) – A child to remove.
Returns:The detached child when child is an element, else None.
Return type::class:`Element`|None
rename(name)

Rename the element.

Parameters:name (basestring) – A new name for the element.
replaceChild(child, content)

Replace child with the specified content.

Parameters:
  • child (Element) – A child element.
  • content (Element or [Element,…]) – An element or collection of elements.
resolvePrefix(prefix, default=(None, None))

Resolve the specified prefix to a namespace. The nsprefixes is searched. If not found, walk up the tree until either resolved or the top of the tree is reached. Searching up the tree provides for inherited mappings.

Parameters:
  • prefix (basestring) – A namespace prefix to resolve.
  • default ((prefix, URI)) – An optional value to be returned when the prefix cannot be resolved.
Returns:

The namespace that is mapped to prefix in this context.
Return type:

(prefix, URI)
set(name, value)

Set an attribute’s value.

Parameters:
  • name (basestring) – The name of the attribute.
  • value (basestring) – The attribute value.

@see: __setitem__()

setPrefix(p, u=None)

Set the element namespace prefix.

Parameters:
  • p (basestring) – A new prefix for the element.
  • u (basestring) – A namespace URI to be mapped to the prefix.
Returns:

self
Return type:

Element
setText(value)

Set the element’s Text content.

Parameters:value (basestring) – The element’s text value.
Returns:self
Return type:Element
setnil(flag=True)

Set this node to nil as defined by having an xsi:nil``=``flag attribute.

Parameters:flag (boolean) – A flag indicating how xsi:nil will be set.
Returns:self
Return type:Element
specialprefixes = {'xml': 'http://www.w3.org/XML/1998/namespace'}
str(indent=0)

Get a string representation of this XML fragment.

Parameters:indent (int) – The indent to be used in formatting the output.
Returns:A pretty string.
Return type:basestring
trim()

Trim leading and trailing whitespace.

Returns:self
Return type:Element
unset(name)

Unset (remove) an attribute.

Parameters:name (str) – The attribute name.
Returns:self
Return type:Element
updatePrefix(p, u)

Update (redefine) a prefix mapping for the branch.

Parameters:
  • p (basestring) – A prefix.
  • u (basestring) – A namespace URI.
Returns:

self
Return type:

Element

@note: This method traverses down the entire branch!

walk(visitor)

Walk the branch and call the visitor function on each node.

Parameters:visitor (single argument function) – A function.
Returns:self
Return type:Element
class suds.sax.element.NodeIterator(parent)

The Element child node iterator.

Variables:
  • pos – The current position
  • children – A list of a child nodes.
next()

Get the next child.

Returns:The next child.
Return type:Element

@raise StopIterator: At the end.

class suds.sax.element.PrefixNormalizer(node)

The prefix normalizer provides namespace prefix normalization.

Variables:
  • node – A node to normalize.
  • branch – The nodes flattened branch.
  • namespaces – A unique list of namespaces (URI).
  • prefixes – A reverse dict of prefixes.
classmethod apply(node)

Normalize the specified node.

Parameters:node (Element) – A node to normalize.
Returns:The normalized node.
Return type:Element
genPrefixes()

Generate a reverse mapping of unique prefixes for all namespaces.

Returns:A reverse dict of prefixes.
Return type:{u: p}
getNamespaces()

Get the unique set of namespaces referenced in the branch.

Returns:A set of namespaces.
Return type:set
permit(ns)

Get whether the ns is to be normalized.

Parameters:ns ((p, u)) – A namespace.
Returns:True if to be included.
Return type:boolean
pset(n)

Convert the nodes nsprefixes into a set.

Parameters:n (Element) – A node.
Returns:A set of namespaces.
Return type:set
refit()

Refit (normalize) the prefixes in the node.

refitAddr(a)

Refit (normalize) the attribute.

Parameters:a (Attribute) – An attribute.
refitAttrs(n)

Refit (normalize) all of the attributes in the node.

Parameters:n (Element) – A node.
refitMappings()

Refit (normalize) all of the nsprefix mappings.

refitNodes()

Refit (normalize) all of the nodes in the branch.

refitValue(a)

Refit (normalize) the attribute’s value.

Parameters:a (Attribute) – An attribute.
skip(ns)

Get whether the ns is to B{not} be normalized.

Parameters:ns ((p, u)) – A namespace.
Returns:True if to be skipped.
Return type:boolean

suds.sax.enc module

Provides XML special character encoder classes.

class suds.sax.enc.Encoder

An XML special character encoder/decoder.

Variables:
  • encodings – A mapping of special characters encoding.
  • decodings – A mapping of special characters decoding.
  • special – A list of special characters.
decode(s)

Decode special characters encodings found in string s.

Parameters:s (str) – A string to decode.
Returns:The decoded string.
Return type:str
decodings = (('&lt;', '<'), ('&gt;', '>'), ('&quot;', '"'), ('&apos;', "'"), ('&amp;', '&'))
encode(s)

Encode special characters found in string s.

Parameters:s (str) – A string to encode.
Returns:The encoded string.
Return type:str
encodings = (('&(?!(amp|lt|gt|quot|apos);)', '&amp;'), ('<', '&lt;'), ('>', '&gt;'), ('"', '&quot;'), ("'", '&apos;'))
special = ('&', '<', '>', '"', "'")

suds.sax.parser module

Classes providing a (D)ocument (O)bject (M)odel representation of an XML document.

The goal is to provide an easy, intuitive interface for managing XML documents. Although the term DOM is used above, this model is B{far} better.

XML namespaces in suds are represented using a (2) element tuple containing the prefix and the URI, e.g. ('tns', 'http://myns').

class suds.sax.parser.Handler

Bases: xml.sax.handler.ContentHandler

SAX handler.

characters(content)
endElement(name)
mapPrefix(node, attribute)
pop()
push(node)
startElement(name, attrs)
top()
class suds.sax.parser.Parser

SAX parser.

parse(file=None, string=None)

SAX parse XML text.

Parameters:
  • file (file-like object) – Parse a python file-like object.
  • string (str) – Parse string XML.
Returns:

Parsed XML document.
Return type:

Document
classmethod saxparser()

suds.sax.text module

Contains XML text classes.

class suds.sax.text.Raw

Bases: suds.sax.text.Text

Raw text which is not XML escaped. This may include string XML.

escape()

Encode (escape) special XML characters. :return: The text with XML special characters escaped. :rtype: Text

unescape()

Decode (unescape) special XML characters. :return: The text with escaped XML special characters decoded. :rtype: Text

class suds.sax.text.Text

Bases: unicode

An XML text object used to represent text content. :ivar lang: The (optional) language flag. :type lang: bool :ivar escaped: The (optional) XML special character escaped flag. :type escaped: bool

escape()

Encode (escape) special XML characters. :return: The text with XML special characters escaped. :rtype: Text

escaped
lang
trim()
unescape()

Decode (unescape) special XML characters. :return: The text with escaped XML special characters decoded. :rtype: Text

Module contents

The sax module contains a collection of classes that provide a (D)ocument (O)bject (M)odel representation of an XML document. The goal is to provide an easy, intuitive interface for managing XML documents. Although the term DOM is used here, this model is B{far} better.

XML namespaces in suds are represented using a (2) element tuple containing the prefix and the URI, e.g. ('tns', 'http://myns')

var encoder:A pluggable XML special character processor used to encode/ decode strings.
type encoder:Encoder
class suds.sax.Namespace

XML namespace.

all = (('xs', 'http://www.w3.org/2001/XMLSchema'), ('xsi', 'http://www.w3.org/2001/XMLSchema-instance'))
classmethod create(p=None, u=None)
default = (None, None)
classmethod isns(ns)
classmethod none(ns)
classmethod w3(ns)
xmlns = ('xml', 'http://www.w3.org/XML/1998/namespace')
classmethod xs(ns)
classmethod xsd(ns)
xsdns = ('xs', 'http://www.w3.org/2001/XMLSchema')
classmethod xsi(ns)
xsins = ('xsi', 'http://www.w3.org/2001/XMLSchema-instance')
suds.sax.splitPrefix(name)

Split the name into a tuple (prefix, name). The first element in the tuple is None when the name does not have a prefix.

Parameters:name (basestring) – A node name containing an optional prefix.
Returns:A tuple containing the (2) parts of name.
Return type:(prefix, name)