Public XPath API

The package includes some classes and functions that implement XPath selectors, parsers, tokens, contexts and schema proxy.

XPath selectors

elementpath.select(root, path, namespaces=None, parser=None, **kwargs)

XPath selector function that apply a path expression on root Element.

Parameters:
  • root – An Element or ElementTree instance.
  • path – The XPath expression.
  • namespaces – A dictionary with mapping from namespace prefixes into URIs.
  • parser – The parser class to use, that is XPath2Parser for default.
  • kwargs – Other optional parameters for the XPath parser instance.
Returns:

A list with XPath nodes or a basic type for expressions based on a function or literal.

elementpath.iter_select(root, path, namespaces=None, parser=None, **kwargs)

A function that creates an XPath selector generator for apply a path expression on root Element.

Parameters:
  • root – An Element or ElementTree instance.
  • path – The XPath expression.
  • namespaces – A dictionary with mapping from namespace prefixes into URIs.
  • parser – The parser class to use, that is XPath2Parser for default.
  • kwargs – Other optional parameters for the XPath parser instance.
Returns:

A generator of the XPath expression results.

class elementpath.Selector(path, namespaces=None, parser=None, **kwargs)

XPath selector class. Create an instance of this class if you want to apply an XPath selector to several target data.

Parameters:
  • path – The XPath expression.
  • namespaces – A dictionary with mapping from namespace prefixes into URIs.
  • parser – The parser class to use, that is XPath2Parser for default.
  • kwargs – Other optional parameters for the XPath parser instance.
Variables:
  • path (str) – The XPath expression.
  • parser (XPath1Parser or XPath2Parser) – The parser instance.
  • root_token (XPathToken) – The root of tokens tree compiled from path.
namespaces

A dictionary with mapping from namespace prefixes into URIs.

select(root)

Applies the instance’s XPath expression on root Element.

Parameters:root – An Element or ElementTree instance.
Returns:A list with XPath nodes or a basic type for expressions based on a function or literal.
iter_select(root)

Creates an XPath selector generator for apply the instance’s XPath expression on root Element.

Parameters:root – An Element or ElementTree instance.
Returns:A generator of the XPath expression results.

XPath parsers

class elementpath.XPath1Parser(namespaces=None, variables=None, strict=True, *args, **kwargs)

XPath 1.0 expression parser class. A parser instance represents also the XPath static context. With variables you can pass a dictionary with the static context’s in-scope variables. Provide a namespaces dictionary argument for mapping namespace prefixes to URI inside expressions. If strict is set to False the parser enables also the parsing of QNames, like the ElementPath library.

Parameters:
  • namespaces – A dictionary with mapping from namespace prefixes into URIs.
  • variables – A dictionary with the static context’s in-scope variables.
  • strict – If strict mode is False the parser enables parsing of QNames in extended format, like the Python’s ElementPath library. Default is True.
DEFAULT_NAMESPACES = {'xml': 'http://www.w3.org/XML/1998/namespace'}

The default prefix-to-namespace associations of the XPath class. Those namespaces are updated in the instance with the ones passed with the namespaces argument.

version

The XPath version string.

default_namespace

The default namespace. For XPath 1.0 this value is always None because the default namespace is ignored (see https://www.w3.org/TR/1999/REC-xpath-19991116/#node-tests).

Helper methods for defining token classes:

classmethod axis(symbol, bp=80)

Register a token for a symbol that represents an XPath axis.

classmethod function(symbol, nargs=None, label='function', bp=90)

Registers a token class for a symbol that represents an XPath callable object. For default a callable labeled as function is registered but a different label can be provided.

class elementpath.XPath2Parser(namespaces=None, variables=None, strict=True, compatibility_mode=False, default_namespace=None, function_namespace=None, schema=None, base_uri=None, default_collation=None, documents=None, collections=None, default_collection=None)

XPath 2.0 expression parser class. This is the default parser used by XPath selectors. A parser instance represents also the XPath static context. With variables you can pass a dictionary with the static context’s in-scope variables. Provide a namespaces dictionary argument for mapping namespace prefixes to URI inside expressions. If strict is set to False the parser enables also the parsing of QNames, like the ElementPath library. There are some additional XPath 2.0 related arguments.

Parameters:
  • namespaces – a dictionary with mapping from namespace prefixes into URIs.
  • variables – a dictionary with the static context’s in-scope variables.
  • strict – if strict mode is False the parser enables parsing of QNames, like the ElementPath library. Default is True.
  • default_namespace – the default namespace to apply to unprefixed names. For default no namespace is applied (empty namespace ‘’).
  • function_namespace – the default namespace to apply to unprefixed function names. For default the namespace “http://www.w3.org/2005/xpath-functions” is used.
  • schema – the schema proxy class or instance to use for types, attributes and elements lookups. If an AbstractSchemaProxy subclass is provided then a schema proxy instance is built without the optional argument, that involves a mapping of only XSD builtin types. If it’s not provided the XPath 2.0 schema’s related expressions cannot be used.
  • base_uri – an absolute URI maybe provided, used when necessary in the resolution of relative URIs.
  • compatibility_mode – if set to True the parser instance works with XPath 1.0 compatibility rules.

XPath tokens

class elementpath.XPathToken(parser, value=None)

Base class for XPath tokens.

evaluate(context=None)

Evaluate default method for XPath tokens.

Parameters:context – The XPath dynamic context.
select(context=None)

Select operator that generates XPath results.

Parameters:context – The XPath dynamic context.

Context manipulation helpers:

get_argument(context, index=0, required=False, default_to_context=False, default=None, cls=None)

Get the argument value of a function of constructor token. A zero length sequence is converted to a None value. If the function has no argument returns the context’s item if the dynamic context is not None.

Parameters:
  • context – the dynamic context.
  • index – an index for select the argument to be got, the first for default.
  • required – if set to True missing or empty sequence arguments are not allowed.
  • default_to_context – if set to True then the item of the dynamic context is returned when the argument is missing.
  • default – the default value returned in case the argument is an empty sequence. If not provided returns None.
  • cls – if a type is provided performs a type checking on item.
atomization(context=None)

Helper method for value atomization of a sequence.

Ref: https://www.w3.org/TR/xpath20/#id-atomization

Parameters:context – the XPath context.
get_atomized_operand(context=None)

Get the atomized value for an XPath operator.

Parameters:context – the XPath context.
Returns:the atomized value of a single length sequence or None if the sequence is empty.
get_comparison_data(context)

Get comparison data couples for the general comparison of sequences. Different sequences maybe generated with an XPath 2.0 parser, depending on compatibility mode setting.

Ref: https://www.w3.org/TR/xpath20/#id-general-comparisons

Parameters:context – the XPath dynamic context.
Returns:a list of data couples.
get_results(context)

Returns formatted XPath results.

Parameters:context – the XPath dynamic context.
Returns:a list or a simple datatype when the result is a single simple type generated by a literal or function token.
get_operands(context, cls=None)

Returns the operands for a binary operator. Float arguments are converted to decimal if the other argument is a Decimal instance.

Parameters:
  • context – the XPath dynamic context.
  • cls – if a type is provided performs a type checking on item.
Returns:

a couple of values representing the operands. If any operand is not available returns a (None, None) couple.

adjust_datetime(context, cls)

XSD datetime adjust function helper.

Parameters:
  • context – the XPath dynamic context.
  • cls – the XSD datetime subclass to use.
Returns:

an empty list if there is only one argument that is the empty sequence or the adjusted XSD datetime instance.

match_xsd_type(schema_item, name)

Match a token with a schema type, checking the matching between the provided schema item and name. If there is a match and the token is already related with another schema type an exception is raised.

Parameters:
  • schema_item – an XPath item related with a schema instance.
  • name – a QName in extended format for matching the item.
Returns:

the matched XSD type or None if there isn’t a match.

use_locale(collation)

A context manager for use a locale setting for string comparison in a code block.

Data accessor helpers .. automethod:: data_value .. automethod:: boolean_value .. automethod:: string_value .. automethod:: number_value .. automethod:: schema_node_value

Error management helper:

error(code, message=None)

Returns an XPath error instance related with a code. An XPath/XQuery/XSLT error code is an alphanumeric token starting with four uppercase letters and ending with four digits.

Parameters:
  • code – the error code.
  • message – an optional custom additional message.

XPath contexts

class elementpath.XPathContext(root, item=None, position=0, size=1, axis=None, variables=None, current_dt=None, timezone=None, documents=None, collections=None, default_collection=None)

The XPath dynamic context. The static context is provided by the parser.

Usually the dynamic context instances are created providing only the root element. Variables argument is needed if the XPath expression refers to predefined variables. The other optional arguments are needed only if a specific position on the context is required, but have to be used with the knowledge of what is their meaning.

Parameters:
  • root – the root of the XML document, can be a ElementTree instance or an Element.
  • item – the context item. A None value means that the context is positioned on the document node.
  • position – the current position of the node within the input sequence.
  • size – the number of items in the input sequence.
  • axis – the active axis. Used to choose when apply the default axis (‘child’ axis).
  • variables – dictionary of context variables that maps a QName to a value.
  • current_dt – current dateTime of the implementation, including explicit timezone.
  • timezone – implicit timezone to be used when a date, time, or dateTime value does not have a timezone.
class elementpath.XPathSchemaContext(root, item=None, position=0, size=1, axis=None, variables=None, current_dt=None, timezone=None, documents=None, collections=None, default_collection=None)

The XPath dynamic context base class for schema bounded parsers. Use this class as dynamic context for schema instances in order to perform a schema-based type checking during the static analysis phase. Don’t use this as dynamic context on XML instances.

XML Schema proxy

The XPath 2.0 parser can be interfaced with an XML Schema processor through a schema proxy. An XMLSchemaProxy class is defined for interfacing schemas created with the xmlschema package. This class is based on an abstract class AbstractSchemaProxy, that can be used for implementing concrete interfaces to other types of XML Schema processors.

class elementpath.AbstractSchemaProxy(schema, base_element=None)

Abstract class for defining schema proxies.

Parameters:
  • schema – a schema instance that implements the AbstractEtreeElement interface.
  • base_element – the schema element used as base item for static analysis. It must implements the AbstractXsdElement interface.
bind_parser(parser)

Binds a parser instance with schema proxy adding the schema’s atomic types constructors. This method can be redefined in a concrete proxy to optimize schema bindings.

Parameters:parser – a parser instance.
get_context()

Get a context instance for static analysis phase.

Returns:an XPathSchemaContext instance.
find(path, namespaces=None)

Find a schema element or attribute using an XPath expression.

Parameters:
  • path – an XPath expression that selects an element or an attribute node.
  • namespaces – an optional mapping from namespace prefix to namespace URI.
Returns:

The first matching schema component, or None if there is no match.

get_type(qname)

Get the XSD global type from the schema’s scope. A concrete implementation must returns an object that implements the AbstractXsdType interface, or None if the global type is not found.

Parameters:qname – the fully qualified name of the type to retrieve.
Returns:an object that represents an XSD type or None.
get_attribute(qname)

Get the XSD global attribute from the schema’s scope. A concrete implementation must returns an object that implements the AbstractXsdAttribute interface, or None if the global attribute is not found.

Parameters:qname – the fully qualified name of the attribute to retrieve.
Returns:an object that represents an XSD attribute or None.
get_element(qname)

Get the XSD global element from the schema’s scope. A concrete implementation must returns an object that implements the AbstractXsdElement interface or None if the global element is not found.

Parameters:qname – the fully qualified name of the element to retrieve.
Returns:an object that represents an XSD element or None.
get_element(qname)

Get the XSD global element from the schema’s scope. A concrete implementation must returns an object that implements the AbstractXsdElement interface or None if the global element is not found.

Parameters:qname – the fully qualified name of the element to retrieve.
Returns:an object that represents an XSD element or None.
is_instance(obj, type_qname)

Returns True if obj is an instance of the XSD global type, False if not.

Parameters:
  • obj – the instance to be tested.
  • type_qname – the fully qualified name of the type used to test the instance.
cast_as(obj, type_qname)

Converts obj to the Python type associated with an XSD global type. A concrete implementation must raises a ValueError or TypeError in case of a decoding error or a KeyError if the type is not bound to the schema’s scope.

Parameters:
  • obj – the instance to be casted.
  • type_qname – the fully qualified name of the type used to convert the instance.
is_instance(obj, type_qname)

Returns True if obj is an instance of the XSD global type, False if not.

Parameters:
  • obj – the instance to be tested.
  • type_qname – the fully qualified name of the type used to test the instance.
iter_atomic_types()

Returns an iterator for not builtin atomic types defined in the schema’s scope. A concrete implementation must yields objects that implement the AbstractXsdType interface.

get_primitive_type(xsd_type)

Returns the primitive type of an XSD type.

Parameters:xsd_type – an XSD type instance.
Returns:an XSD builtin primitive type.

Exception classes

exception elementpath.ElementPathError(message, code=None, token=None)

Base exception class for elementpath package.

Parameters:
  • message – the message related to the error.
  • code – an optional error code.
  • token – an optional token instance related with the error.
exception elementpath.MissingContextError(message, code=None, token=None)

Raised when the dynamic context is required for evaluate the XPath expression.

Other exceptions

There are some exceptions derived from the base exception and Python built-in exceptions:

exception elementpath.ElementPathKeyError(message, code=None, token=None)
exception elementpath.ElementPathLocaleError(message, code=None, token=None)
exception elementpath.ElementPathNameError(message, code=None, token=None)
exception elementpath.ElementPathSyntaxError(message, code=None, token=None)
exception elementpath.ElementPathTypeError(message, code=None, token=None)
exception elementpath.ElementPathValueError(message, code=None, token=None)