Parse an XML document into an xml4h-wrapped DOM representation using an underlying XML library implementation.
Parameters: |
|
---|---|
Returns: | an xml4h.nodes.Document node representing the parsed document. |
Delegates to an adapter’s parse_string() or parse_file() implementation.
Return a Builder that represents an element in a new or existing XML DOM and provides “chainable” methods focussed specifically on adding XML content.
Parameters: |
|
---|---|
Returns: | a Builder instance that represents an Element node in an XML DOM. |
The best adapter available in the Python environment. This adapter is the default when parsing or creating XML documents, unless overridden by passing a specific adapter class.
alias of XmlDomImplAdapter
Builder is a utility class that makes it easy to create valid, well-formed XML documents using relatively sparse python code. The builder class works by wrapping an xml4h.nodes.Element node to provide “chainable” methods focussed specifically on adding XML content.
Each method that adds content returns a Builder instance representing the current or the newly-added element. Behind the scenes, the builder uses the xml4h.nodes node traversal and manipulation methods to add content directly to the underlying DOM.
You will not generally create Builder instances directly, but will instead call the xml4h.builder() method with the name for a new root element or with an existing xml4h.nodes.Element node.
Builder class that wraps an xml4h.nodes.Element node with methods for adding XML content to an underlying DOM.
Alias of attributes()
Add one or more attributes to the xml4h.nodes.Element node represented by this Builder.
Returns: | the current Builder. |
---|
Delegates to xml4h.nodes.Element.set_attributes().
Alias of attributes()
Add a CDATA node to the xml4h.nodes.Element node represented by this Builder.
Returns: | the current Builder. |
---|
Delegates to xml4h.nodes.Element.add_cdata().
Clone a node from another document to become a child of the xml4h.nodes.Element node represented by this Builder.
Returns: | a new Builder that represents the current element (not the cloned node). |
---|
Delegates to xml4h.nodes.Node.clone_node().
Add a coment node to the xml4h.nodes.Element node represented by this Builder.
Returns: | the current Builder. |
---|
Delegates to xml4h.nodes.Element.add_comment().
Returns: | the xml4h.nodes.Document node that contains the element represented by this Builder. |
---|
Returns: | the xml4h.nodes.Element node represented by this Builder. |
---|
Add a child element to the xml4h.nodes.Element node represented by this Builder.
Returns: | a new Builder that represents the child element. |
---|
Delegates to xml4h.nodes.Element.add_element().
Find descendants of the element represented by this builder that match the given constraints.
Returns: | a list of xml4h.nodes.Element nodes |
---|
Delegates to xml4h.nodes.Node.find()
Find nodes in this element’s owning xml4h.nodes.Document that match the given constraints.
Returns: | a list of xml4h.nodes.Element nodes |
---|
Delegates to xml4h.nodes.Node.find_doc().
Alias of processing_instruction()
Alias of processing_instruction()
Set the namespace prefix of the xml4h.nodes.Element node represented by this Builder.
Returns: | the current Builder. |
---|
Delegates to xml4h.nodes.Element.set_ns_prefix().
Add a processing instruction node to the xml4h.nodes.Element node represented by this Builder.
Returns: | the current Builder. |
---|
Delegates to xml4h.nodes.Element.add_instruction().
Returns: | the xml4h.nodes.Element root node ancestor of the element represented by this Builder |
---|
Add a text node to the xml4h.nodes.Element node represented by this Builder.
Returns: | the current Builder. |
---|
Delegates to xml4h.nodes.Element.add_text().
Transplant a node from another document to become a child of the xml4h.nodes.Element node represented by this Builder.
Returns: | a new Builder that represents the current element (not the transplanted node). |
---|
Delegates to xml4h.nodes.Node.transplant_node().
Returns: | a builder representing an ancestor of the current element, by default the parent element. |
---|---|
Parameters: |
|
Write XML text for the element represented by this builder.
Delegates to xml4h.nodes.Node.write().
Write XML text for the Document containing the element represented by this builder.
Delegates to xml4h.nodes.Node.write_doc().
Writer to serialize XML DOM documents or sections to text.
Serialize an xml4h DOM node and its descendants to text, writing the output to a given writer or to stdout.
Parameters: |
|
---|
Node representing an attribute of a Document or Element node.
Dictionary-like object of element attributes that always reflects the state of the underlying element node, and that allows for in-place modifications that will immediately affect the element.
list of weak references to the object (if defined)
Parameters: | name (string) – the name of an attribute to look up. |
---|---|
Returns: | the namespace URI associated with the named attribute, or None. |
Node representing character data in an XML document.
Node representing an XML document fragment.
Node representing the type of an XML document.
Node representing an element in an XML document, with support for manipulating and adding content to the element.
Add a character data node to this element.
Parameters: | data (string) – text content to add as character data. |
---|
Add a comment node to this element.
Parameters: | text (string) – text content to add as a comment. |
---|
Add a new child element to this element, with an optional namespace definition. If no namespace is provided the child will be assigned to the default namespace.
Parameters: |
|
---|---|
Returns: | the new child as a an Element node. |
Add an instruction node to this element.
Parameters: | text (string) – text content to add as an instruction. |
---|
Add a text node to this element.
Adding text with this method is subtly different from assigning a new text value with text() accessor, because it “appends” to rather than replacing this element’s set of text nodes.
Parameters: |
|
---|
Alias of set_attributes()
Parameters: |
|
---|---|
Returns: | this element’s attributes that match ns_uri as Attribute nodes. |
Get or set this element’s attributes as name/value pairs.
Note
Setting element attributes via this accessor will remove any existing attributes, as opposed to the set_attributes() method which only updates and replaces them.
Alias of set_attributes()
Returns: | a Builder representing this element with convenience methods for adding XML content. |
---|
Add or update this element’s attributes, where attributes can be specified in a number of ways.
Parameters: |
|
---|
Node representing an entity reference in an XML document.
Provide methods to access node name and value attributes, where the node name may also be composed of “prefix” and “local” components.
Base class for xml4h DOM nodes that represent and interact with a node in the underlying XML implementation.
URI constant for XMLNS
Construct an object that represents and wraps a DOM node in the underlying XML implementation.
Parameters: |
|
---|
list of weak references to the object (if defined)
Convert a list of underlying implementation nodes into a list of xml4h wrapper nodes.
Returns: | the xml4h.impls.XmlImplAdapter subclass implementation that mediates operations on the node in the underlying XML implementation. |
---|
Returns: | the class of the xml4h.impls.XmlImplAdapter subclass implementation that mediates operations on the node in the underlying XML implementation. |
---|
Returns: | the ancestors of this node in a list ordered by proximity to this node, that is: parent, grandparent, great-grandparent etc. |
---|
Returns: | the first child node matching the given constraints, or None if there are no matching child nodes. |
---|
Delegates to NodeList.filter().
Clone a node from another document to become a child of this node, by copying the node’s data into this document but leaving the node untouched in the source document. The node to be cloned can be a Node based on the same underlying XML library implementation and adapter, or a “raw” node from that implementation.
Parameters: | node (xml4h or implementation node) – the node in another document to clone. |
---|
Delete this node from the owning document.
Parameters: | destroy (bool) – if True the child node will be destroyed in addition to being removed from the document. |
---|---|
Returns: | the removed child node, or None if the child was destroyed. |
Returns: | the Document node that contains this node, or self if this node is the document. |
---|
Find Element node descendants of this node, with optional constraints to limit the results.
Parameters: |
|
---|---|
Returns: | a list of Element nodes matching any given constraints, or a single node if first_only=True. |
Find Element node descendants of the document containing this node, with optional constraints to limit the results.
Delegates to find() applied to this node’s owning document.
Find the first Element node descendant of this node that matches any optional constraints, or None if there are no matching elements.
Delegates to find() with first_only=True.
Returns: | True if a named feature is supported by the adapter implementation underlying this node. |
---|
Returns: | the document object from the underlying XML implementation that contains the node represented by this xml4h node. |
---|
Returns: | the node object from the underlying XML implementation that is represented by this xml4h node. |
---|
Returns: | True if this is a DocumentFragment node. |
---|
Returns: | True if this is a DocumentType node. |
---|
Returns: | True if this is an EntityReference node. |
---|
Returns: | True if this is a ProcessingInstruction node. |
---|
Returns: | an int constant value that identifies the type of this node, such as ELEMENT_NODE or TEXT_NODE. |
---|
Alias for namespace_uri()
Returns: | the root Element node of the document that contains this node, or self if this node is the root element. |
---|
Returns: | a list of this node’s siblings that occur after this node in the DOM. |
---|
Returns: | a list of this node’s siblings that occur before this node in the DOM. |
---|
Transplant a node from another document to become a child of this node, removing it from the source document. The node to be transplanted can be a Node based on the same underlying XML library implementation and adapter, or a “raw” node from that implementation.
Parameters: | node (xml4h or implementation node) – the node in another document to transplant. |
---|
Serialize this node and its descendants to text, writing the output to a given writer or to stdout.
Parameters: |
|
---|
Delegates to xml4h.writer.write_node() applied to this node.
Perform “magical” lookup of a node’s attributes via dict-style keyword reference, and child elements via class attribute reference.
Retrieve this node’s child element by tag name regardless of the elements namespace, assuming the name given doesn’t match an existing attribute of this class.
Parameters: | child_name (string) – tag name of the child element. The name must match the following pattern rules for xml4h to attempt a child element lookup, otherwise an AttributeError will be raised immediately:
|
---|---|
Returns: | the type of the return value depends on how many child elements match the name: |
Raise : | AttributeError if the node has no child element with the given name, or if the given name does not match the required pattern. |
Retrieve this node’s attribute value by name using dict-style keyword lookup.
Parameters: | attr_name (string) – name of the attribute. If the attribute has a namespace prefix that must be included, in other words the name must be a qname not local name. |
---|---|
Raise : | KeyError if the node has no such attribute. |
list of weak references to the object (if defined)
Custom implementation for Node lists that provides additional functionality, such as node filtering.
Alias for filter().
list of weak references to the object (if defined)
Apply filters to the set of nodes in this list.
Parameters: |
|
---|---|
Returns: | the type of the return value depends on the value of the first_only parameter and how many nodes match the filter: |
Node representing a processing instruction in an XML document.
Get or set the value of a node.
Provide xpath() method to nodes that support XPath searching.
list of weak references to the object (if defined)
Perform an XPath query on the current node.
Parameters: |
|
---|---|
Returns: | results of the query as a list of Node objects, or a list of base type objects if the XPath query does not reference node objects. |
Base class that defines how xml4h interacts with an underlying XML library that the adaptor “wraps” to provide additional (or at least different) functionality.
This class should be treated as an abstract class. It provides some common implementation code used by all xml4h adapter implementations, but mostly it sketches out the methods the real implementaiton subclasses must provide.
Returns: | element node descendents of the given node that match the search constraints. |
---|---|
Parameters: |
|
Return a three-element tuple with the prefix, local name, and namespace URI for the given element/attribute name (in the context of the given node’s hierarchy). If the name has no associated prefix or namespace information, None is return for those tuple members.
Returns: | True if a named feature is supported by this adapter. |
---|
Adapter to the lxml XML library implementation.
Returns: | element node descendents of the given node that match the search constraints. |
---|---|
Parameters: |
|
Return result of performing the given XPath query on the given node.
All known namespace prefix-to-URI mappings in the document are automatically included in the XPath invocation.
If an empty/default namespace (i.e. None) is defined, this is converted to the prefix name ‘_’ so it can be used despite empty namespace prefixes being unsupported by XPath.
Custom xml4h exceptions.
User has attempted to use a feature that is available in some xml4h implementations/adapters, but is not available in the current one.