aboutsummaryrefslogtreecommitdiffstats
path: root/contrib/python/Twisted/py2/twisted/web/_stan.py
blob: 033a52c6529d9a635d46c8d0390e7cc21738c198 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
# -*- test-case-name: twisted.web.test.test_stan -*-
# Copyright (c) Twisted Matrix Laboratories.
# See LICENSE for details.

"""
An s-expression-like syntax for expressing xml in pure python.

Stan tags allow you to build XML documents using Python.

Stan is a DOM, or Document Object Model, implemented using basic Python types
and functions called "flatteners". A flattener is a function that knows how to
turn an object of a specific type into something that is closer to an HTML
string. Stan differs from the W3C DOM by not being as cumbersome and heavy
weight. Since the object model is built using simple python types such as lists,
strings, and dictionaries, the API is simpler and constructing a DOM less
cumbersome.

@var voidElements: the names of HTML 'U{void
    elements<http://www.whatwg.org/specs/web-apps/current-work/multipage/syntax.html#void-elements>}';
    those which can't have contents and can therefore be self-closing in the
    output.
"""

from __future__ import absolute_import, division

from twisted.python.compat import iteritems



class slot(object):
    """
    Marker for markup insertion in a template.

    @type name: C{str}
    @ivar name: The name of this slot.  The key which must be used in
        L{Tag.fillSlots} to fill it.

    @type children: C{list}
    @ivar children: The L{Tag} objects included in this L{slot}'s template.

    @type default: anything flattenable, or L{None}
    @ivar default: The default contents of this slot, if it is left unfilled.
        If this is L{None}, an L{UnfilledSlot} will be raised, rather than
        L{None} actually being used.

    @type filename: C{str} or L{None}
    @ivar filename: The name of the XML file from which this tag was parsed.
        If it was not parsed from an XML file, L{None}.

    @type lineNumber: C{int} or L{None}
    @ivar lineNumber: The line number on which this tag was encountered in the
        XML file from which it was parsed.  If it was not parsed from an XML
        file, L{None}.

    @type columnNumber: C{int} or L{None}
    @ivar columnNumber: The column number at which this tag was encountered in
        the XML file from which it was parsed.  If it was not parsed from an
        XML file, L{None}.
    """

    def __init__(self, name, default=None, filename=None, lineNumber=None,
                 columnNumber=None):
        self.name = name
        self.children = []
        self.default = default
        self.filename = filename
        self.lineNumber = lineNumber
        self.columnNumber = columnNumber


    def __repr__(self):
        return "slot(%r)" % (self.name,)



class Tag(object):
    """
    A L{Tag} represents an XML tags with a tag name, attributes, and children.
    A L{Tag} can be constructed using the special L{twisted.web.template.tags}
    object, or it may be constructed directly with a tag name. L{Tag}s have a
    special method, C{__call__}, which makes representing trees of XML natural
    using pure python syntax.

    @ivar tagName: The name of the represented element.  For a tag like
        C{<div></div>}, this would be C{"div"}.
    @type tagName: C{str}

    @ivar attributes: The attributes of the element.
    @type attributes: C{dict} mapping C{str} to renderable objects.

    @ivar children: The child L{Tag}s of this C{Tag}.
    @type children: C{list} of renderable objects.

    @ivar render: The name of the render method to use for this L{Tag}.  This
        name will be looked up at render time by the
        L{twisted.web.template.Element} doing the rendering, via
        L{twisted.web.template.Element.lookupRenderMethod}, to determine which
        method to call.
    @type render: C{str}

    @type filename: C{str} or L{None}
    @ivar filename: The name of the XML file from which this tag was parsed.
        If it was not parsed from an XML file, L{None}.

    @type lineNumber: C{int} or L{None}
    @ivar lineNumber: The line number on which this tag was encountered in the
        XML file from which it was parsed.  If it was not parsed from an XML
        file, L{None}.

    @type columnNumber: C{int} or L{None}
    @ivar columnNumber: The column number at which this tag was encountered in
        the XML file from which it was parsed.  If it was not parsed from an
        XML file, L{None}.

    @type slotData: C{dict} or L{None}
    @ivar slotData: The data which can fill slots.  If present, a dictionary
        mapping slot names to renderable values.  The values in this dict might
        be anything that can be present as the child of a L{Tag}; strings,
        lists, L{Tag}s, generators, etc.
    """

    slotData = None
    filename = None
    lineNumber = None
    columnNumber = None

    def __init__(self, tagName, attributes=None, children=None, render=None,
                 filename=None, lineNumber=None, columnNumber=None):
        self.tagName = tagName
        self.render = render
        if attributes is None:
            self.attributes = {}
        else:
            self.attributes = attributes
        if children is None:
            self.children = []
        else:
            self.children = children
        if filename is not None:
            self.filename = filename
        if lineNumber is not None:
            self.lineNumber = lineNumber
        if columnNumber is not None:
            self.columnNumber = columnNumber


    def fillSlots(self, **slots):
        """
        Remember the slots provided at this position in the DOM.

        During the rendering of children of this node, slots with names in
        C{slots} will be rendered as their corresponding values.

        @return: C{self}. This enables the idiom C{return tag.fillSlots(...)} in
            renderers.
        """
        if self.slotData is None:
            self.slotData = {}
        self.slotData.update(slots)
        return self


    def __call__(self, *children, **kw):
        """
        Add children and change attributes on this tag.

        This is implemented using __call__ because it then allows the natural
        syntax::

          table(tr1, tr2, width="100%", height="50%", border="1")

        Children may be other tag instances, strings, functions, or any other
        object which has a registered flatten.

        Attributes may be 'transparent' tag instances (so that
        C{a(href=transparent(data="foo", render=myhrefrenderer))} works),
        strings, functions, or any other object which has a registered
        flattener.

        If the attribute is a python keyword, such as 'class', you can add an
        underscore to the name, like 'class_'.

        There is one special keyword argument, 'render', which will be used as
        the name of the renderer and saved as the 'render' attribute of this
        instance, rather than the DOM 'render' attribute in the attributes
        dictionary.
        """
        self.children.extend(children)

        for k, v in iteritems(kw):
            if k[-1] == '_':
                k = k[:-1]

            if k == 'render':
                self.render = v
            else:
                self.attributes[k] = v
        return self


    def _clone(self, obj, deep):
        """
        Clone an arbitrary object; used by L{Tag.clone}.

        @param obj: an object with a clone method, a list or tuple, or something
            which should be immutable.

        @param deep: whether to continue cloning child objects; i.e. the
            contents of lists, the sub-tags within a tag.

        @return: a clone of C{obj}.
        """
        if hasattr(obj, 'clone'):
            return obj.clone(deep)
        elif isinstance(obj, (list, tuple)):
            return [self._clone(x, deep) for x in obj]
        else:
            return obj


    def clone(self, deep=True):
        """
        Return a clone of this tag. If deep is True, clone all of this tag's
        children. Otherwise, just shallow copy the children list without copying
        the children themselves.
        """
        if deep:
            newchildren = [self._clone(x, True) for x in self.children]
        else:
            newchildren = self.children[:]
        newattrs = self.attributes.copy()
        for key in newattrs.keys():
            newattrs[key] = self._clone(newattrs[key], True)

        newslotdata = None
        if self.slotData:
            newslotdata = self.slotData.copy()
            for key in newslotdata:
                newslotdata[key] = self._clone(newslotdata[key], True)

        newtag = Tag(
            self.tagName,
            attributes=newattrs,
            children=newchildren,
            render=self.render,
            filename=self.filename,
            lineNumber=self.lineNumber,
            columnNumber=self.columnNumber)
        newtag.slotData = newslotdata

        return newtag


    def clear(self):
        """
        Clear any existing children from this tag.
        """
        self.children = []
        return self


    def __repr__(self):
        rstr = ''
        if self.attributes:
            rstr += ', attributes=%r' % self.attributes
        if self.children:
            rstr += ', children=%r' % self.children
        return "Tag(%r%s)" % (self.tagName, rstr)



voidElements = ('img', 'br', 'hr', 'base', 'meta', 'link', 'param', 'area',
                'input', 'col', 'basefont', 'isindex', 'frame', 'command',
                'embed', 'keygen', 'source', 'track', 'wbs')


class CDATA(object):
    """
    A C{<![CDATA[]]>} block from a template.  Given a separate representation in
    the DOM so that they may be round-tripped through rendering without losing
    information.

    @ivar data: The data between "C{<![CDATA[}" and "C{]]>}".
    @type data: C{unicode}
    """
    def __init__(self, data):
        self.data = data


    def __repr__(self):
        return 'CDATA(%r)' % (self.data,)



class Comment(object):
    """
    A C{<!-- -->} comment from a template.  Given a separate representation in
    the DOM so that they may be round-tripped through rendering without losing
    information.

    @ivar data: The data between "C{<!--}" and "C{-->}".
    @type data: C{unicode}
    """

    def __init__(self, data):
        self.data = data


    def __repr__(self):
        return 'Comment(%r)' % (self.data,)



class CharRef(object):
    """
    A numeric character reference.  Given a separate representation in the DOM
    so that non-ASCII characters may be output as pure ASCII.

    @ivar ordinal: The ordinal value of the unicode character to which this is
        object refers.
    @type ordinal: C{int}

    @since: 12.0
    """
    def __init__(self, ordinal):
        self.ordinal = ordinal


    def __repr__(self):
        return "CharRef(%d)" % (self.ordinal,)