XML Class

Properties Methods Events Configuration Settings Errors

The XML class can be used to both parse and create XML documents.

Syntax

class ipworks.XML

Remarks

The XML class can operate as either a parser of writer of XML.

Parsing XML

The XML class parses XML documents and verifies that they are well-formed. The results are provided through a set of events complying with the SAX2 specification.

In addition, the document structure may be queried through an x_path mechanism that supports a subset of the XPath specification.

The parser is optimized for read applications, with a very fast engine that builds internal DOM structures with close to zero heap allocations. Additionally, build_dom can be set to False which reduces the overhead of creating the DOM and offers a fast forward-only parsing implementation which fires events to provide the parsed data.

When parsing a document events will fire to provide information about the parsed data. After parse returns the document may be navigated by setting x_path if build_dom is True (default). If build_dom is False parsed data is only accessible through the events.

Events are fired only when qualifying conditions (such as, for example, the beginning of a new element) are met. In the meantime, text will be buffered internally. The following events will fire during parsing:

If build_dom is True (default), x_path may be set after this method returns. x_path implements a subset of the XML XPath specification, allowing you to point to specific elements in the XML documents.

The path is a series of one or more element accessors separated by '/'. The path can be absolute (starting with '/') or relative to the current x_path location.

The following are possible values for an element accessor:


'name'	A particular element name
name[i]	The i-th subelement of the current element with the given name
[i]	The i-th subelement of the current element
[last()]	The last subelement of the current element
[last()-i]	The subelement located at the last location minus i in the current element
name[@attrname="attrvalue"]	The subelement containing a particular value for a given attribute (supports single AND double quotes)
..	The parent of the current element

When x_path is set to a valid path, x_element points to the name of the element, with x_parent, x_namespace, x_prefix, x_child_name, x_child_namespace, x_child_prefix, x_child_x_text, and x_text providing other properties of the element. The attributes of the current element are provided in the attr_name, attr_namespace, attr_prefix, and attr_value properties.

build_dom must be set to True prior to parsing the document for the x_path functionality to be available.

Example (Setting XPath):


Document root	XML.XPath = "/"
Specific Element	XML.XPath = "/root/SubElement1/SubElement2/"
i-th Child	XML.XPath = "/root/SubElement1[i]"

Input Properties

The class will determine the source of the input based on which properties are set.

The order in which the input properties are checked is as follows:

When a valid source is found the search stops.

If parsing multiple documents call reset between documents to reset the parser.

An additional "relaxed" mode allows for lexical parsing of non-XML documents (e.g. HTML). This is enabled by setting validate to False. In this case, events will be fired as elements, entities, etc. are encountered, but the structure of the document will not be checked for "well-formedness", and the internal DOM structure will not be built.

Writing XML

To use the class first decide whether or not to write to file, or to output_data.

Output Properties

The class will determine the destination of the output based on which properties are set.

The order in which the output properties are checked is as follows:

output_file
output_data: The output data is written to this property if no other destination is specified.

To begin writing the XML document first optionally set xml_declaration. If this is not set the class will use a default XML declaration at the beginning of the document.

Next begin adding elements to your document. Calling start_element will open an element with the specified name. To create a nested structure continue calling start_element to open more child elements. To write a value within an element call put_string. To close the element that was last opened call end_element. Each time end_element is called the element at the current level is closed. Alternatively, calling put_element will write the element specified with the value specified and will also close the element.

To write an attribute of the current element, after calling start_element call put_attr. Call put_attr multiple times to add multiple attributes.

Writing comments or CDATA can be done at any time with the put_comment and put_c_data methods.

To close your XML document call save. You can call save from any location and it will close any remaining open elements automatically.

Property List

The following is the full list of the properties of the class with short descriptions. Click on the links for further details.


build_dom	When True, an internal object model of the XML document is created.
input_data	The XML data to parse.
input_file	The file to process.
namespace_count	The number of records in the Namespace arrays.
namespace_prefix	The Prefix for the Namespace .
namespace_uri	Namespace URI associated with the corresponding Prefix .
output_data	The output XML after processing.
output_file	The path to a local file where the output will be written.
overwrite	Indicates whether or not the class should overwrite files.
validate	When True, the parser checks that the document consists of well-formed XML.
attr_count	The number of records in the Attr arrays.
attr_name	The Name provides the local name (without prefix) of the attribute.
attr_namespace	Attribute namespace.
attr_prefix	Attribute prefix (if any).
attr_value	Attribute value.
x_child_count	The number of records in the XChild arrays.
x_child_name	The Name property provides the local name (without prefix) of the element.
x_child_namespace	Namespace of the element.
x_child_prefix	Prefix of the element (if any).
x_child_x_text	The inner text of the element.
x_comment_count	The number of records in the XComment arrays.
x_comment_text	This property holds the comment text.
x_element	The name of the current element.
xml_declaration_encoding	This property specifies the XML encoding to use.
xml_declaration_standalone	This property indicates whether the standalone attribute is present in the declaration with a value of true.
xml_declaration_version	This property specifies the XML version.
x_namespace	The namespace of the current element.
x_parent	The parent of the current element.
x_path	Provides a way to point to a specific element in the document.
x_prefix	The prefix of the current element.
x_sub_tree	A snapshot of the current element in the document.
x_text	The text of the current element.

Method List

The following is the full list of the methods of the class with short descriptions. Click on the links for further details.


config	Sets or retrieves a configuration setting.
end_element	Writes the closing tag of an open XML element.
flush	Flushes the parser and checks its end state.
get_attr	Returns the value of the specified attribute.
has_x_path	Determines whether a specific element exists in the document.
load_dom	Loads the DOM from a file.
load_schema	Load the XML schema.
parse	This method parses the specified XML data.
put_attr	Writes an XML attribute.
put_c_data	Writes an XML CDATA block.
put_comment	Writes an XML comment block.
put_element	Writes a simple XML element with a value.
put_raw	Writes a raw XML fragment.
put_string	Writes text inside an XML element.
remove_attr	Remove a attribute.
remove_children	Removes the children of the elment as the specified XPath.
remove_element	Removes the elment as the specified XPath.
reset	Resets the parser.
save	Closes the class writing stream.
save_dom	Saves the DOM to a file.
start_element	Writes the opening tag of an XML element.
try_x_path	Navigates to the specified XPath if it exists.

Event List

The following is the full list of the events fired by the class with short descriptions. Click on the links for further details.


on_characters	Fired for plain text segments of the input stream.
on_comment	Fired when a comment section is encountered.
on_end_element	Fired when an end-element tag is encountered.
on_end_prefix_mapping	Fired when leaving the scope of a namespace declaration.
on_error	Information about errors during data delivery.
on_eval_entity	Fired every time an entity needs to be evaluated.
on_ignorable_whitespace	Fired when a section of ignorable whitespace is encountered.
on_meta	Fired when a meta section is encountered.
on_pi	Fired when a processing instruction section is encountered.
on_special_section	Fired when a special section is encountered.
on_start_element	Fired when a begin-element tag is encountered in the document.
on_start_prefix_mapping	Fired when entering the scope of a namespace declaration.
on_xml	Fires as XML is written.

Configuration Settings

The following is a list of configuration settings for the class with short descriptions. Click on the links for further details.


CacheContent	If true, the original XML is saved in a buffer.
Charset	Specifies the charset used when encoding data.
EOL	The characters to use for separating lines.
ErrorOnEmptyAttr	If true, passing an invalid attribute to the Attr method will throw an exception.
ExtraNameChars	Extra characters for the parser to consider as name characters.
ExtraSpaceChars	Extra characters for the parser to consider as white space.
FlushOnEOL	If set, the parser flushes its text buffer after every line of text.
IgnoreBadAttributePrefixes	If true, bad (unknown) attribute prefixes are ignored.
IgnoreBadElementPrefixes	If true, bad (unknown) element prefixes are ignored.
IncludeElementPrefix	Whether to include the prefix in the element name.
IncludeXMLDeclaration	Whether to include the XML declaration when writing XML.
Indent	The characters to use for each indentation level.
Offset	Current offset of the document being parsed.
PreserveWhitespace	If true, leading and trailing whitespace in element text is preserved.
QuoteChar	Quote character to use for attribute values.
StringProcessingOptions	Defines options to use when processing string values.
BuildInfo	Information about the product's build.
CodePage	The system code page used for Unicode to Multibyte translations.
LicenseInfo	Information about the current license.
ProcessIdleEvents	Whether the class uses its internal event loop to process events when the main thread is idle.
SelectWaitMillis	The length of time in milliseconds the class will wait when DoEvents is called if there are no events to process.
UseInternalSecurityAPI	Tells the class whether or not to use the system security libraries or an internal implementation.

IPWorks 2020 Python Edition