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
param filters: one or more callable objects that should be applied as filters return: the filtered stream rtype: Stream render(self, method=None, encoding='utf-8', out=None, **kwargs)
Return a string representation of the stream.
Any additional keyword arguments are passed to the serializer, and thus depend on the method parameter value.
param method: determines how the stream is serialized; can be either "xml", "xhtml", "html", "text", or a custom serializer class; if None, the default serialization method of the stream is used param encoding: how the output string should be encoded; if set to None, this method returns a unicode object param out: a file-like object that the output should be written to instead of being returned as one big string; note that if this is a file or socket (or similar), the encoding must not be None (that is, the output must be encoded) return: a str or unicode object (depending on the encoding parameter), or None if the out parameter is provided rtype: basestring see: XMLSerializer, XHTMLSerializer, HTMLSerializer, TextSerializer note: Changed in 0.5: added the out parameter select(self, path, namespaces=None, variables=None)
Return a new stream that contains the events matching the given XPath expression.
>>> from genshi import HTML >>> stream = HTML('<doc><elem>foo</elem><elem>bar</elem></doc>') >>> print stream.select('elem') <elem>foo</elem><elem>bar</elem> >>> print stream.select('elem/text()') foobar
Note that the outermost element of the stream becomes the context node for the XPath test. That means that the expression "doc" would not match anything in the example above, because it only tests against child elements of the outermost element:
>>> print stream.select('doc') <BLANKLINE>
You can use the "." expression to match the context node itself (although that usually makes little sense):
>>> print stream.select('.') <doc><elem>foo</elem><elem>bar</elem></doc>
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 rtype: Stream 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.
Any additional keyword arguments are passed to the serializer, and thus depend on the method parameter value.
param method: determines how the stream is serialized; can be either "xml", "xhtml", "html", "text", or a custom serializer class; if None, the default serialization method of the stream is used return: an iterator over the serialization results (Markup or unicode objects, depending on the serialization method) rtype: iterator see: XMLSerializer, XHTMLSerializer, HTMLSerializer, TextSerializer
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 rtype: object 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))
return: a TEXT event rtype: tuple
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 rtype: Markup 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'"1 < 2"'>
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 < 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 rtype: Markup unescape(self)
Reverse-escapes &, <, >, and " and returns a unicode object.
>>> Markup('1 < 2').unescape() u'1 < 2'
return: the unescaped string rtype: unicode 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 (&, ', >, < and ") are not stripped.
return: a Markup instance with entities removed rtype: Markup see: genshi.util.stripentities striptags(self)
Return a copy of the text with all XML/HTML tags removed.
return: a Markup instance with all tags removed rtype: Markup 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, it is returned unchanged.
>>> unescape('1 < 2') '1 < 2'
param text: the text to unescape return: the unescsaped string rtype: unicode 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-uri}local-name. 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'