Package suds :: Package sax :: Module element :: Class Element
[hide private]
[frames] | no frames]

Class Element

source code

Known Subclasses:

An XML element object.

Instance Methods [hide private]
 
__childrenAtPath(self, parts) source code
 
__eq__(self, rhs) source code
 
__getitem__(self, index) source code
 
__init__(self, name, parent=None, ns=None) source code
 
__iter__(self) source code
 
__len__(self) source code
 
__repr__(self) source code
 
__setitem__(self, index, value) source code
 
__str__(self) source code
 
__unicode__(self) source code
Element
addPrefix(self, p, u)
Add or update a prefix mapping.
source code
[Element,..]
ancestors(self)
Get a list of ancestors.
source code
Element
append(self, objects)
Append the specified child based on whether it is an element or an attrbuite.
source code
 
applyns(self, ns)
Apply the namespace to this node.
source code
[Element,..]
branch(self)
Get a flattened representation of the branch.
source code
Element
childAtPath(self, path)
Get a child at path where path is a (/) separated list of element names that are expected to be children.
source code
[Element,...]
childrenAtPath(self, path)
Get a list of children at path where path is a (/) separated list of element names that are expected to be children.
source code
Element
clearPrefix(self, prefix)
Clear the specified prefix from the prefix mappings.
source code
Element
clone(self, parent=None)
Deep clone of this element and children.
source code
(prefix, name)
defaultNamespace(self)
Get the default (unqualified namespace).
source code
Element
detach(self)
Detach from parent.
source code
[Element,...]
detachChildren(self)
Detach and return this element's children.
source code
basestring
findPrefix(self, uri, default=None)
Find the first prefix that has been mapped to a namespace URI.
source code
[basestring,...]
findPrefixes(self, uri, match='eq')
Find all prefixes that has been mapped to a namespace URI.
source code
basestring
get(self, name, ns=None, default=None)
Get the value of an attribute by name.
source code
Attribute
getAttribute(self, name, ns=None, default=None)
Get an attribute by name and (optional) namespace
source code
Element
getChild(self, name, ns=None, default=None)
Get a child by (optional) name and/or (optional) namespace.
source code
[Element,...]
getChildren(self, name=None, ns=None)
Get a list of children by (optional) name and/or (optional) namespace.
source code
Element
getRoot(self)
Get the root (top) node of the tree.
source code
Text
getText(self, default=None)
Get the element's Text content with optional default
source code
boolean
hasText(self)
Get whether the element has text and that it is not an empty (zero length) string.
source code
Element
insert(self, objects, index=0)
Insert an Element content at the specified index.
source code
boolean
isempty(self, content=True)
Get whether the element has no children.
source code
boolean
isnil(self)
Get whether the element is nil as defined by having an attribute in the xsi:nil="true"
source code
boolean
match(self, name=None, ns=None)
Match by (optional) name and/or (optional) namespace.
source code
(prefix, name)
namespace(self)
Get the element's namespace.
source code
Element
normalizePrefixes(self)
Normalize the namespace prefixes.
source code
basestring
nsdeclarations(self)
Get a string representation for all namespace declarations as xmlns="" and xmlns:p="".
source code
basestring
plain(self)
Get a string representation of this XML fragment.
source code
Element
promotePrefixes(self)
Push prefix declarations up the tree as far as possible.
source code
 
prune(self)
Prune the branch of empty nodes.
source code
basestring
qname(self)
Get the fully qualified name of this element
source code
Element
refitPrefixes(self)
Refit namespace qualification by replacing prefixes with explicit namespaces.
source code
Element|None
remove(self, child)
Remove the specified child element or attribute.
source code
 
rename(self, name)
Rename the element.
source code
 
replaceChild(self, child, content)
Replace child with the specified content.
source code
(prefix,URI)
resolvePrefix(self, prefix, default=(None, None))
Resolve the specified prefix to a namespace.
source code
 
set(self, name, value)
Set an attribute's value.
source code
Element
setPrefix(self, p, u=None)
Set the element namespace prefix.
source code
Element
setText(self, value)
Set the element's Text content.
source code
Element
setnil(self, flag=True)
Set this node to nil as defined by having an attribute xsi:nil=flag.
source code
basestring
str(self, indent=0)
Get a string representation of this XML fragment.
source code
Element
trim(self)
Trim leading and trailing whitespace.
source code
Element
unset(self, name)
Unset (remove) an attribute.
source code
Element
updatePrefix(self, p, u)
Update (redefine) a prefix mapping for the branch.
source code
Element
walk(self, visitor)
Walk the branch and call the visitor function on each node.
source code
Class Methods [hide private]
Element
buildPath(self, parent, path)
Build the specifed pat as a/b/c where missing intermediate nodes are built automatically.
source code
Class Variables [hide private]
  matcher = {'eq': lambda a, b: a== b, 'startswith': lambda a, b...
A collection of lambda for string matching.
  specialprefixes = {'xml': 'http://www.w3.org/XML/1998/namespace'}
A dictionary of builtin-special prefixes.
Instance Variables [hide private]
[Attribute,] attributes
A list of XML attributes.
[Element,] children
A list of child elements.
(prefix, name) expns
An explicit namespace (xmlns="...").
basestring name
The unqualified name of the attribute
dict nsprefixes
A mapping of prefixes to namespaces.
Element parent
The node containing this attribute
basestring prefix
The optional namespace prefix.
basestring text
The element's text content.
Method Details [hide private]

__init__(self, name, parent=None, ns=None)
(Constructor)

source code 
Parameters:
  • name (basestring) - The element's (tag) name. May cotain a prefix.
  • parent (Element) - An optional parent element.
  • ns ((prefix, name)) - An optional namespace

addPrefix(self, p, u)

source code 

Add or update a prefix mapping.

Parameters:
  • p (basestring) - A prefix.
  • u (basestring) - A namespace URI.
Returns: Element
self

ancestors(self)

source code 

Get a list of ancestors.

Returns: [Element,..]
A list of ancestors.

append(self, objects)

source code 

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

Parameters:
  • objects ((Element|Attribute)) - A (single|collection) of attribute(s) or element(s) to be added as children.
Returns: Element
self

applyns(self, ns)

source code 

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(self)

source code 

Get a flattened representation of the branch.

Returns: [Element,..]
A flat list of nodes.

buildPath(self, parent, path)
Class Method

source code 

Build the specifed pat as a/b/c where 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: Element
The leaf node of path.

childAtPath(self, path)

source code 

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: Element
The leaf node at the end of path

childrenAtPath(self, path)

source code 

Get a list of children 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: [Element,...]
The collection leaf nodes at the end of path

clearPrefix(self, prefix)

source code 

Clear the specified prefix from the prefix mappings.

Parameters:
  • prefix (basestring) - A prefix to clear.
Returns: Element
self

clone(self, parent=None)

source code 

Deep clone of this element and children.

Parameters:
  • parent (Element) - An optional parent for the copied fragment.
Returns: Element
A deep copy parented by parent

defaultNamespace(self)

source code 

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

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

detach(self)

source code 

Detach from parent.

Returns: Element
This element removed from its parent's child list and parent=None

detachChildren(self)

source code 

Detach and return this element's children.

Returns: [Element,...]
The element's children (detached).

findPrefix(self, uri, default=None)

source code 

Find the first prefix that has been mapped to a namespace URI. The local mapping is searched, then it 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: basestring
A mapped prefix.

findPrefixes(self, uri, match='eq')

source code 

Find all prefixes that has been mapped to a namespace URI. The local mapping is searched, then it 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: [basestring,...]
A list of mapped prefixes.

get(self, name, ns=None, default=None)

source code 

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 of has not value.
Returns: basestring
The attribute's value or default

See Also: __getitem__()

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

source code 

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: Attribute
The requested attribute object.

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

source code 

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: Element
The requested child, or default when not-found.

getChildren(self, name=None, ns=None)

source code 

Get a list of children 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.
Returns: [Element,...]
The list of matching children.

getRoot(self)

source code 

Get the root (top) node of the tree.

Returns: Element
The top node of this tree.

getText(self, default=None)

source code 

Get the element's Text content with optional default

Parameters:
  • default (basestring) - A value to be returned when no text content exists.
Returns: Text
The text content, or default

hasText(self)

source code 

Get whether the element has text and that it is not an empty (zero length) string.

Returns: boolean
True when has text.

insert(self, objects, index=0)

source code 

Insert an Element content at the specified index.

Parameters:
  • objects ((Element|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: Element
self

isempty(self, content=True)

source code 

Get whether the element has no children.

Parameters:
  • content (boolean) - Test content (children & text) only.
Returns: boolean
True when element has not children.

isnil(self)

source code 

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

Returns: boolean
True if nil, else False

match(self, name=None, ns=None)

source code 

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

Parameters:
  • name (str) - The optional element tag name.
  • ns ((prefix, name)) - An optional namespace.
Returns: boolean
True if matched.

namespace(self)

source code 

Get the element's namespace.

Returns: (prefix, name)
The element's namespace by resolving the prefix, the explicit namespace or the inherited namespace.

normalizePrefixes(self)

source code 

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: Element
self

nsdeclarations(self)

source code 

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

Returns: basestring
A separated list of declarations.

plain(self)

source code 

Get a string representation of this XML fragment.

Returns: basestring
A plain string.

promotePrefixes(self)

source code 

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: Element
self

qname(self)

source code 

Get the fully qualified name of this element

Returns: basestring
The fully qualified name.

refitPrefixes(self)

source code 

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

Returns: Element
self

remove(self, child)

source code 

Remove the specified child element or attribute.

Parameters:
Returns: Element|None
The detached child when child is an element, else None.

rename(self, name)

source code 

Rename the element.

Parameters:
  • name (basestring) - A new name for the element.

replaceChild(self, child, content)

source code 

Replace child with the specified content.

Parameters:
  • child (Element) - A child element.
  • content (Element or [Element,]) - An element or collection of elements.

resolvePrefix(self, prefix, default=(None, None))

source code 

Resolve the specified prefix to a namespace. The nsprefixes is searched. If not found, it walks 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: (prefix,URI)
The namespace that is mapped to prefix in this context.

set(self, name, value)

source code 

Set an attribute's value.

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

See Also: __setitem__()

setPrefix(self, p, u=None)

source code 

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: Element
self

setText(self, value)

source code 

Set the element's Text content.

Parameters:
  • value (basestring) - The element's text value.
Returns: Element
self

setnil(self, flag=True)

source code 

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

Parameters:
  • flag (boolean) - A flag inidcating how xsi:nil will be set.
Returns: Element
self

str(self, indent=0)

source code 

Get a string representation of this XML fragment.

Parameters:
  • indent (int) - The indent to be used in formatting the output.
Returns: basestring
A pretty string.

trim(self)

source code 

Trim leading and trailing whitespace.

Returns: Element
self

unset(self, name)

source code 

Unset (remove) an attribute.

Parameters:
  • name (str) - The attribute name.
Returns: Element
self

updatePrefix(self, p, u)

source code 

Update (redefine) a prefix mapping for the branch.

Parameters:
  • p (basestring) - A prefix.
  • u (basestring) - A namespace URI.
Returns: Element
self

Note: This method traverses down the entire branch!

walk(self, visitor)

source code 

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

Parameters:
  • visitor - A function.
Returns: Element
self

Class Variable Details [hide private]

matcher

A collection of lambda for string matching.
Value:
{'eq': lambda a, b: a== b, 'startswith': lambda a, b: a.startswith(b),\
 'endswith': lambda a, b: a.endswith(b), 'contains': lambda a, b: b in\
 a}