Mercurial > genshi > mirror

annotate genshi/core.py @ 462:d5e2a7b58116 trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add lower-level serialization functions.
author cmlenz
date Thu, 26 Apr 2007 09:14:30 +0000
parents 75425671b437
children 700e7b47bf2b
rev   line source
1
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
1 # -*- coding: utf-8 -*-
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
2 #
408
4675d5cf6c67 Update copyright year for files modified this year.
cmlenz
parents: 403
diff changeset
3 # Copyright (C) 2006-2007 Edgewall Software
1
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
4 # All rights reserved.
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
5 #
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
6 # This software is licensed as described in the file COPYING, which
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
7 # you should have received as part of this distribution. The terms
230
84168828b074 Renamed Markup to Genshi in repository.
cmlenz
parents: 224
diff changeset
8 # are also available at http://genshi.edgewall.org/wiki/License.
1
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
9 #
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
10 # This software consists of voluntary contributions made by many
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
11 # individuals. For the exact contribution history, see the revision
230
84168828b074 Renamed Markup to Genshi in repository.
cmlenz
parents: 224
diff changeset
12 # history and logs, available at http://genshi.edgewall.org/log/.
1
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
13
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
14 """Core classes for markup processing."""
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
15
204
51d4101f49ca * Implement reverse add/mul operators for `Markup` class, so that the result is also a `Markup` instance.
cmlenz
parents: 200
diff changeset
16 import operator
397
31742fe6d47e * Moved some utility functions from `genshi.core` to `genshi.util` (backwards compatibility preserved via imports)
cmlenz
parents: 382
diff changeset
17
31742fe6d47e * Moved some utility functions from `genshi.core` to `genshi.util` (backwards compatibility preserved via imports)
cmlenz
parents: 382
diff changeset
18 from genshi.util import plaintext, stripentities, striptags
1
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
19
377
9aa6aa18fa35 Add `Attrs` class to `genshi.core.__all__`, so that it can be imported directly from the `genshi` package.
cmlenz
parents: 345
diff changeset
20 __all__ = ['Stream', 'Markup', 'escape', 'unescape', 'Attrs', 'Namespace',
9aa6aa18fa35 Add `Attrs` class to `genshi.core.__all__`, so that it can be imported directly from the `genshi` package.
cmlenz
parents: 345
diff changeset
21 'QName']
425
073640758a42 Try to use proper reStructuredText for docstrings throughout.
cmlenz
parents: 408
diff changeset
22 __docformat__ = 'restructuredtext en'
1
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
23
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
24
17
74cc70129d04 Refactoring to address #6: all match templates are now processed by a single filter, which means that match templates added by included templates are properly applied. A side effect of this refactoring is that `Context` objects may not be reused across multiple template processing runs.
cmlenz
parents: 10
diff changeset
25 class StreamEventKind(str):
397
31742fe6d47e * Moved some utility functions from `genshi.core` to `genshi.util` (backwards compatibility preserved via imports)
cmlenz
parents: 382
diff changeset
26 """A kind of event on a markup stream."""
279
a99666402b12 Some adjustments to make core data structures picklable (requires protocol 2).
cmlenz
parents: 278
diff changeset
27 __slots__ = []
a99666402b12 Some adjustments to make core data structures picklable (requires protocol 2).
cmlenz
parents: 278
diff changeset
28 _instances = {}
a99666402b12 Some adjustments to make core data structures picklable (requires protocol 2).
cmlenz
parents: 278
diff changeset
29
a99666402b12 Some adjustments to make core data structures picklable (requires protocol 2).
cmlenz
parents: 278
diff changeset
30 def __new__(cls, val):
a99666402b12 Some adjustments to make core data structures picklable (requires protocol 2).
cmlenz
parents: 278
diff changeset
31 return cls._instances.setdefault(val, str.__new__(cls, val))
1
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
32
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
33
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
34 class Stream(object):
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
35 """Represents a stream of markup events.
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
36
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
37 This class is basically an iterator over the events.
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
38
425
073640758a42 Try to use proper reStructuredText for docstrings throughout.
cmlenz
parents: 408
diff changeset
39 Stream events are tuples of the form::
397
31742fe6d47e * Moved some utility functions from `genshi.core` to `genshi.util` (backwards compatibility preserved via imports)
cmlenz
parents: 382
diff changeset
40
31742fe6d47e * Moved some utility functions from `genshi.core` to `genshi.util` (backwards compatibility preserved via imports)
cmlenz
parents: 382
diff changeset
41 (kind, data, position)
31742fe6d47e * Moved some utility functions from `genshi.core` to `genshi.util` (backwards compatibility preserved via imports)
cmlenz
parents: 382
diff changeset
42
425
073640758a42 Try to use proper reStructuredText for docstrings throughout.
cmlenz
parents: 408
diff changeset
43 where ``kind`` is the event kind (such as `START`, `END`, `TEXT`, etc),
073640758a42 Try to use proper reStructuredText for docstrings throughout.
cmlenz
parents: 408
diff changeset
44 ``data`` depends on the kind of event, and ``position`` is a
073640758a42 Try to use proper reStructuredText for docstrings throughout.
cmlenz
parents: 408
diff changeset
45 ``(filename, line, offset)`` tuple that contains the location of the
073640758a42 Try to use proper reStructuredText for docstrings throughout.
cmlenz
parents: 408
diff changeset
46 original element or text in the input. If the original location is unknown,
073640758a42 Try to use proper reStructuredText for docstrings throughout.
cmlenz
parents: 408
diff changeset
47 ``position`` is ``(None, -1, -1)``.
397
31742fe6d47e * Moved some utility functions from `genshi.core` to `genshi.util` (backwards compatibility preserved via imports)
cmlenz
parents: 382
diff changeset
48
1
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
49 Also provided are ways to serialize the stream to text. The `serialize()`
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
50 method will return an iterator over generated strings, while `render()`
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
51 returns the complete generated text at once. Both accept various parameters
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
52 that impact the way the stream is serialized.
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
53 """
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
54 __slots__ = ['events']
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
55
427
55c574767df2 More API documentation.
cmlenz
parents: 425
diff changeset
56 START = StreamEventKind('START') #: a start tag
55c574767df2 More API documentation.
cmlenz
parents: 425
diff changeset
57 END = StreamEventKind('END') #: an end tag
55c574767df2 More API documentation.
cmlenz
parents: 425
diff changeset
58 TEXT = StreamEventKind('TEXT') #: literal text
460
75425671b437 Apply patch by Alec Thomas for processing XML declarations (#111). Thanks!
cmlenz
parents: 438
diff changeset
59 XML_DECL = StreamEventKind('XML_DECL') #: XML declaration
427
55c574767df2 More API documentation.
cmlenz
parents: 425
diff changeset
60 DOCTYPE = StreamEventKind('DOCTYPE') #: doctype declaration
55c574767df2 More API documentation.
cmlenz
parents: 425
diff changeset
61 START_NS = StreamEventKind('START_NS') #: start namespace mapping
55c574767df2 More API documentation.
cmlenz
parents: 425
diff changeset
62 END_NS = StreamEventKind('END_NS') #: end namespace mapping
55c574767df2 More API documentation.
cmlenz
parents: 425
diff changeset
63 START_CDATA = StreamEventKind('START_CDATA') #: start CDATA section
55c574767df2 More API documentation.
cmlenz
parents: 425
diff changeset
64 END_CDATA = StreamEventKind('END_CDATA') #: end CDATA section
55c574767df2 More API documentation.
cmlenz
parents: 425
diff changeset
65 PI = StreamEventKind('PI') #: processing instruction
55c574767df2 More API documentation.
cmlenz
parents: 425
diff changeset
66 COMMENT = StreamEventKind('COMMENT') #: comment
1
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
67
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
68 def __init__(self, events):
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
69 """Initialize the stream with a sequence of markup events.
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
70
425
073640758a42 Try to use proper reStructuredText for docstrings throughout.
cmlenz
parents: 408
diff changeset
71 :param events: a sequence or iterable providing the events
1
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
72 """
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
73 self.events = events
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
74
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
75 def __iter__(self):
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
76 return iter(self.events)
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
77
204
51d4101f49ca * Implement reverse add/mul operators for `Markup` class, so that the result is also a `Markup` instance.
cmlenz
parents: 200
diff changeset
78 def __or__(self, function):
51d4101f49ca * Implement reverse add/mul operators for `Markup` class, so that the result is also a `Markup` instance.
cmlenz
parents: 200
diff changeset
79 """Override the "bitwise or" operator to apply filters or serializers
51d4101f49ca * Implement reverse add/mul operators for `Markup` class, so that the result is also a `Markup` instance.
cmlenz
parents: 200
diff changeset
80 to the stream, providing a syntax similar to pipes on Unix shells.
51d4101f49ca * Implement reverse add/mul operators for `Markup` class, so that the result is also a `Markup` instance.
cmlenz
parents: 200
diff changeset
81
51d4101f49ca * Implement reverse add/mul operators for `Markup` class, so that the result is also a `Markup` instance.
cmlenz
parents: 200
diff changeset
82 Assume the following stream produced by the `HTML` function:
51d4101f49ca * Implement reverse add/mul operators for `Markup` class, so that the result is also a `Markup` instance.
cmlenz
parents: 200
diff changeset
83
230
84168828b074 Renamed Markup to Genshi in repository.
cmlenz
parents: 224
diff changeset
84 >>> from genshi.input import HTML
204
51d4101f49ca * Implement reverse add/mul operators for `Markup` class, so that the result is also a `Markup` instance.
cmlenz
parents: 200
diff changeset
85 >>> html = HTML('''<p onclick="alert('Whoa')">Hello, world!</p>''')
51d4101f49ca * Implement reverse add/mul operators for `Markup` class, so that the result is also a `Markup` instance.
cmlenz
parents: 200
diff changeset
86 >>> print html
51d4101f49ca * Implement reverse add/mul operators for `Markup` class, so that the result is also a `Markup` instance.
cmlenz
parents: 200
diff changeset
87 <p onclick="alert('Whoa')">Hello, world!</p>
51d4101f49ca * Implement reverse add/mul operators for `Markup` class, so that the result is also a `Markup` instance.
cmlenz
parents: 200
diff changeset
88
51d4101f49ca * Implement reverse add/mul operators for `Markup` class, so that the result is also a `Markup` instance.
cmlenz
parents: 200
diff changeset
89 A filter such as the HTML sanitizer can be applied to that stream using
51d4101f49ca * Implement reverse add/mul operators for `Markup` class, so that the result is also a `Markup` instance.
cmlenz
parents: 200
diff changeset
90 the pipe notation as follows:
51d4101f49ca * Implement reverse add/mul operators for `Markup` class, so that the result is also a `Markup` instance.
cmlenz
parents: 200
diff changeset
91
230
84168828b074 Renamed Markup to Genshi in repository.
cmlenz
parents: 224
diff changeset
92 >>> from genshi.filters import HTMLSanitizer
204
51d4101f49ca * Implement reverse add/mul operators for `Markup` class, so that the result is also a `Markup` instance.
cmlenz
parents: 200
diff changeset
93 >>> sanitizer = HTMLSanitizer()
51d4101f49ca * Implement reverse add/mul operators for `Markup` class, so that the result is also a `Markup` instance.
cmlenz
parents: 200
diff changeset
94 >>> print html | sanitizer
51d4101f49ca * Implement reverse add/mul operators for `Markup` class, so that the result is also a `Markup` instance.
cmlenz
parents: 200
diff changeset
95 <p>Hello, world!</p>
51d4101f49ca * Implement reverse add/mul operators for `Markup` class, so that the result is also a `Markup` instance.
cmlenz
parents: 200
diff changeset
96
51d4101f49ca * Implement reverse add/mul operators for `Markup` class, so that the result is also a `Markup` instance.
cmlenz
parents: 200
diff changeset
97 Filters can be any function that accepts and produces a stream (where
397
31742fe6d47e * Moved some utility functions from `genshi.core` to `genshi.util` (backwards compatibility preserved via imports)
cmlenz
parents: 382
diff changeset
98 a stream is anything that iterates over events):
204
51d4101f49ca * Implement reverse add/mul operators for `Markup` class, so that the result is also a `Markup` instance.
cmlenz
parents: 200
diff changeset
99
51d4101f49ca * Implement reverse add/mul operators for `Markup` class, so that the result is also a `Markup` instance.
cmlenz
parents: 200
diff changeset
100 >>> def uppercase(stream):
51d4101f49ca * Implement reverse add/mul operators for `Markup` class, so that the result is also a `Markup` instance.
cmlenz
parents: 200
diff changeset
101 ... for kind, data, pos in stream:
51d4101f49ca * Implement reverse add/mul operators for `Markup` class, so that the result is also a `Markup` instance.
cmlenz
parents: 200
diff changeset
102 ... if kind is TEXT:
51d4101f49ca * Implement reverse add/mul operators for `Markup` class, so that the result is also a `Markup` instance.
cmlenz
parents: 200
diff changeset
103 ... data = data.upper()
51d4101f49ca * Implement reverse add/mul operators for `Markup` class, so that the result is also a `Markup` instance.
cmlenz
parents: 200
diff changeset
104 ... yield kind, data, pos
51d4101f49ca * Implement reverse add/mul operators for `Markup` class, so that the result is also a `Markup` instance.
cmlenz
parents: 200
diff changeset
105 >>> print html | sanitizer | uppercase
51d4101f49ca * Implement reverse add/mul operators for `Markup` class, so that the result is also a `Markup` instance.
cmlenz
parents: 200
diff changeset
106 <p>HELLO, WORLD!</p>
51d4101f49ca * Implement reverse add/mul operators for `Markup` class, so that the result is also a `Markup` instance.
cmlenz
parents: 200
diff changeset
107
51d4101f49ca * Implement reverse add/mul operators for `Markup` class, so that the result is also a `Markup` instance.
cmlenz
parents: 200
diff changeset
108 Serializers can also be used with this notation:
51d4101f49ca * Implement reverse add/mul operators for `Markup` class, so that the result is also a `Markup` instance.
cmlenz
parents: 200
diff changeset
109
230
84168828b074 Renamed Markup to Genshi in repository.
cmlenz
parents: 224
diff changeset
110 >>> from genshi.output import TextSerializer
204
51d4101f49ca * Implement reverse add/mul operators for `Markup` class, so that the result is also a `Markup` instance.
cmlenz
parents: 200
diff changeset
111 >>> output = TextSerializer()
51d4101f49ca * Implement reverse add/mul operators for `Markup` class, so that the result is also a `Markup` instance.
cmlenz
parents: 200
diff changeset
112 >>> print html | sanitizer | uppercase | output
51d4101f49ca * Implement reverse add/mul operators for `Markup` class, so that the result is also a `Markup` instance.
cmlenz
parents: 200
diff changeset
113 HELLO, WORLD!
51d4101f49ca * Implement reverse add/mul operators for `Markup` class, so that the result is also a `Markup` instance.
cmlenz
parents: 200
diff changeset
114
51d4101f49ca * Implement reverse add/mul operators for `Markup` class, so that the result is also a `Markup` instance.
cmlenz
parents: 200
diff changeset
115 Commonly, serializers should be used at the end of the "pipeline";
51d4101f49ca * Implement reverse add/mul operators for `Markup` class, so that the result is also a `Markup` instance.
cmlenz
parents: 200
diff changeset
116 using them somewhere in the middle may produce unexpected results.
51d4101f49ca * Implement reverse add/mul operators for `Markup` class, so that the result is also a `Markup` instance.
cmlenz
parents: 200
diff changeset
117 """
51d4101f49ca * Implement reverse add/mul operators for `Markup` class, so that the result is also a `Markup` instance.
cmlenz
parents: 200
diff changeset
118 return Stream(_ensure(function(self)))
51d4101f49ca * Implement reverse add/mul operators for `Markup` class, so that the result is also a `Markup` instance.
cmlenz
parents: 200
diff changeset
119
123
10279d2eeec9 Fix for #18: whitespace in space-sensitive elements such as `<pre>` and `<textarea>` is now preserved.
cmlenz
parents: 116
diff changeset
120 def filter(self, *filters):
10279d2eeec9 Fix for #18: whitespace in space-sensitive elements such as `<pre>` and `<textarea>` is now preserved.
cmlenz
parents: 116
diff changeset
121 """Apply filters to the stream.
113
d10fbba1d5e0 Removed the `sanitize()` method from the `Markup` class, and migrate the existing unit tests to `markup.tests.filters`. Provide a `Stream.filter()` method instead which can be used to conveniently apply a filter to a stream.
cmlenz
parents: 111
diff changeset
122
123
10279d2eeec9 Fix for #18: whitespace in space-sensitive elements such as `<pre>` and `<textarea>` is now preserved.
cmlenz
parents: 116
diff changeset
123 This method returns a new stream with the given filters applied. The
10279d2eeec9 Fix for #18: whitespace in space-sensitive elements such as `<pre>` and `<textarea>` is now preserved.
cmlenz
parents: 116
diff changeset
124 filters must be callables that accept the stream object as parameter,
10279d2eeec9 Fix for #18: whitespace in space-sensitive elements such as `<pre>` and `<textarea>` is now preserved.
cmlenz
parents: 116
diff changeset
125 and return the filtered stream.
204
51d4101f49ca * Implement reverse add/mul operators for `Markup` class, so that the result is also a `Markup` instance.
cmlenz
parents: 200
diff changeset
126
425
073640758a42 Try to use proper reStructuredText for docstrings throughout.
cmlenz
parents: 408
diff changeset
127 The call::
204
51d4101f49ca * Implement reverse add/mul operators for `Markup` class, so that the result is also a `Markup` instance.
cmlenz
parents: 200
diff changeset
128
51d4101f49ca * Implement reverse add/mul operators for `Markup` class, so that the result is also a `Markup` instance.
cmlenz
parents: 200
diff changeset
129 stream.filter(filter1, filter2)
51d4101f49ca * Implement reverse add/mul operators for `Markup` class, so that the result is also a `Markup` instance.
cmlenz
parents: 200
diff changeset
130
425
073640758a42 Try to use proper reStructuredText for docstrings throughout.
cmlenz
parents: 408
diff changeset
131 is equivalent to::
204
51d4101f49ca * Implement reverse add/mul operators for `Markup` class, so that the result is also a `Markup` instance.
cmlenz
parents: 200
diff changeset
132
51d4101f49ca * Implement reverse add/mul operators for `Markup` class, so that the result is also a `Markup` instance.
cmlenz
parents: 200
diff changeset
133 stream | filter1 | filter2
113
d10fbba1d5e0 Removed the `sanitize()` method from the `Markup` class, and migrate the existing unit tests to `markup.tests.filters`. Provide a `Stream.filter()` method instead which can be used to conveniently apply a filter to a stream.
cmlenz
parents: 111
diff changeset
134 """
204
51d4101f49ca * Implement reverse add/mul operators for `Markup` class, so that the result is also a `Markup` instance.
cmlenz
parents: 200
diff changeset
135 return reduce(operator.or_, (self,) + filters)
113
d10fbba1d5e0 Removed the `sanitize()` method from the `Markup` class, and migrate the existing unit tests to `markup.tests.filters`. Provide a `Stream.filter()` method instead which can be used to conveniently apply a filter to a stream.
cmlenz
parents: 111
diff changeset
136
123
10279d2eeec9 Fix for #18: whitespace in space-sensitive elements such as `<pre>` and `<textarea>` is now preserved.
cmlenz
parents: 116
diff changeset
137 def render(self, method='xml', encoding='utf-8', **kwargs):
1
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
138 """Return a string representation of the stream.
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
139
425
073640758a42 Try to use proper reStructuredText for docstrings throughout.
cmlenz
parents: 408
diff changeset
140 :param method: determines how the stream is serialized; can be either
200
5861f4446c26 Add serialization to plain text, based on cboos' patch. Closes #41.
cmlenz
parents: 182
diff changeset
141 "xml", "xhtml", "html", "text", or a custom serializer
5861f4446c26 Add serialization to plain text, based on cboos' patch. Closes #41.
cmlenz
parents: 182
diff changeset
142 class
425
073640758a42 Try to use proper reStructuredText for docstrings throughout.
cmlenz
parents: 408
diff changeset
143 :param encoding: how the output string should be encoded; if set to
1
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
144 `None`, this method returns a `unicode` object
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
145
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
146 Any additional keyword arguments are passed to the serializer, and thus
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
147 depend on the `method` parameter value.
438
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents: 435
diff changeset
148
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents: 435
diff changeset
149 :see: XMLSerializer.__init__, XHTMLSerializer.__init__,
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents: 435
diff changeset
150 HTMLSerializer.__init__, TextSerializer.__init__
1
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
151 """
462
d5e2a7b58116 Add lower-level serialization functions.
cmlenz
parents: 460
diff changeset
152 from genshi.output import encode
123
10279d2eeec9 Fix for #18: whitespace in space-sensitive elements such as `<pre>` and `<textarea>` is now preserved.
cmlenz
parents: 116
diff changeset
153 generator = self.serialize(method=method, **kwargs)
462
d5e2a7b58116 Add lower-level serialization functions.
cmlenz
parents: 460
diff changeset
154 return encode(generator, method=method, encoding=encoding)
1
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
155
278
d6c58473a9d0 Fix the handling of namespace context for match templates.
cmlenz
parents: 230
diff changeset
156 def select(self, path, namespaces=None, variables=None):
1
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
157 """Return a new stream that contains the events matching the given
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
158 XPath expression.
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
159
425
073640758a42 Try to use proper reStructuredText for docstrings throughout.
cmlenz
parents: 408
diff changeset
160 :param path: a string containing the XPath expression
435
be39660919a5 More API doc enhancements.
cmlenz
parents: 434
diff changeset
161 :param namespaces: mapping of namespace prefixes used in the path
be39660919a5 More API doc enhancements.
cmlenz
parents: 434
diff changeset
162 :param variables: mapping of variable names to values
be39660919a5 More API doc enhancements.
cmlenz
parents: 434
diff changeset
163 :return: the selected substream
be39660919a5 More API doc enhancements.
cmlenz
parents: 434
diff changeset
164 :raises PathSyntaxError: if the given path expression is invalid or not
be39660919a5 More API doc enhancements.
cmlenz
parents: 434
diff changeset
165 supported
1
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
166 """
230
84168828b074 Renamed Markup to Genshi in repository.
cmlenz
parents: 224
diff changeset
167 from genshi.path import Path
278
d6c58473a9d0 Fix the handling of namespace context for match templates.
cmlenz
parents: 230
diff changeset
168 return Path(path).select(self, namespaces, variables)
1
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
169
123
10279d2eeec9 Fix for #18: whitespace in space-sensitive elements such as `<pre>` and `<textarea>` is now preserved.
cmlenz
parents: 116
diff changeset
170 def serialize(self, method='xml', **kwargs):
1
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
171 """Generate strings corresponding to a specific serialization of the
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
172 stream.
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
173
18
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
174 Unlike the `render()` method, this method is a generator that returns
1
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
175 the serialized output incrementally, as opposed to returning a single
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
176 string.
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
177
425
073640758a42 Try to use proper reStructuredText for docstrings throughout.
cmlenz
parents: 408
diff changeset
178 :param method: determines how the stream is serialized; can be either
200
5861f4446c26 Add serialization to plain text, based on cboos' patch. Closes #41.
cmlenz
parents: 182
diff changeset
179 "xml", "xhtml", "html", "text", or a custom serializer
5861f4446c26 Add serialization to plain text, based on cboos' patch. Closes #41.
cmlenz
parents: 182
diff changeset
180 class
438
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents: 435
diff changeset
181
147
a4a0ca41b6ad Use `xmlcharrefreplace` when encoding the output in `Stream.render()`, so that encoding the output to legacy encodings such as ASCII or ISO-8859-1 should always work.
cmlenz
parents: 145
diff changeset
182 Any additional keyword arguments are passed to the serializer, and thus
a4a0ca41b6ad Use `xmlcharrefreplace` when encoding the output in `Stream.render()`, so that encoding the output to legacy encodings such as ASCII or ISO-8859-1 should always work.
cmlenz
parents: 145
diff changeset
183 depend on the `method` parameter value.
438
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents: 435
diff changeset
184
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents: 435
diff changeset
185 :see: XMLSerializer.__init__, XHTMLSerializer.__init__,
2c38ec4e2dff Added documentation page on the builtin stream filters.
cmlenz
parents: 435
diff changeset
186 HTMLSerializer.__init__, TextSerializer.__init__
1
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
187 """
462
d5e2a7b58116 Add lower-level serialization functions.
cmlenz
parents: 460
diff changeset
188 from genshi.output import get_serializer
d5e2a7b58116 Add lower-level serialization functions.
cmlenz
parents: 460
diff changeset
189 return get_serializer(method, **kwargs)(_ensure(self))
1
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
190
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
191 def __str__(self):
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
192 return self.render()
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
193
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
194 def __unicode__(self):
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
195 return self.render(encoding=None)
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
196
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
197
69
c40a5dcd2b55 A couple of minor performance improvements.
cmlenz
parents: 66
diff changeset
198 START = Stream.START
c40a5dcd2b55 A couple of minor performance improvements.
cmlenz
parents: 66
diff changeset
199 END = Stream.END
c40a5dcd2b55 A couple of minor performance improvements.
cmlenz
parents: 66
diff changeset
200 TEXT = Stream.TEXT
460
75425671b437 Apply patch by Alec Thomas for processing XML declarations (#111). Thanks!
cmlenz
parents: 438
diff changeset
201 XML_DECL = Stream.XML_DECL
69
c40a5dcd2b55 A couple of minor performance improvements.
cmlenz
parents: 66
diff changeset
202 DOCTYPE = Stream.DOCTYPE
c40a5dcd2b55 A couple of minor performance improvements.
cmlenz
parents: 66
diff changeset
203 START_NS = Stream.START_NS
c40a5dcd2b55 A couple of minor performance improvements.
cmlenz
parents: 66
diff changeset
204 END_NS = Stream.END_NS
143
3d4c214c979a CDATA sections in XML input now appear as CDATA sections in the output. This should address the problem with escaping the contents of `<style>` and `<script>` elements, which would only get interpreted correctly if the output was served as `application/xhtml+xml`. Closes #24.
cmlenz
parents: 141
diff changeset
205 START_CDATA = Stream.START_CDATA
3d4c214c979a CDATA sections in XML input now appear as CDATA sections in the output. This should address the problem with escaping the contents of `<style>` and `<script>` elements, which would only get interpreted correctly if the output was served as `application/xhtml+xml`. Closes #24.
cmlenz
parents: 141
diff changeset
206 END_CDATA = Stream.END_CDATA
69
c40a5dcd2b55 A couple of minor performance improvements.
cmlenz
parents: 66
diff changeset
207 PI = Stream.PI
c40a5dcd2b55 A couple of minor performance improvements.
cmlenz
parents: 66
diff changeset
208 COMMENT = Stream.COMMENT
c40a5dcd2b55 A couple of minor performance improvements.
cmlenz
parents: 66
diff changeset
209
111
2368c3becc52 Some fixes and more unit tests for the XPath engine.
cmlenz
parents: 100
diff changeset
210 def _ensure(stream):
2368c3becc52 Some fixes and more unit tests for the XPath engine.
cmlenz
parents: 100
diff changeset
211 """Ensure that every item on the stream is actually a markup event."""
2368c3becc52 Some fixes and more unit tests for the XPath engine.
cmlenz
parents: 100
diff changeset
212 for event in stream:
145
47bbd9d2a5af * Fix error in expression evaluation when the expression evaluates to an iterable that does not produce event tuples.
cmlenz
parents: 143
diff changeset
213 if type(event) is not tuple:
47bbd9d2a5af * Fix error in expression evaluation when the expression evaluates to an iterable that does not produce event tuples.
cmlenz
parents: 143
diff changeset
214 if hasattr(event, 'totuple'):
47bbd9d2a5af * Fix error in expression evaluation when the expression evaluates to an iterable that does not produce event tuples.
cmlenz
parents: 143
diff changeset
215 event = event.totuple()
47bbd9d2a5af * Fix error in expression evaluation when the expression evaluates to an iterable that does not produce event tuples.
cmlenz
parents: 143
diff changeset
216 else:
47bbd9d2a5af * Fix error in expression evaluation when the expression evaluates to an iterable that does not produce event tuples.
cmlenz
parents: 143
diff changeset
217 event = TEXT, unicode(event), (None, -1, -1)
47bbd9d2a5af * Fix error in expression evaluation when the expression evaluates to an iterable that does not produce event tuples.
cmlenz
parents: 143
diff changeset
218 yield event
111
2368c3becc52 Some fixes and more unit tests for the XPath engine.
cmlenz
parents: 100
diff changeset
219
69
c40a5dcd2b55 A couple of minor performance improvements.
cmlenz
parents: 66
diff changeset
220
345
2aa7ca37ae6a Make `Attrs` instances immutable.
cmlenz
parents: 326
diff changeset
221 class Attrs(tuple):
2aa7ca37ae6a Make `Attrs` instances immutable.
cmlenz
parents: 326
diff changeset
222 """Immutable sequence type that stores the attributes of an element.
18
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
223
434
5692bc32ba5f * Better method to propogate the full path to the template file on parse errors. Supersedes r513.
cmlenz
parents: 427
diff changeset
224 Ordering of the attributes is preserved, while access by name is also
345
2aa7ca37ae6a Make `Attrs` instances immutable.
cmlenz
parents: 326
diff changeset
225 supported.
18
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
226
182
2f30ce3fb85e Renamed `Attributes` to `Attrs` to reduce the verbosity.
cmlenz
parents: 172
diff changeset
227 >>> attrs = Attrs([('href', '#'), ('title', 'Foo')])
18
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
228 >>> attrs
403
228907abb726 Remove some magic/overhead from `Attrs` creation and manipulation by not automatically wrapping attribute names in `QName`.
cmlenz
parents: 397
diff changeset
229 Attrs([('href', '#'), ('title', 'Foo')])
18
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
230
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
231 >>> 'href' in attrs
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
232 True
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
233 >>> 'tabindex' in attrs
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
234 False
403
228907abb726 Remove some magic/overhead from `Attrs` creation and manipulation by not automatically wrapping attribute names in `QName`.
cmlenz
parents: 397
diff changeset
235 >>> attrs.get('title')
18
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
236 'Foo'
345
2aa7ca37ae6a Make `Attrs` instances immutable.
cmlenz
parents: 326
diff changeset
237
425
073640758a42 Try to use proper reStructuredText for docstrings throughout.
cmlenz
parents: 408
diff changeset
238 Instances may not be manipulated directly. Instead, the operators ``|`` and
073640758a42 Try to use proper reStructuredText for docstrings throughout.
cmlenz
parents: 408
diff changeset
239 ``-`` can be used to produce new instances that have specific attributes
345
2aa7ca37ae6a Make `Attrs` instances immutable.
cmlenz
parents: 326
diff changeset
240 added, replaced or removed.
2aa7ca37ae6a Make `Attrs` instances immutable.
cmlenz
parents: 326
diff changeset
241
425
073640758a42 Try to use proper reStructuredText for docstrings throughout.
cmlenz
parents: 408
diff changeset
242 To remove an attribute, use the ``-`` operator. The right hand side can be
345
2aa7ca37ae6a Make `Attrs` instances immutable.
cmlenz
parents: 326
diff changeset
243 either a string or a set/sequence of strings, identifying the name(s) of
2aa7ca37ae6a Make `Attrs` instances immutable.
cmlenz
parents: 326
diff changeset
244 the attribute(s) to remove:
2aa7ca37ae6a Make `Attrs` instances immutable.
cmlenz
parents: 326
diff changeset
245
2aa7ca37ae6a Make `Attrs` instances immutable.
cmlenz
parents: 326
diff changeset
246 >>> attrs - 'title'
403
228907abb726 Remove some magic/overhead from `Attrs` creation and manipulation by not automatically wrapping attribute names in `QName`.
cmlenz
parents: 397
diff changeset
247 Attrs([('href', '#')])
345
2aa7ca37ae6a Make `Attrs` instances immutable.
cmlenz
parents: 326
diff changeset
248 >>> attrs - ('title', 'href')
2aa7ca37ae6a Make `Attrs` instances immutable.
cmlenz
parents: 326
diff changeset
249 Attrs()
2aa7ca37ae6a Make `Attrs` instances immutable.
cmlenz
parents: 326
diff changeset
250
2aa7ca37ae6a Make `Attrs` instances immutable.
cmlenz
parents: 326
diff changeset
251 The original instance is not modified, but the operator can of course be
2aa7ca37ae6a Make `Attrs` instances immutable.
cmlenz
parents: 326
diff changeset
252 used with an assignment:
2aa7ca37ae6a Make `Attrs` instances immutable.
cmlenz
parents: 326
diff changeset
253
18
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
254 >>> attrs
403
228907abb726 Remove some magic/overhead from `Attrs` creation and manipulation by not automatically wrapping attribute names in `QName`.
cmlenz
parents: 397
diff changeset
255 Attrs([('href', '#'), ('title', 'Foo')])
345
2aa7ca37ae6a Make `Attrs` instances immutable.
cmlenz
parents: 326
diff changeset
256 >>> attrs -= 'title'
18
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
257 >>> attrs
403
228907abb726 Remove some magic/overhead from `Attrs` creation and manipulation by not automatically wrapping attribute names in `QName`.
cmlenz
parents: 397
diff changeset
258 Attrs([('href', '#')])
18
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
259
425
073640758a42 Try to use proper reStructuredText for docstrings throughout.
cmlenz
parents: 408
diff changeset
260 To add a new attribute, use the ``|`` operator, where the right hand value
073640758a42 Try to use proper reStructuredText for docstrings throughout.
cmlenz
parents: 408
diff changeset
261 is a sequence of ``(name, value)`` tuples (which includes `Attrs`
073640758a42 Try to use proper reStructuredText for docstrings throughout.
cmlenz
parents: 408
diff changeset
262 instances):
170
6b265e02d099 Allow initialization of `Attributes` with keyword arguments.
cmlenz
parents: 161
diff changeset
263
403
228907abb726 Remove some magic/overhead from `Attrs` creation and manipulation by not automatically wrapping attribute names in `QName`.
cmlenz
parents: 397
diff changeset
264 >>> attrs | [('title', 'Bar')]
228907abb726 Remove some magic/overhead from `Attrs` creation and manipulation by not automatically wrapping attribute names in `QName`.
cmlenz
parents: 397
diff changeset
265 Attrs([('href', '#'), ('title', 'Bar')])
171
7fcf8e04514e Follow-up to [214]: allow initializing `Attributes` with attribute names that contain dashes or conflict with a reserved word (such as ?class?.)
cmlenz
parents: 170
diff changeset
266
345
2aa7ca37ae6a Make `Attrs` instances immutable.
cmlenz
parents: 326
diff changeset
267 If the attributes already contain an attribute with a given name, the value
2aa7ca37ae6a Make `Attrs` instances immutable.
cmlenz
parents: 326
diff changeset
268 of that attribute is replaced:
171
7fcf8e04514e Follow-up to [214]: allow initializing `Attributes` with attribute names that contain dashes or conflict with a reserved word (such as ?class?.)
cmlenz
parents: 170
diff changeset
269
403
228907abb726 Remove some magic/overhead from `Attrs` creation and manipulation by not automatically wrapping attribute names in `QName`.
cmlenz
parents: 397
diff changeset
270 >>> attrs | [('href', 'http://example.org/')]
228907abb726 Remove some magic/overhead from `Attrs` creation and manipulation by not automatically wrapping attribute names in `QName`.
cmlenz
parents: 397
diff changeset
271 Attrs([('href', 'http://example.org/')])
18
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
272 """
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
273 __slots__ = []
1
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
274
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
275 def __contains__(self, name):
18
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
276 """Return whether the list includes an attribute with the specified
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
277 name.
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
278 """
133
79f445396cd7 Minor cleanup and performance improvement for the builder module.
cmlenz
parents: 123
diff changeset
279 for attr, _ in self:
79f445396cd7 Minor cleanup and performance improvement for the builder module.
cmlenz
parents: 123
diff changeset
280 if attr == name:
79f445396cd7 Minor cleanup and performance improvement for the builder module.
cmlenz
parents: 123
diff changeset
281 return True
1
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
282
345
2aa7ca37ae6a Make `Attrs` instances immutable.
cmlenz
parents: 326
diff changeset
283 def __getslice__(self, i, j):
2aa7ca37ae6a Make `Attrs` instances immutable.
cmlenz
parents: 326
diff changeset
284 return Attrs(tuple.__getslice__(self, i, j))
2aa7ca37ae6a Make `Attrs` instances immutable.
cmlenz
parents: 326
diff changeset
285
2aa7ca37ae6a Make `Attrs` instances immutable.
cmlenz
parents: 326
diff changeset
286 def __or__(self, attrs):
2aa7ca37ae6a Make `Attrs` instances immutable.
cmlenz
parents: 326
diff changeset
287 """Return a new instance that contains the attributes in `attrs` in
2aa7ca37ae6a Make `Attrs` instances immutable.
cmlenz
parents: 326
diff changeset
288 addition to any already existing attributes.
2aa7ca37ae6a Make `Attrs` instances immutable.
cmlenz
parents: 326
diff changeset
289 """
2aa7ca37ae6a Make `Attrs` instances immutable.
cmlenz
parents: 326
diff changeset
290 repl = dict([(an, av) for an, av in attrs if an in self])
2aa7ca37ae6a Make `Attrs` instances immutable.
cmlenz
parents: 326
diff changeset
291 return Attrs([(sn, repl.get(sn, sv)) for sn, sv in self] +
2aa7ca37ae6a Make `Attrs` instances immutable.
cmlenz
parents: 326
diff changeset
292 [(an, av) for an, av in attrs if an not in self])
2aa7ca37ae6a Make `Attrs` instances immutable.
cmlenz
parents: 326
diff changeset
293
326
f999da894391 Fixed `__repr__` of the `QName`, `Attrs`, and `Expression` classes so that the output can be used as code to instantiate the object again.
cmlenz
parents: 279
diff changeset
294 def __repr__(self):
f999da894391 Fixed `__repr__` of the `QName`, `Attrs`, and `Expression` classes so that the output can be used as code to instantiate the object again.
cmlenz
parents: 279
diff changeset
295 if not self:
f999da894391 Fixed `__repr__` of the `QName`, `Attrs`, and `Expression` classes so that the output can be used as code to instantiate the object again.
cmlenz
parents: 279
diff changeset
296 return 'Attrs()'
345
2aa7ca37ae6a Make `Attrs` instances immutable.
cmlenz
parents: 326
diff changeset
297 return 'Attrs([%s])' % ', '.join([repr(item) for item in self])
2aa7ca37ae6a Make `Attrs` instances immutable.
cmlenz
parents: 326
diff changeset
298
2aa7ca37ae6a Make `Attrs` instances immutable.
cmlenz
parents: 326
diff changeset
299 def __sub__(self, names):
2aa7ca37ae6a Make `Attrs` instances immutable.
cmlenz
parents: 326
diff changeset
300 """Return a new instance with all attributes with a name in `names` are
2aa7ca37ae6a Make `Attrs` instances immutable.
cmlenz
parents: 326
diff changeset
301 removed.
2aa7ca37ae6a Make `Attrs` instances immutable.
cmlenz
parents: 326
diff changeset
302 """
2aa7ca37ae6a Make `Attrs` instances immutable.
cmlenz
parents: 326
diff changeset
303 if isinstance(names, basestring):
2aa7ca37ae6a Make `Attrs` instances immutable.
cmlenz
parents: 326
diff changeset
304 names = (names,)
2aa7ca37ae6a Make `Attrs` instances immutable.
cmlenz
parents: 326
diff changeset
305 return Attrs([(name, val) for name, val in self if name not in names])
326
f999da894391 Fixed `__repr__` of the `QName`, `Attrs`, and `Expression` classes so that the output can be used as code to instantiate the object again.
cmlenz
parents: 279
diff changeset
306
1
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
307 def get(self, name, default=None):
18
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
308 """Return the value of the attribute with the specified name, or the
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
309 value of the `default` parameter if no such attribute is found.
435
be39660919a5 More API doc enhancements.
cmlenz
parents: 434
diff changeset
310
be39660919a5 More API doc enhancements.
cmlenz
parents: 434
diff changeset
311 :param name: the name of the attribute
be39660919a5 More API doc enhancements.
cmlenz
parents: 434
diff changeset
312 :param default: the value to return when the attribute does not exist
be39660919a5 More API doc enhancements.
cmlenz
parents: 434
diff changeset
313 :return: the attribute value, or the `default` value if that attribute
be39660919a5 More API doc enhancements.
cmlenz
parents: 434
diff changeset
314 does not exist
18
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
315 """
1
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
316 for attr, value in self:
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
317 if attr == name:
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
318 return value
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
319 return default
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
320
77
f5ec6d4a61e4 * Simplify implementation of the individual XPath tests (use closures instead of callable classes)
cmlenz
parents: 73
diff changeset
321 def totuple(self):
161
7b1f07496bf7 Various docstring additions and other cosmetic changes.
cmlenz
parents: 147
diff changeset
322 """Return the attributes as a markup event.
7b1f07496bf7 Various docstring additions and other cosmetic changes.
cmlenz
parents: 147
diff changeset
323
425
073640758a42 Try to use proper reStructuredText for docstrings throughout.
cmlenz
parents: 408
diff changeset
324 The returned event is a `TEXT` event, the data is the value of all
161
7b1f07496bf7 Various docstring additions and other cosmetic changes.
cmlenz
parents: 147
diff changeset
325 attributes joined together.
434
5692bc32ba5f * Better method to propogate the full path to the template file on parse errors. Supersedes r513.
cmlenz
parents: 427
diff changeset
326
5692bc32ba5f * Better method to propogate the full path to the template file on parse errors. Supersedes r513.
cmlenz
parents: 427
diff changeset
327 >>> Attrs([('href', '#'), ('title', 'Foo')]).totuple()
5692bc32ba5f * Better method to propogate the full path to the template file on parse errors. Supersedes r513.
cmlenz
parents: 427
diff changeset
328 ('TEXT', u'#Foo', (None, -1, -1))
161
7b1f07496bf7 Various docstring additions and other cosmetic changes.
cmlenz
parents: 147
diff changeset
329 """
77
f5ec6d4a61e4 * Simplify implementation of the individual XPath tests (use closures instead of callable classes)
cmlenz
parents: 73
diff changeset
330 return TEXT, u''.join([x[1] for x in self]), (None, -1, -1)
f5ec6d4a61e4 * Simplify implementation of the individual XPath tests (use closures instead of callable classes)
cmlenz
parents: 73
diff changeset
331
1
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
332
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
333 class Markup(unicode):
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
334 """Marks a string as being safe for inclusion in HTML/XML output without
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
335 needing to be escaped.
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
336 """
18
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
337 __slots__ = []
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
338
27
b4f78c05e5c9 * Fix the boilerplate in the Python source files.
cmlenz
parents: 18
diff changeset
339 def __new__(cls, text='', *args):
1
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
340 if args:
136
b86f496f6035 Minor performance improvements in serialization.
cmlenz
parents: 133
diff changeset
341 text %= tuple(map(escape, args))
27
b4f78c05e5c9 * Fix the boilerplate in the Python source files.
cmlenz
parents: 18
diff changeset
342 return unicode.__new__(cls, text)
1
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
343
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
344 def __add__(self, other):
204
51d4101f49ca * Implement reverse add/mul operators for `Markup` class, so that the result is also a `Markup` instance.
cmlenz
parents: 200
diff changeset
345 return Markup(unicode(self) + unicode(escape(other)))
51d4101f49ca * Implement reverse add/mul operators for `Markup` class, so that the result is also a `Markup` instance.
cmlenz
parents: 200
diff changeset
346
51d4101f49ca * Implement reverse add/mul operators for `Markup` class, so that the result is also a `Markup` instance.
cmlenz
parents: 200
diff changeset
347 def __radd__(self, other):
51d4101f49ca * Implement reverse add/mul operators for `Markup` class, so that the result is also a `Markup` instance.
cmlenz
parents: 200
diff changeset
348 return Markup(unicode(escape(other)) + unicode(self))
1
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
349
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
350 def __mod__(self, args):
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
351 if not isinstance(args, (list, tuple)):
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
352 args = [args]
136
b86f496f6035 Minor performance improvements in serialization.
cmlenz
parents: 133
diff changeset
353 return Markup(unicode.__mod__(self, tuple(map(escape, args))))
1
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
354
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
355 def __mul__(self, num):
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
356 return Markup(unicode(self) * num)
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
357
204
51d4101f49ca * Implement reverse add/mul operators for `Markup` class, so that the result is also a `Markup` instance.
cmlenz
parents: 200
diff changeset
358 def __rmul__(self, num):
51d4101f49ca * Implement reverse add/mul operators for `Markup` class, so that the result is also a `Markup` instance.
cmlenz
parents: 200
diff changeset
359 return Markup(num * unicode(self))
51d4101f49ca * Implement reverse add/mul operators for `Markup` class, so that the result is also a `Markup` instance.
cmlenz
parents: 200
diff changeset
360
17
74cc70129d04 Refactoring to address #6: all match templates are now processed by a single filter, which means that match templates added by included templates are properly applied. A side effect of this refactoring is that `Context` objects may not be reused across multiple template processing runs.
cmlenz
parents: 10
diff changeset
361 def __repr__(self):
382
2682dabbcd04 * Added documentation for the various stream event kinds.
cmlenz
parents: 377
diff changeset
362 return '<%s %r>' % (self.__class__.__name__, unicode(self))
17
74cc70129d04 Refactoring to address #6: all match templates are now processed by a single filter, which means that match templates added by included templates are properly applied. A side effect of this refactoring is that `Context` objects may not be reused across multiple template processing runs.
cmlenz
parents: 10
diff changeset
363
54
1f3cd91325d9 Fix a number of escaping problems:
cmlenz
parents: 34
diff changeset
364 def join(self, seq, escape_quotes=True):
434
5692bc32ba5f * Better method to propogate the full path to the template file on parse errors. Supersedes r513.
cmlenz
parents: 427
diff changeset
365 """Return a `Markup` object which is the concatenation of the strings
5692bc32ba5f * Better method to propogate the full path to the template file on parse errors. Supersedes r513.
cmlenz
parents: 427
diff changeset
366 in the given sequence, where this `Markup` object is the separator
5692bc32ba5f * Better method to propogate the full path to the template file on parse errors. Supersedes r513.
cmlenz
parents: 427
diff changeset
367 between the joined elements.
5692bc32ba5f * Better method to propogate the full path to the template file on parse errors. Supersedes r513.
cmlenz
parents: 427
diff changeset
368
5692bc32ba5f * Better method to propogate the full path to the template file on parse errors. Supersedes r513.
cmlenz
parents: 427
diff changeset
369 Any element in the sequence that is not a `Markup` instance is
5692bc32ba5f * Better method to propogate the full path to the template file on parse errors. Supersedes r513.
cmlenz
parents: 427
diff changeset
370 automatically escaped.
5692bc32ba5f * Better method to propogate the full path to the template file on parse errors. Supersedes r513.
cmlenz
parents: 427
diff changeset
371
5692bc32ba5f * Better method to propogate the full path to the template file on parse errors. Supersedes r513.
cmlenz
parents: 427
diff changeset
372 :param seq: the sequence of strings to join
5692bc32ba5f * Better method to propogate the full path to the template file on parse errors. Supersedes r513.
cmlenz
parents: 427
diff changeset
373 :param escape_quotes: whether double quote characters in the elements
5692bc32ba5f * Better method to propogate the full path to the template file on parse errors. Supersedes r513.
cmlenz
parents: 427
diff changeset
374 should be escaped
5692bc32ba5f * Better method to propogate the full path to the template file on parse errors. Supersedes r513.
cmlenz
parents: 427
diff changeset
375 :return: the joined `Markup` object
5692bc32ba5f * Better method to propogate the full path to the template file on parse errors. Supersedes r513.
cmlenz
parents: 427
diff changeset
376 :see: `escape`
5692bc32ba5f * Better method to propogate the full path to the template file on parse errors. Supersedes r513.
cmlenz
parents: 427
diff changeset
377 """
54
1f3cd91325d9 Fix a number of escaping problems:
cmlenz
parents: 34
diff changeset
378 return Markup(unicode(self).join([escape(item, quotes=escape_quotes)
34
3421dd98f015 quotes should not be escaped inside text nodes
mgood
parents: 27
diff changeset
379 for item in seq]))
1
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
380
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
381 def escape(cls, text, quotes=True):
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
382 """Create a Markup instance from a string and escape special characters
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
383 it may contain (<, >, & and \").
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
384
434
5692bc32ba5f * Better method to propogate the full path to the template file on parse errors. Supersedes r513.
cmlenz
parents: 427
diff changeset
385 >>> escape('"1 < 2"')
5692bc32ba5f * Better method to propogate the full path to the template file on parse errors. Supersedes r513.
cmlenz
parents: 427
diff changeset
386 <Markup u'&#34;1 &lt; 2&#34;'>
5692bc32ba5f * Better method to propogate the full path to the template file on parse errors. Supersedes r513.
cmlenz
parents: 427
diff changeset
387
1
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
388 If the `quotes` parameter is set to `False`, the \" character is left
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
389 as is. Escaping quotes is generally only required for strings that are
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
390 to be used in attribute values.
434
5692bc32ba5f * Better method to propogate the full path to the template file on parse errors. Supersedes r513.
cmlenz
parents: 427
diff changeset
391
5692bc32ba5f * Better method to propogate the full path to the template file on parse errors. Supersedes r513.
cmlenz
parents: 427
diff changeset
392 >>> escape('"1 < 2"', quotes=False)
5692bc32ba5f * Better method to propogate the full path to the template file on parse errors. Supersedes r513.
cmlenz
parents: 427
diff changeset
393 <Markup u'"1 &lt; 2"'>
5692bc32ba5f * Better method to propogate the full path to the template file on parse errors. Supersedes r513.
cmlenz
parents: 427
diff changeset
394
5692bc32ba5f * Better method to propogate the full path to the template file on parse errors. Supersedes r513.
cmlenz
parents: 427
diff changeset
395 :param text: the text to escape
5692bc32ba5f * Better method to propogate the full path to the template file on parse errors. Supersedes r513.
cmlenz
parents: 427
diff changeset
396 :param quotes: if ``True``, double quote characters are escaped in
5692bc32ba5f * Better method to propogate the full path to the template file on parse errors. Supersedes r513.
cmlenz
parents: 427
diff changeset
397 addition to the other special characters
5692bc32ba5f * Better method to propogate the full path to the template file on parse errors. Supersedes r513.
cmlenz
parents: 427
diff changeset
398 :return: the escaped `Markup` string
5692bc32ba5f * Better method to propogate the full path to the template file on parse errors. Supersedes r513.
cmlenz
parents: 427
diff changeset
399 :see: `genshi.core.escape`
1
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
400 """
73
1da51d718391 Some more performance tweaks.
cmlenz
parents: 69
diff changeset
401 if not text:
1da51d718391 Some more performance tweaks.
cmlenz
parents: 69
diff changeset
402 return cls()
1da51d718391 Some more performance tweaks.
cmlenz
parents: 69
diff changeset
403 if type(text) is cls:
1
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
404 return text
73
1da51d718391 Some more performance tweaks.
cmlenz
parents: 69
diff changeset
405 text = unicode(text).replace('&', '&amp;') \
1da51d718391 Some more performance tweaks.
cmlenz
parents: 69
diff changeset
406 .replace('<', '&lt;') \
1da51d718391 Some more performance tweaks.
cmlenz
parents: 69
diff changeset
407 .replace('>', '&gt;')
1
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
408 if quotes:
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
409 text = text.replace('"', '&#34;')
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
410 return cls(text)
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
411 escape = classmethod(escape)
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
412
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
413 def unescape(self):
434
5692bc32ba5f * Better method to propogate the full path to the template file on parse errors. Supersedes r513.
cmlenz
parents: 427
diff changeset
414 """Reverse-escapes &, <, >, and \" and returns a `unicode` object.
5692bc32ba5f * Better method to propogate the full path to the template file on parse errors. Supersedes r513.
cmlenz
parents: 427
diff changeset
415
5692bc32ba5f * Better method to propogate the full path to the template file on parse errors. Supersedes r513.
cmlenz
parents: 427
diff changeset
416 >>> Markup('1 &lt; 2').unescape()
5692bc32ba5f * Better method to propogate the full path to the template file on parse errors. Supersedes r513.
cmlenz
parents: 427
diff changeset
417 u'1 < 2'
5692bc32ba5f * Better method to propogate the full path to the template file on parse errors. Supersedes r513.
cmlenz
parents: 427
diff changeset
418
5692bc32ba5f * Better method to propogate the full path to the template file on parse errors. Supersedes r513.
cmlenz
parents: 427
diff changeset
419 :see: `genshi.core.unescape`
5692bc32ba5f * Better method to propogate the full path to the template file on parse errors. Supersedes r513.
cmlenz
parents: 427
diff changeset
420 """
1
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
421 if not self:
18
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
422 return u''
1
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
423 return unicode(self).replace('&#34;', '"') \
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
424 .replace('&gt;', '>') \
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
425 .replace('&lt;', '<') \
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
426 .replace('&amp;', '&')
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
427
116
c77c113846d6 Merged [135:138/branches/experimental/cspeedups].
cmlenz
parents: 115
diff changeset
428 def stripentities(self, keepxmlentities=False):
c77c113846d6 Merged [135:138/branches/experimental/cspeedups].
cmlenz
parents: 115
diff changeset
429 """Return a copy of the text with any character or numeric entities
c77c113846d6 Merged [135:138/branches/experimental/cspeedups].
cmlenz
parents: 115
diff changeset
430 replaced by the equivalent UTF-8 characters.
c77c113846d6 Merged [135:138/branches/experimental/cspeedups].
cmlenz
parents: 115
diff changeset
431
c77c113846d6 Merged [135:138/branches/experimental/cspeedups].
cmlenz
parents: 115
diff changeset
432 If the `keepxmlentities` parameter is provided and evaluates to `True`,
434
5692bc32ba5f * Better method to propogate the full path to the template file on parse errors. Supersedes r513.
cmlenz
parents: 427
diff changeset
433 the core XML entities (``&amp;``, ``&apos;``, ``&gt;``, ``&lt;`` and
5692bc32ba5f * Better method to propogate the full path to the template file on parse errors. Supersedes r513.
cmlenz
parents: 427
diff changeset
434 ``&quot;``) are not stripped.
5692bc32ba5f * Better method to propogate the full path to the template file on parse errors. Supersedes r513.
cmlenz
parents: 427
diff changeset
435
5692bc32ba5f * Better method to propogate the full path to the template file on parse errors. Supersedes r513.
cmlenz
parents: 427
diff changeset
436 :see: `genshi.util.stripentities`
6
71e8e645fe81 Simplified implementation of `py:content` directive.
cmlenz
parents: 5
diff changeset
437 """
116
c77c113846d6 Merged [135:138/branches/experimental/cspeedups].
cmlenz
parents: 115
diff changeset
438 return Markup(stripentities(self, keepxmlentities=keepxmlentities))
c77c113846d6 Merged [135:138/branches/experimental/cspeedups].
cmlenz
parents: 115
diff changeset
439
c77c113846d6 Merged [135:138/branches/experimental/cspeedups].
cmlenz
parents: 115
diff changeset
440 def striptags(self):
434
5692bc32ba5f * Better method to propogate the full path to the template file on parse errors. Supersedes r513.
cmlenz
parents: 427
diff changeset
441 """Return a copy of the text with all XML/HTML tags removed.
5692bc32ba5f * Better method to propogate the full path to the template file on parse errors. Supersedes r513.
cmlenz
parents: 427
diff changeset
442
5692bc32ba5f * Better method to propogate the full path to the template file on parse errors. Supersedes r513.
cmlenz
parents: 427
diff changeset
443 :see: `genshi.util.striptags`
5692bc32ba5f * Better method to propogate the full path to the template file on parse errors. Supersedes r513.
cmlenz
parents: 427
diff changeset
444 """
116
c77c113846d6 Merged [135:138/branches/experimental/cspeedups].
cmlenz
parents: 115
diff changeset
445 return Markup(striptags(self))
1
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
446
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
447
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
448 escape = Markup.escape
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
449
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
450 def unescape(text):
434
5692bc32ba5f * Better method to propogate the full path to the template file on parse errors. Supersedes r513.
cmlenz
parents: 427
diff changeset
451 """Reverse-escapes &, <, >, and \" and returns a `unicode` object.
5692bc32ba5f * Better method to propogate the full path to the template file on parse errors. Supersedes r513.
cmlenz
parents: 427
diff changeset
452
5692bc32ba5f * Better method to propogate the full path to the template file on parse errors. Supersedes r513.
cmlenz
parents: 427
diff changeset
453 >>> unescape(Markup('1 &lt; 2'))
5692bc32ba5f * Better method to propogate the full path to the template file on parse errors. Supersedes r513.
cmlenz
parents: 427
diff changeset
454 u'1 < 2'
5692bc32ba5f * Better method to propogate the full path to the template file on parse errors. Supersedes r513.
cmlenz
parents: 427
diff changeset
455
5692bc32ba5f * Better method to propogate the full path to the template file on parse errors. Supersedes r513.
cmlenz
parents: 427
diff changeset
456 If the provided `text` object is not a `Markup` instance, the text is
5692bc32ba5f * Better method to propogate the full path to the template file on parse errors. Supersedes r513.
cmlenz
parents: 427
diff changeset
457 returned as-is.
5692bc32ba5f * Better method to propogate the full path to the template file on parse errors. Supersedes r513.
cmlenz
parents: 427
diff changeset
458
5692bc32ba5f * Better method to propogate the full path to the template file on parse errors. Supersedes r513.
cmlenz
parents: 427
diff changeset
459 >>> unescape('1 &lt; 2')
5692bc32ba5f * Better method to propogate the full path to the template file on parse errors. Supersedes r513.
cmlenz
parents: 427
diff changeset
460 '1 &lt; 2'
5692bc32ba5f * Better method to propogate the full path to the template file on parse errors. Supersedes r513.
cmlenz
parents: 427
diff changeset
461
5692bc32ba5f * Better method to propogate the full path to the template file on parse errors. Supersedes r513.
cmlenz
parents: 427
diff changeset
462 :param text: the text to unescape
5692bc32ba5f * Better method to propogate the full path to the template file on parse errors. Supersedes r513.
cmlenz
parents: 427
diff changeset
463 """
1
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
464 if not isinstance(text, Markup):
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
465 return text
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
466 return text.unescape()
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
467
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
468
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
469 class Namespace(object):
18
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
470 """Utility class creating and testing elements with a namespace.
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
471
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
472 Internally, namespace URIs are encoded in the `QName` of any element or
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
473 attribute, the namespace URI being enclosed in curly braces. This class
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
474 helps create and test these strings.
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
475
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
476 A `Namespace` object is instantiated with the namespace URI.
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
477
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
478 >>> html = Namespace('http://www.w3.org/1999/xhtml')
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
479 >>> html
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
480 <Namespace "http://www.w3.org/1999/xhtml">
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
481 >>> html.uri
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
482 u'http://www.w3.org/1999/xhtml'
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
483
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
484 The `Namespace` object can than be used to generate `QName` objects with
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
485 that namespace:
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
486
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
487 >>> html.body
326
f999da894391 Fixed `__repr__` of the `QName`, `Attrs`, and `Expression` classes so that the output can be used as code to instantiate the object again.
cmlenz
parents: 279
diff changeset
488 QName(u'http://www.w3.org/1999/xhtml}body')
18
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
489 >>> html.body.localname
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
490 u'body'
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
491 >>> html.body.namespace
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
492 u'http://www.w3.org/1999/xhtml'
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
493
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
494 The same works using item access notation, which is useful for element or
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
495 attribute names that are not valid Python identifiers:
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
496
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
497 >>> html['body']
326
f999da894391 Fixed `__repr__` of the `QName`, `Attrs`, and `Expression` classes so that the output can be used as code to instantiate the object again.
cmlenz
parents: 279
diff changeset
498 QName(u'http://www.w3.org/1999/xhtml}body')
18
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
499
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
500 A `Namespace` object can also be used to test whether a specific `QName`
425
073640758a42 Try to use proper reStructuredText for docstrings throughout.
cmlenz
parents: 408
diff changeset
501 belongs to that namespace using the ``in`` operator:
18
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
502
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
503 >>> qname = html.body
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
504 >>> qname in html
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
505 True
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
506 >>> qname in Namespace('http://www.w3.org/2002/06/xhtml2')
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
507 False
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
508 """
224
90d62225f411 Implement support for namespace prefixes in XPath expressions.
cmlenz
parents: 204
diff changeset
509 def __new__(cls, uri):
90d62225f411 Implement support for namespace prefixes in XPath expressions.
cmlenz
parents: 204
diff changeset
510 if type(uri) is cls:
90d62225f411 Implement support for namespace prefixes in XPath expressions.
cmlenz
parents: 204
diff changeset
511 return uri
90d62225f411 Implement support for namespace prefixes in XPath expressions.
cmlenz
parents: 204
diff changeset
512 return object.__new__(cls, uri)
90d62225f411 Implement support for namespace prefixes in XPath expressions.
cmlenz
parents: 204
diff changeset
513
279
a99666402b12 Some adjustments to make core data structures picklable (requires protocol 2).
cmlenz
parents: 278
diff changeset
514 def __getnewargs__(self):
a99666402b12 Some adjustments to make core data structures picklable (requires protocol 2).
cmlenz
parents: 278
diff changeset
515 return (self.uri,)
a99666402b12 Some adjustments to make core data structures picklable (requires protocol 2).
cmlenz
parents: 278
diff changeset
516
a99666402b12 Some adjustments to make core data structures picklable (requires protocol 2).
cmlenz
parents: 278
diff changeset
517 def __getstate__(self):
a99666402b12 Some adjustments to make core data structures picklable (requires protocol 2).
cmlenz
parents: 278
diff changeset
518 return self.uri
a99666402b12 Some adjustments to make core data structures picklable (requires protocol 2).
cmlenz
parents: 278
diff changeset
519
a99666402b12 Some adjustments to make core data structures picklable (requires protocol 2).
cmlenz
parents: 278
diff changeset
520 def __setstate__(self, uri):
a99666402b12 Some adjustments to make core data structures picklable (requires protocol 2).
cmlenz
parents: 278
diff changeset
521 self.uri = uri
a99666402b12 Some adjustments to make core data structures picklable (requires protocol 2).
cmlenz
parents: 278
diff changeset
522
18
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
523 def __init__(self, uri):
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
524 self.uri = unicode(uri)
1
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
525
18
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
526 def __contains__(self, qname):
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
527 return qname.namespace == self.uri
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
528
278
d6c58473a9d0 Fix the handling of namespace context for match templates.
cmlenz
parents: 230
diff changeset
529 def __ne__(self, other):
d6c58473a9d0 Fix the handling of namespace context for match templates.
cmlenz
parents: 230
diff changeset
530 return not self == other
d6c58473a9d0 Fix the handling of namespace context for match templates.
cmlenz
parents: 230
diff changeset
531
18
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
532 def __eq__(self, other):
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
533 if isinstance(other, Namespace):
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
534 return self.uri == other.uri
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
535 return self.uri == other
1
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
536
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
537 def __getitem__(self, name):
18
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
538 return QName(self.uri + u'}' + name)
1
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
539 __getattr__ = __getitem__
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
540
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
541 def __repr__(self):
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
542 return '<Namespace "%s">' % self.uri
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
543
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
544 def __str__(self):
18
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
545 return self.uri.encode('utf-8')
1
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
546
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
547 def __unicode__(self):
18
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
548 return self.uri
1
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
549
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
550
147
a4a0ca41b6ad Use `xmlcharrefreplace` when encoding the output in `Stream.render()`, so that encoding the output to legacy encodings such as ASCII or ISO-8859-1 should always work.
cmlenz
parents: 145
diff changeset
551 # The namespace used by attributes such as xml:lang and xml:space
141
520a5b7dd6d2 * No escaping of `<script>` or `<style>` tags in HTML output (see #24)
cmlenz
parents: 140
diff changeset
552 XML_NAMESPACE = Namespace('http://www.w3.org/XML/1998/namespace')
520a5b7dd6d2 * No escaping of `<script>` or `<style>` tags in HTML output (see #24)
cmlenz
parents: 140
diff changeset
553
520a5b7dd6d2 * No escaping of `<script>` or `<style>` tags in HTML output (see #24)
cmlenz
parents: 140
diff changeset
554
1
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
555 class QName(unicode):
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
556 """A qualified element or attribute name.
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
557
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
558 The unicode value of instances of this class contains the qualified name of
425
073640758a42 Try to use proper reStructuredText for docstrings throughout.
cmlenz
parents: 408
diff changeset
559 the element or attribute, in the form ``{namespace}localname``. The namespace
1
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
560 URI can be obtained through the additional `namespace` attribute, while the
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
561 local name can be accessed through the `localname` attribute.
18
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
562
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
563 >>> qname = QName('foo')
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
564 >>> qname
326
f999da894391 Fixed `__repr__` of the `QName`, `Attrs`, and `Expression` classes so that the output can be used as code to instantiate the object again.
cmlenz
parents: 279
diff changeset
565 QName(u'foo')
18
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
566 >>> qname.localname
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
567 u'foo'
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
568 >>> qname.namespace
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
569
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
570 >>> qname = QName('http://www.w3.org/1999/xhtml}body')
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
571 >>> qname
326
f999da894391 Fixed `__repr__` of the `QName`, `Attrs`, and `Expression` classes so that the output can be used as code to instantiate the object again.
cmlenz
parents: 279
diff changeset
572 QName(u'http://www.w3.org/1999/xhtml}body')
18
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
573 >>> qname.localname
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
574 u'body'
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
575 >>> qname.namespace
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
576 u'http://www.w3.org/1999/xhtml'
1
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
577 """
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
578 __slots__ = ['namespace', 'localname']
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
579
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
580 def __new__(cls, qname):
100
a519f581a1b1 Ported [111] to trunk.
cmlenz
parents: 96
diff changeset
581 if type(qname) is cls:
1
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
582 return qname
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
583
18
5420cfe42d36 Actually make use of the `markup.core.Namespace` class, and add a couple of doctests.
cmlenz
parents: 17
diff changeset
584 parts = qname.split(u'}', 1)
100
a519f581a1b1 Ported [111] to trunk.
cmlenz
parents: 96
diff changeset
585 if len(parts) > 1:
136
b86f496f6035 Minor performance improvements in serialization.
cmlenz
parents: 133
diff changeset
586 self = unicode.__new__(cls, u'{%s' % qname)
b86f496f6035 Minor performance improvements in serialization.
cmlenz
parents: 133
diff changeset
587 self.namespace, self.localname = map(unicode, parts)
1
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
588 else:
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
589 self = unicode.__new__(cls, qname)
136
b86f496f6035 Minor performance improvements in serialization.
cmlenz
parents: 133
diff changeset
590 self.namespace, self.localname = None, unicode(qname)
1
5479aae32f5a Initial import.
cmlenz
parents:
diff changeset
591 return self
279
a99666402b12 Some adjustments to make core data structures picklable (requires protocol 2).
cmlenz
parents: 278
diff changeset
592
a99666402b12 Some adjustments to make core data structures picklable (requires protocol 2).
cmlenz
parents: 278
diff changeset
593 def __getnewargs__(self):
a99666402b12 Some adjustments to make core data structures picklable (requires protocol 2).
cmlenz
parents: 278
diff changeset
594 return (self.lstrip('{'),)
326
f999da894391 Fixed `__repr__` of the `QName`, `Attrs`, and `Expression` classes so that the output can be used as code to instantiate the object again.
cmlenz
parents: 279
diff changeset
595
f999da894391 Fixed `__repr__` of the `QName`, `Attrs`, and `Expression` classes so that the output can be used as code to instantiate the object again.
cmlenz
parents: 279
diff changeset
596 def __repr__(self):
f999da894391 Fixed `__repr__` of the `QName`, `Attrs`, and `Expression` classes so that the output can be used as code to instantiate the object again.
cmlenz
parents: 279
diff changeset
597 return 'QName(%s)' % unicode.__repr__(self.lstrip('{'))
Copyright (C) 2012-2017 Edgewall Software