Mercurial > genshi > mirror
annotate genshi/builder.py @ 379:e1d659c87ddf trunk
The builder API now accepts streams as children of elements and fragments.
| author | cmlenz |
|---|---|
| date | Thu, 23 Nov 2006 17:48:17 +0000 |
| parents | 2aa7ca37ae6a |
| children | 228907abb726 3eb30e4ece8c |
| rev | line source |
|---|---|
| 1 | 1 # -*- coding: utf-8 -*- |
| 2 # | |
|
66
59eb24184e9c
Switch copyright to Edgewall and URLs to markup.edgewall.org.
cmlenz
parents:
65
diff
changeset
|
3 # Copyright (C) 2006 Edgewall Software |
| 1 | 4 # All rights reserved. |
| 5 # | |
| 6 # This software is licensed as described in the file COPYING, which | |
| 7 # you should have received as part of this distribution. The terms | |
| 230 | 8 # are also available at http://genshi.edgewall.org/wiki/License. |
| 1 | 9 # |
| 10 # This software consists of voluntary contributions made by many | |
| 11 # individuals. For the exact contribution history, see the revision | |
| 230 | 12 # history and logs, available at http://genshi.edgewall.org/log/. |
| 1 | 13 |
| 230 | 14 from genshi.core import Attrs, Namespace, QName, Stream, START, END, TEXT |
| 1 | 15 |
| 16 __all__ = ['Fragment', 'Element', 'tag'] | |
| 17 | |
| 18 | |
| 19 class Fragment(object): | |
| 28 | 20 """Represents a markup fragment, which is basically just a list of element |
| 21 or text nodes. | |
| 22 """ | |
| 1 | 23 __slots__ = ['children'] |
| 24 | |
| 25 def __init__(self): | |
| 26 self.children = [] | |
| 27 | |
|
65
b3fdf93057ab
Support the use of directives as elements to reduce the need for using `py:strip`.
cmlenz
parents:
34
diff
changeset
|
28 def __add__(self, other): |
|
b3fdf93057ab
Support the use of directives as elements to reduce the need for using `py:strip`.
cmlenz
parents:
34
diff
changeset
|
29 return Fragment()(self, other) |
|
b3fdf93057ab
Support the use of directives as elements to reduce the need for using `py:strip`.
cmlenz
parents:
34
diff
changeset
|
30 |
|
b3fdf93057ab
Support the use of directives as elements to reduce the need for using `py:strip`.
cmlenz
parents:
34
diff
changeset
|
31 def __call__(self, *args): |
|
133
79f445396cd7
Minor cleanup and performance improvement for the builder module.
cmlenz
parents:
119
diff
changeset
|
32 map(self.append, args) |
|
65
b3fdf93057ab
Support the use of directives as elements to reduce the need for using `py:strip`.
cmlenz
parents:
34
diff
changeset
|
33 return self |
|
b3fdf93057ab
Support the use of directives as elements to reduce the need for using `py:strip`.
cmlenz
parents:
34
diff
changeset
|
34 |
|
b3fdf93057ab
Support the use of directives as elements to reduce the need for using `py:strip`.
cmlenz
parents:
34
diff
changeset
|
35 def __iter__(self): |
|
98
44af12832c5a
Bugfix in `builder` module: attribute values need to be converted to strings when generating streams.
cmlenz
parents:
94
diff
changeset
|
36 return self._generate() |
|
65
b3fdf93057ab
Support the use of directives as elements to reduce the need for using `py:strip`.
cmlenz
parents:
34
diff
changeset
|
37 |
|
b3fdf93057ab
Support the use of directives as elements to reduce the need for using `py:strip`.
cmlenz
parents:
34
diff
changeset
|
38 def __repr__(self): |
|
b3fdf93057ab
Support the use of directives as elements to reduce the need for using `py:strip`.
cmlenz
parents:
34
diff
changeset
|
39 return '<%s>' % self.__class__.__name__ |
|
b3fdf93057ab
Support the use of directives as elements to reduce the need for using `py:strip`.
cmlenz
parents:
34
diff
changeset
|
40 |
|
b3fdf93057ab
Support the use of directives as elements to reduce the need for using `py:strip`.
cmlenz
parents:
34
diff
changeset
|
41 def __str__(self): |
|
b3fdf93057ab
Support the use of directives as elements to reduce the need for using `py:strip`.
cmlenz
parents:
34
diff
changeset
|
42 return str(self.generate()) |
|
b3fdf93057ab
Support the use of directives as elements to reduce the need for using `py:strip`.
cmlenz
parents:
34
diff
changeset
|
43 |
|
b3fdf93057ab
Support the use of directives as elements to reduce the need for using `py:strip`.
cmlenz
parents:
34
diff
changeset
|
44 def __unicode__(self): |
|
b3fdf93057ab
Support the use of directives as elements to reduce the need for using `py:strip`.
cmlenz
parents:
34
diff
changeset
|
45 return unicode(self.generate()) |
|
b3fdf93057ab
Support the use of directives as elements to reduce the need for using `py:strip`.
cmlenz
parents:
34
diff
changeset
|
46 |
| 1 | 47 def append(self, node): |
| 48 """Append an element or string as child node.""" | |
|
379
e1d659c87ddf
The builder API now accepts streams as children of elements and fragments.
cmlenz
parents:
345
diff
changeset
|
49 if isinstance(node, (Stream, Element, basestring, int, float, long)): |
| 1 | 50 # For objects of a known/primitive type, we avoid the check for |
| 51 # whether it is iterable for better performance | |
| 52 self.children.append(node) | |
| 53 elif isinstance(node, Fragment): | |
|
133
79f445396cd7
Minor cleanup and performance improvement for the builder module.
cmlenz
parents:
119
diff
changeset
|
54 self.children.extend(node.children) |
| 1 | 55 elif node is not None: |
| 56 try: | |
|
133
79f445396cd7
Minor cleanup and performance improvement for the builder module.
cmlenz
parents:
119
diff
changeset
|
57 map(self.append, iter(node)) |
| 1 | 58 except TypeError: |
| 59 self.children.append(node) | |
|
94
0f8800c46e21
Some bugfixes and minor performance improvements for the builder module.
cmlenz
parents:
91
diff
changeset
|
60 |
|
0f8800c46e21
Some bugfixes and minor performance improvements for the builder module.
cmlenz
parents:
91
diff
changeset
|
61 def _generate(self): |
|
0f8800c46e21
Some bugfixes and minor performance improvements for the builder module.
cmlenz
parents:
91
diff
changeset
|
62 for child in self.children: |
|
0f8800c46e21
Some bugfixes and minor performance improvements for the builder module.
cmlenz
parents:
91
diff
changeset
|
63 if isinstance(child, Fragment): |
|
0f8800c46e21
Some bugfixes and minor performance improvements for the builder module.
cmlenz
parents:
91
diff
changeset
|
64 for event in child._generate(): |
|
0f8800c46e21
Some bugfixes and minor performance improvements for the builder module.
cmlenz
parents:
91
diff
changeset
|
65 yield event |
|
379
e1d659c87ddf
The builder API now accepts streams as children of elements and fragments.
cmlenz
parents:
345
diff
changeset
|
66 elif isinstance(child, Stream): |
|
e1d659c87ddf
The builder API now accepts streams as children of elements and fragments.
cmlenz
parents:
345
diff
changeset
|
67 for event in child: |
|
e1d659c87ddf
The builder API now accepts streams as children of elements and fragments.
cmlenz
parents:
345
diff
changeset
|
68 yield event |
|
94
0f8800c46e21
Some bugfixes and minor performance improvements for the builder module.
cmlenz
parents:
91
diff
changeset
|
69 else: |
|
0f8800c46e21
Some bugfixes and minor performance improvements for the builder module.
cmlenz
parents:
91
diff
changeset
|
70 if not isinstance(child, basestring): |
|
0f8800c46e21
Some bugfixes and minor performance improvements for the builder module.
cmlenz
parents:
91
diff
changeset
|
71 child = unicode(child) |
|
133
79f445396cd7
Minor cleanup and performance improvement for the builder module.
cmlenz
parents:
119
diff
changeset
|
72 yield TEXT, child, (None, -1, -1) |
| 1 | 73 |
| 74 def generate(self): | |
| 28 | 75 """Return a markup event stream for the fragment.""" |
|
94
0f8800c46e21
Some bugfixes and minor performance improvements for the builder module.
cmlenz
parents:
91
diff
changeset
|
76 return Stream(self._generate()) |
| 1 | 77 |
| 78 | |
| 345 | 79 def _value_to_unicode(value): |
| 80 if isinstance(value, unicode): | |
| 81 return value | |
| 82 return unicode(value) | |
| 83 | |
| 84 def _kwargs_to_attrs(kwargs): | |
| 85 return [(k.rstrip('_').replace('_', '-'), _value_to_unicode(v)) | |
| 86 for k, v in kwargs.items() if v is not None] | |
| 87 | |
| 88 | |
| 1 | 89 class Element(Fragment): |
| 90 """Simple XML output generator based on the builder pattern. | |
| 91 | |
| 92 Construct XML elements by passing the tag name to the constructor: | |
| 93 | |
| 94 >>> print Element('strong') | |
| 95 <strong/> | |
| 96 | |
| 97 Attributes can be specified using keyword arguments. The values of the | |
| 98 arguments will be converted to strings and any special XML characters | |
| 99 escaped: | |
| 100 | |
| 101 >>> print Element('textarea', rows=10, cols=60) | |
| 102 <textarea rows="10" cols="60"/> | |
| 103 >>> print Element('span', title='1 < 2') | |
| 104 <span title="1 < 2"/> | |
| 105 >>> print Element('span', title='"baz"') | |
| 106 <span title=""baz""/> | |
| 107 | |
| 108 The " character is escaped using a numerical entity. | |
| 109 The order in which attributes are rendered is undefined. | |
| 110 | |
| 111 If an attribute value evaluates to `None`, that attribute is not included | |
| 112 in the output: | |
| 113 | |
| 114 >>> print Element('a', name=None) | |
| 115 <a/> | |
| 116 | |
| 117 Attribute names that conflict with Python keywords can be specified by | |
| 118 appending an underscore: | |
| 119 | |
| 120 >>> print Element('div', class_='warning') | |
| 121 <div class="warning"/> | |
| 122 | |
| 123 Nested elements can be added to an element using item access notation. | |
| 124 The call notation can also be used for this and for adding attributes | |
| 125 using keyword arguments, as one would do in the constructor. | |
| 126 | |
| 127 >>> print Element('ul')(Element('li'), Element('li')) | |
| 128 <ul><li/><li/></ul> | |
| 129 >>> print Element('a')('Label') | |
| 130 <a>Label</a> | |
| 131 >>> print Element('a')('Label', href="target") | |
| 132 <a href="target">Label</a> | |
| 133 | |
| 134 Text nodes can be nested in an element by adding strings instead of | |
| 135 elements. Any special characters in the strings are escaped automatically: | |
| 136 | |
| 137 >>> print Element('em')('Hello world') | |
| 138 <em>Hello world</em> | |
| 139 >>> print Element('em')(42) | |
| 140 <em>42</em> | |
| 141 >>> print Element('em')('1 < 2') | |
| 142 <em>1 < 2</em> | |
| 143 | |
| 144 This technique also allows mixed content: | |
| 145 | |
| 146 >>> print Element('p')('Hello ', Element('b')('world')) | |
| 147 <p>Hello <b>world</b></p> | |
| 148 | |
| 34 | 149 Quotes are not escaped inside text nodes: |
| 150 >>> print Element('p')('"Hello"') | |
| 151 <p>"Hello"</p> | |
| 152 | |
| 1 | 153 Elements can also be combined with other elements or strings using the |
| 154 addition operator, which results in a `Fragment` object that contains the | |
| 155 operands: | |
| 156 | |
| 157 >>> print Element('br') + 'some text' + Element('br') | |
| 158 <br/>some text<br/> | |
| 159 | |
| 160 Elements with a namespace can be generated using the `Namespace` and/or | |
| 161 `QName` classes: | |
| 162 | |
| 230 | 163 >>> from genshi.core import Namespace |
| 1 | 164 >>> xhtml = Namespace('http://www.w3.org/1999/xhtml') |
| 165 >>> print Element(xhtml.html, lang='en') | |
| 166 <html lang="en" xmlns="http://www.w3.org/1999/xhtml"/> | |
| 167 """ | |
| 168 __slots__ = ['tag', 'attrib'] | |
| 169 | |
| 170 def __init__(self, tag_, **attrib): | |
| 171 Fragment.__init__(self) | |
| 172 self.tag = QName(tag_) | |
| 345 | 173 self.attrib = Attrs(_kwargs_to_attrs(attrib)) |
| 1 | 174 |
| 175 def __call__(self, *args, **kwargs): | |
| 345 | 176 self.attrib |= Attrs(_kwargs_to_attrs(kwargs)) |
|
98
44af12832c5a
Bugfix in `builder` module: attribute values need to be converted to strings when generating streams.
cmlenz
parents:
94
diff
changeset
|
177 Fragment.__call__(self, *args) |
|
44af12832c5a
Bugfix in `builder` module: attribute values need to be converted to strings when generating streams.
cmlenz
parents:
94
diff
changeset
|
178 return self |
| 1 | 179 |
|
65
b3fdf93057ab
Support the use of directives as elements to reduce the need for using `py:strip`.
cmlenz
parents:
34
diff
changeset
|
180 def __repr__(self): |
|
b3fdf93057ab
Support the use of directives as elements to reduce the need for using `py:strip`.
cmlenz
parents:
34
diff
changeset
|
181 return '<%s "%s">' % (self.__class__.__name__, self.tag) |
|
b3fdf93057ab
Support the use of directives as elements to reduce the need for using `py:strip`.
cmlenz
parents:
34
diff
changeset
|
182 |
|
94
0f8800c46e21
Some bugfixes and minor performance improvements for the builder module.
cmlenz
parents:
91
diff
changeset
|
183 def _generate(self): |
|
133
79f445396cd7
Minor cleanup and performance improvement for the builder module.
cmlenz
parents:
119
diff
changeset
|
184 yield START, (self.tag, self.attrib), (None, -1, -1) |
|
94
0f8800c46e21
Some bugfixes and minor performance improvements for the builder module.
cmlenz
parents:
91
diff
changeset
|
185 for kind, data, pos in Fragment._generate(self): |
|
0f8800c46e21
Some bugfixes and minor performance improvements for the builder module.
cmlenz
parents:
91
diff
changeset
|
186 yield kind, data, pos |
|
133
79f445396cd7
Minor cleanup and performance improvement for the builder module.
cmlenz
parents:
119
diff
changeset
|
187 yield END, self.tag, (None, -1, -1) |
|
94
0f8800c46e21
Some bugfixes and minor performance improvements for the builder module.
cmlenz
parents:
91
diff
changeset
|
188 |
| 1 | 189 def generate(self): |
| 28 | 190 """Return a markup event stream for the fragment.""" |
|
94
0f8800c46e21
Some bugfixes and minor performance improvements for the builder module.
cmlenz
parents:
91
diff
changeset
|
191 return Stream(self._generate()) |
| 1 | 192 |
| 193 | |
| 194 class ElementFactory(object): | |
| 28 | 195 """Factory for `Element` objects. |
| 196 | |
| 197 A new element is created simply by accessing a correspondingly named | |
| 198 attribute of the factory object: | |
| 199 | |
| 200 >>> factory = ElementFactory() | |
| 201 >>> print factory.foo | |
| 202 <foo/> | |
| 203 >>> print factory.foo(id=2) | |
| 204 <foo id="2"/> | |
| 205 | |
|
119
cc2aee07f53b
Allow creating fragments from the `tag` object in `markup.builder`.
cmlenz
parents:
98
diff
changeset
|
206 Markup fragments (lists of nodes without a parent element) can be created |
|
cc2aee07f53b
Allow creating fragments from the `tag` object in `markup.builder`.
cmlenz
parents:
98
diff
changeset
|
207 by calling the factory: |
|
cc2aee07f53b
Allow creating fragments from the `tag` object in `markup.builder`.
cmlenz
parents:
98
diff
changeset
|
208 |
|
cc2aee07f53b
Allow creating fragments from the `tag` object in `markup.builder`.
cmlenz
parents:
98
diff
changeset
|
209 >>> print factory('Hello, ', factory.em('world'), '!') |
|
cc2aee07f53b
Allow creating fragments from the `tag` object in `markup.builder`.
cmlenz
parents:
98
diff
changeset
|
210 Hello, <em>world</em>! |
|
cc2aee07f53b
Allow creating fragments from the `tag` object in `markup.builder`.
cmlenz
parents:
98
diff
changeset
|
211 |
| 28 | 212 A factory can also be bound to a specific namespace: |
| 213 | |
| 214 >>> factory = ElementFactory('http://www.w3.org/1999/xhtml') | |
| 215 >>> print factory.html(lang="en") | |
| 216 <html lang="en" xmlns="http://www.w3.org/1999/xhtml"/> | |
| 217 | |
| 218 The namespace for a specific element can be altered on an existing factory | |
| 219 by specifying the new namespace using item access: | |
| 220 | |
| 221 >>> factory = ElementFactory() | |
| 222 >>> print factory.html(factory['http://www.w3.org/2000/svg'].g(id=3)) | |
| 223 <html><g id="3" xmlns="http://www.w3.org/2000/svg"/></html> | |
| 224 | |
| 225 Usually, the `ElementFactory` class is not be used directly. Rather, the | |
| 226 `tag` instance should be used to create elements. | |
| 227 """ | |
| 1 | 228 |
|
19
704f10b06507
Enable `ElementFactory` to create namespaced elements.
cmlenz
parents:
17
diff
changeset
|
229 def __init__(self, namespace=None): |
| 28 | 230 """Create the factory, optionally bound to the given namespace. |
| 231 | |
| 232 @param namespace: the namespace URI for any created elements, or `None` | |
| 233 for no namespace | |
| 234 """ | |
| 20 | 235 if namespace and not isinstance(namespace, Namespace): |
|
19
704f10b06507
Enable `ElementFactory` to create namespaced elements.
cmlenz
parents:
17
diff
changeset
|
236 namespace = Namespace(namespace) |
|
704f10b06507
Enable `ElementFactory` to create namespaced elements.
cmlenz
parents:
17
diff
changeset
|
237 self.namespace = namespace |
|
704f10b06507
Enable `ElementFactory` to create namespaced elements.
cmlenz
parents:
17
diff
changeset
|
238 |
|
119
cc2aee07f53b
Allow creating fragments from the `tag` object in `markup.builder`.
cmlenz
parents:
98
diff
changeset
|
239 def __call__(self, *args): |
|
cc2aee07f53b
Allow creating fragments from the `tag` object in `markup.builder`.
cmlenz
parents:
98
diff
changeset
|
240 return Fragment()(*args) |
|
cc2aee07f53b
Allow creating fragments from the `tag` object in `markup.builder`.
cmlenz
parents:
98
diff
changeset
|
241 |
|
19
704f10b06507
Enable `ElementFactory` to create namespaced elements.
cmlenz
parents:
17
diff
changeset
|
242 def __getitem__(self, namespace): |
| 28 | 243 """Return a new factory that is bound to the specified namespace.""" |
|
19
704f10b06507
Enable `ElementFactory` to create namespaced elements.
cmlenz
parents:
17
diff
changeset
|
244 return ElementFactory(namespace) |
|
704f10b06507
Enable `ElementFactory` to create namespaced elements.
cmlenz
parents:
17
diff
changeset
|
245 |
|
704f10b06507
Enable `ElementFactory` to create namespaced elements.
cmlenz
parents:
17
diff
changeset
|
246 def __getattr__(self, name): |
| 28 | 247 """Create an `Element` with the given name.""" |
|
19
704f10b06507
Enable `ElementFactory` to create namespaced elements.
cmlenz
parents:
17
diff
changeset
|
248 return Element(self.namespace and self.namespace[name] or name) |
| 1 | 249 |
| 250 | |
| 251 tag = ElementFactory() |