genshi.path

Basic support for evaluating XPath expressions against streams.

>>> from genshi.input import XML
>>> doc = XML('''<doc>
...  <items count="4">
...       <item status="new">
...         <summary>Foo</summary>
...       </item>
...       <item status="closed">
...         <summary>Bar</summary>
...       </item>
...       <item status="closed" resolution="invalid">
...         <summary>Baz</summary>
...       </item>
...       <item status="closed" resolution="fixed">
...         <summary>Waz</summary>
...       </item>
...   </items>
... </doc>''')
>>> print doc.select('items/item[@status="closed" and '
...     '(@resolution="invalid" or not(@resolution))]/summary/text()')
BarBaz

Because the XPath engine operates on markup streams (as opposed to tree structures), it only implements a subset of the full XPath 1.0 language.

Axis

Defines constants for the various supported XPath axes.

forname(cls, name)

Return the axis constant for the given name, or None if no such axis was defined.

Path

Implements basic XPath support on streams.

Instances of this class represent a "compiled" XPath expression, and provide methods for testing the path against a stream, as well as extracting a substream matching that path.

select(self, stream, namespaces=None, variables=None)

Returns a substream of the given stream that matches the path.

If there are no matches, this method returns an empty stream.

>>> from genshi.input import XML
>>> xml = XML('<root><elem><child>Text</child></elem></root>')

>>> print Path('.//child').select(xml)
<child>Text</child>

>>> print Path('.//child/text()').select(xml)
Text

param stream:	the stream to select from
param namespaces:
	(optional) a mapping of namespace prefixes to URIs
param variables:
	(optional) a mapping of variable names to values
return:	the substream matching the path, or an empty stream
rtype:	Stream

test(self, ignore_context=False)

Returns a function that can be used to track whether the path matches a specific stream event.

The function returned expects the positional arguments event, namespaces and variables. The first is a stream event, while the latter two are a mapping of namespace prefixes to URIs, and a mapping of variable names to values, respectively. In addition, the function accepts an updateonly keyword argument that default to False. If it is set to True, the function only updates its internal state, but does not perform any tests or return a result.

If the path matches the event, the function returns the match (for example, a START or TEXT event.) Otherwise, it returns None.

>>> from genshi.input import XML
>>> xml = XML('<root><elem><child id="1"/></elem><child id="2"/></root>')
>>> test = Path('child').test()
>>> for event in xml:
...     if test(event, {}, {}):
...         print event[0], repr(event[1])
START (QName(u'child'), Attrs([(QName(u'id'), u'2')]))

param ignore_context:
	if True, the path is interpreted like a pattern in XSLT, meaning for example that it will match at any depth
return:	a function that can be used to test individual events in a stream against the path
rtype:	function

PathSyntaxError

Exception raised when an XPath expression is syntactically incorrect.

PathParser

Tokenizes and parses an XPath expression.

next_token(self)

(Not documented)

peek_token(self)

(Not documented)

parse(self)

Parses the XPath expression and returns a list of location path tests.

For union expressions (such as *|text()), this function returns one test for each operand in the union. For patch expressions that don't use the union operator, the function always returns a list of size 1.

Each path test in turn is a sequence of tests that correspond to the location steps, each tuples of the form (axis, testfunc, predicates)

as_scalar(value)

Convert value to a scalar. If a single element Attrs() object is passed the value of the single attribute will be returned.

as_float(value)

(Not documented)

as_long(value)

(Not documented)

as_string(value)

(Not documented)

as_bool(value)

(Not documented)

PrincipalTypeTest

Node test that matches any event with the given principal type.

QualifiedPrincipalTypeTest

Node test that matches any event with the given principal type in a specific namespace.

LocalNameTest

Node test that matches any event with the given principal type and local name.

QualifiedNameTest

Node test that matches any event with the given principal type and qualified name.

CommentNodeTest

Node test that matches any comment events.

NodeTest

Node test that matches any node.

ProcessingInstructionNodeTest

Node test that matches any processing instruction event.

TextNodeTest

Node test that matches any text event.

Function

Base class for function nodes in XPath expressions.

BooleanFunction

The boolean function, which converts its argument to a boolean value.

CeilingFunction

The ceiling function, which returns the nearest lower integer number for the given number.

ConcatFunction

The concat function, which concatenates (joins) the variable number of strings it gets as arguments.

ContainsFunction

The contains function, which returns whether a string contains a given substring.

MatchesFunction

The matches function, which returns whether a string matches a regular expression.

FalseFunction

The false function, which always returns the boolean false value.

FloorFunction

The ceiling function, which returns the nearest higher integer number for the given number.

LocalNameFunction

The local-name function, which returns the local name of the current element.

NameFunction

The name function, which returns the qualified name of the current element.

NamespaceUriFunction

The namespace-uri function, which returns the namespace URI of the current element.

NotFunction

The not function, which returns the negated boolean value of its argument.

NormalizeSpaceFunction

The normalize-space function, which removes leading and trailing whitespace in the given string, and replaces multiple adjacent whitespace characters inside the string with a single space.

NumberFunction

The number function that converts its argument to a number.

RoundFunction

The round function, which returns the nearest integer number for the given number.

StartsWithFunction

The starts-with function that returns whether one string starts with a given substring.

StringLengthFunction

The string-length function that returns the length of the given string.

SubstringFunction

The substring function that returns the part of a string that starts at the given offset, and optionally limited to the given length.

SubstringAfterFunction

The substring-after function that returns the part of a string that is found after the given substring.

SubstringBeforeFunction

The substring-before function that returns the part of a string that is found before the given substring.

TranslateFunction

The translate function that translates a set of characters in a string to target set of characters.

TrueFunction

The true function, which always returns the boolean true value.

Literal

Abstract base class for literal nodes.

StringLiteral

A string literal node.

NumberLiteral

A number literal node.

VariableReference

A variable reference node.

AndOperator

The boolean operator and.

EqualsOperator

The equality operator =.

NotEqualsOperator

The equality operator !=.

OrOperator

The boolean operator or.

GreaterThanOperator

The relational operator > (greater than).

GreaterThanOrEqualOperator

The relational operator >= (greater than or equal).

LessThanOperator

The relational operator < (less than).

LessThanOrEqualOperator

The relational operator <= (less than or equal).

---

See Using XPath in Genshi, ApiDocs/0.5.x, Documentation