genshi.core

Core classes for markup processing.

StreamEventKind

A kind of event on a markup stream.

Stream

Represents a stream of markup events.

This class is basically an iterator over the events.

Stream events are tuples of the form:

(kind, data, position)

where kind is the event kind (such as START, END, TEXT, etc), data depends on the kind of event, and position is a (filename, line, offset) tuple that contains the location of the original element or text in the input. If the original location is unknown, position is (None, -1, -1).

Also provided are ways to serialize the stream to text. The serialize() method will return an iterator over generated strings, while render() returns the complete generated text at once. Both accept various parameters that impact the way the stream is serialized.

filter(self, *filters)

Apply filters to the stream.

This method returns a new stream with the given filters applied. The filters must be callables that accept the stream object as parameter, and return the filtered stream.

The call:

stream.filter(filter1, filter2)

is equivalent to:

stream | filter1 | filter2

render(self, method='xml', encoding='utf-8', **kwargs)

Return a string representation of the stream.

param method:	determines how the stream is serialized; can be either "xml", "xhtml", "html", "text", or a custom serializer class
param encoding:	how the output string should be encoded; if set to None, this method returns a unicode object

Any additional keyword arguments are passed to the serializer, and thus depend on the method parameter value.

see:	XMLSerializer.__init__, XHTMLSerializer.__init__, HTMLSerializer.__init__, TextSerializer.__init__

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

Return a new stream that contains the events matching the given XPath expression.

param path:	a string containing the XPath expression
param namespaces:
	mapping of namespace prefixes used in the path
param variables:
	mapping of variable names to values
return:	the selected substream
raises PathSyntaxError:
	if the given path expression is invalid or not supported

serialize(self, method='xml', **kwargs)

Generate strings corresponding to a specific serialization of the stream.

Unlike the render() method, this method is a generator that returns the serialized output incrementally, as opposed to returning a single string.

param method:	determines how the stream is serialized; can be either "xml", "xhtml", "html", "text", or a custom serializer class

Any additional keyword arguments are passed to the serializer, and thus depend on the method parameter value.

see:	XMLSerializer.__init__, XHTMLSerializer.__init__, HTMLSerializer.__init__, TextSerializer.__init__

Attrs

Immutable sequence type that stores the attributes of an element.

Ordering of the attributes is preserved, while access by name is also supported.

>>> attrs = Attrs([('href', '#'), ('title', 'Foo')])
>>> attrs
Attrs([('href', '#'), ('title', 'Foo')])

>>> 'href' in attrs
True
>>> 'tabindex' in attrs
False
>>> attrs.get('title')
'Foo'

Instances may not be manipulated directly. Instead, the operators | and - can be used to produce new instances that have specific attributes added, replaced or removed.

To remove an attribute, use the - operator. The right hand side can be either a string or a set/sequence of strings, identifying the name(s) of the attribute(s) to remove:

>>> attrs - 'title'
Attrs([('href', '#')])
>>> attrs - ('title', 'href')
Attrs()

The original instance is not modified, but the operator can of course be used with an assignment:

>>> attrs
Attrs([('href', '#'), ('title', 'Foo')])
>>> attrs -= 'title'
>>> attrs
Attrs([('href', '#')])

To add a new attribute, use the | operator, where the right hand value is a sequence of (name, value) tuples (which includes Attrs instances):

>>> attrs | [('title', 'Bar')]
Attrs([('href', '#'), ('title', 'Bar')])

If the attributes already contain an attribute with a given name, the value of that attribute is replaced:

>>> attrs | [('href', 'http://example.org/')]
Attrs([('href', 'http://example.org/')])

get(self, name, default=None)

Return the value of the attribute with the specified name, or the value of the default parameter if no such attribute is found.

param name:	the name of the attribute
param default:	the value to return when the attribute does not exist
return:	the attribute value, or the default value if that attribute does not exist

totuple(self)

Return the attributes as a markup event.

The returned event is a TEXT event, the data is the value of all attributes joined together.

>>> Attrs([('href', '#'), ('title', 'Foo')]).totuple()
('TEXT', u'#Foo', (None, -1, -1))

Markup

Marks a string as being safe for inclusion in HTML/XML output without needing to be escaped.

join(self, seq, escape_quotes=True)

Return a Markup object which is the concatenation of the strings in the given sequence, where this Markup object is the separator between the joined elements.

Any element in the sequence that is not a Markup instance is automatically escaped.

param seq:	the sequence of strings to join
param escape_quotes:
	whether double quote characters in the elements should be escaped
return:	the joined Markup object
see:	escape

escape(cls, text, quotes=True)

Create a Markup instance from a string and escape special characters it may contain (<, >, & and ").

>>> escape('"1 < 2"')
<Markup u'&#34;1 &lt; 2&#34;'>

If the quotes parameter is set to False, the " character is left as is. Escaping quotes is generally only required for strings that are to be used in attribute values.

>>> escape('"1 < 2"', quotes=False)
<Markup u'"1 &lt; 2"'>

param text:	the text to escape
param quotes:	if True, double quote characters are escaped in addition to the other special characters
return:	the escaped Markup string
see:	genshi.core.escape

unescape(self)

Reverse-escapes &, <, >, and " and returns a unicode object.

>>> Markup('1 < 2').unescape()
u'1 < 2'

see:	genshi.core.unescape

stripentities(self, keepxmlentities=False)

Return a copy of the text with any character or numeric entities replaced by the equivalent UTF-8 characters.

If the keepxmlentities parameter is provided and evaluates to True, the core XML entities (&amp;, &apos;, &gt;, &lt; and &quot;) are not stripped.

see:	genshi.util.stripentities

striptags(self)

Return a copy of the text with all XML/HTML tags removed.

see:	genshi.util.striptags

unescape(text)

Reverse-escapes &, <, >, and " and returns a unicode object.

>>> unescape(Markup('1 < 2'))
u'1 < 2'

If the provided text object is not a Markup instance, the text is returned as-is.

>>> unescape('1 < 2')
'1 < 2'

param text:	the text to unescape

Namespace

Utility class creating and testing elements with a namespace.

Internally, namespace URIs are encoded in the QName of any element or attribute, the namespace URI being enclosed in curly braces. This class helps create and test these strings.

A Namespace object is instantiated with the namespace URI.

>>> html = Namespace('http://www.w3.org/1999/xhtml')
>>> html
<Namespace "http://www.w3.org/1999/xhtml">
>>> html.uri
u'http://www.w3.org/1999/xhtml'

The Namespace object can than be used to generate QName objects with that namespace:

>>> html.body
QName(u'http://www.w3.org/1999/xhtml}body')
>>> html.body.localname
u'body'
>>> html.body.namespace
u'http://www.w3.org/1999/xhtml'

The same works using item access notation, which is useful for element or attribute names that are not valid Python identifiers:

>>> html['body']
QName(u'http://www.w3.org/1999/xhtml}body')

A Namespace object can also be used to test whether a specific QName belongs to that namespace using the in operator:

>>> qname = html.body
>>> qname in html
True
>>> qname in Namespace('http://www.w3.org/2002/06/xhtml2')
False

QName

A qualified element or attribute name.

The unicode value of instances of this class contains the qualified name of the element or attribute, in the form {namespace}localname. The namespace URI can be obtained through the additional namespace attribute, while the local name can be accessed through the localname attribute.

>>> qname = QName('foo')
>>> qname
QName(u'foo')
>>> qname.localname
u'foo'
>>> qname.namespace

>>> qname = QName('http://www.w3.org/1999/xhtml}body')
>>> qname
QName(u'http://www.w3.org/1999/xhtml}body')
>>> qname.localname
u'body'
>>> qname.namespace
u'http://www.w3.org/1999/xhtml'

---

See ApiDocs/0.4.x, Documentation