annotate markup/builder.py @ 133:79f445396cd7 trunk

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