1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17 """
18 ====================================
19 Interfaces used in the tdi package
20 ====================================
21
22 The module provides all interfaces required or provided by the `tdi`
23 package and a small function to check for them.
24 """
25 __author__ = u"Andr\xe9 Malo"
26 __docformat__ = "restructuredtext en"
27
28
30 """
31 Check if `obj` implements one or more interfaces.
32
33 The check looks for the ``__implements__`` attribute of ``obj``, which
34 is expected to be an iterable containing the implemented interfaces.
35
36 :Parameters:
37 `obj` : ``type`` or ``object``
38 The object to inspect
39
40 `interfaces` : ``tuple``
41 Interface classes to check
42
43 :Return: Are all interfaces implemented?
44 :Rtype: ``bool``
45 """
46 try:
47 impls = tuple(obj.__implements__)
48 except AttributeError:
49 return False
50
51 def subclass(sub, sup, _subclass=issubclass):
52 """ Type error proof subclass check """
53 try:
54 return _subclass(sub, sup)
55 except TypeError:
56 return False
57
58
59
60 for interface in interfaces:
61 for impl in impls:
62 if subclass(impl, interface):
63 break
64 else:
65 return False
66 return True
67
68
70 """
71 Interface for a parser/lexer event listener.
72 """
73
74 - def handle_text(self, data):
75 """
76 Handle text data
77
78 :Parameters:
79 `data` : ``str``
80 The text data to handle
81 """
82
84 """
85 Handle escaped data
86
87 :Parameters:
88 `escaped` : ``str``
89 The escaped string (unescaped, despite the name)
90
91 `data` : ``str``
92 The full escape sequence
93 """
94
96 """
97 Handle start tag (``<foo ....>``)
98
99 :Parameters:
100 `name` : ``str``
101 The element name (``''`` for empty tag)
102
103 `attrs` : ``list``
104 The attributes (``[(name, value), ...]``), where ``value``
105 may be ``None`` for short attributes.
106
107 `closed` : ``bool``
108 Is the start tag closed? In that case, no endtag will be needed.
109
110 `data` : ``str``
111 The raw tag string
112 """
113
115 """
116 Handle end tag (``</foo>``)
117
118 :Parameters:
119 `name` : ``str``
120 The element name (``''`` for empty tag)
121
122 `data` : ``str``
123 The raw tag string
124 """
125
134
136 """
137 Handle marked section (``<![name[...]]>`` or ``<![name ...]>``)
138
139 The ``<![name ... ]>`` sections are MS specific. ``markupbase``
140 comments::
141
142 # An analysis of the MS-Word extensions is available at
143 # http://www.planetpublish.com/xmlarena/xap/Thursday/WordtoXML.pdf
144
145 :Parameters:
146 `name` : ``str``
147 The section name
148
149 `value` : ``str``
150 The section value
151
152 `data` : ``str``
153 The section block
154 """
155
157 """
158 Handle declaration (``<!...>``)
159
160 :Parameters:
161 `name` : ``str``
162 The name of the declaration block
163
164 `value` : ``str``
165 The value of the declaration block
166
167 `data` : ``str``
168 The declaration block
169 """
170
172 """
173 Handle Processing instruction (``<? ... ?>``)
174
175 :Parameters:
176 `data` : ``str``
177 The PI block
178 """
179
180
182 """ Interface for template parsers """
183
184 - def feed(self, food):
185 """
186 Take a chunk of data and generate parser events out of it
187
188 :Parameters:
189 `food` : ``str``
190 The data to process
191 """
192
194 """
195 Finish the parser
196
197 Calling `finalize` indicates that `feed` is not called any more
198 and advises the parser to flush all pending events.
199 """
200
201
203 """ Interface for DTD query classes """
204
206 """
207 Determine if the element `name` is a CDATA element
208
209 :Parameters:
210 `name` : ``str``
211 The name of the element (lowercased)
212
213 :Return: CDATA element?
214 :Rtype: ``bool``
215 """
216
218 """
219 Determine if the element `inner` may occur in `outer`.
220
221 :Parameters:
222 `outer` : ``str``
223 The name of the outer element (lowercased)
224
225 `inner` : ``str``
226 The name of the inner element (lowercased)
227
228 :Return: nestable?
229 :Rtype: ``bool``
230 """
231
233 """
234 Determines if the element `name` is empty.
235
236 :Parameters:
237 `name` : ``str``
238 The element name (lowercased)
239
240 :Return: Empty element?
241 :Rtype: ``bool``
242 """
243
244
246 """
247 Interface for Attribute analyzers
248
249 :IVariables:
250 `attribute` : ``str``
251 The attribute name
252
253 `scope` : ``str``
254 The scope attribute name
255 """
256
257 - def __call__(self, normalize, attr, name=''):
258 """
259 Analyze attributes
260
261 :Parameters:
262 `normalize` : ``callable``
263 Element and attribute name normalizer
264
265 `attr` : sequence
266 (key, value) list of attributes. value may be ``None``
267
268 `name` : ``str``
269 Name to treat as attribute. Only applied if set and not empty.
270
271 :Return: The (possibly) reduced attributes and a dict of special
272 attributes. All of the special attributes are optional:
273
274 ``attribute``
275 ``(flags, name)``
276 ``overlay``
277 ``(flags, name)`` or ``None``
278 ``scope``
279 ``(flags, name)`` or ``None``
280
281 :Rtype: ``tuple``
282 """
283
284
286 """ Interface for builders """
287
289 """
290 Finalize the build
291
292 Flush all buffers, finalize the parse tree, etc
293
294 :Return: The built result
295 :Rtype: any
296 """
297
298
300 """
301 Extensions to the listener interface
302
303 :IVariables:
304 `encoder` : `EncoderInterface`
305 Encoder
306
307 `decoder` : `DecoderInterface`
308 Decoder
309
310 `encoding` : ``str``
311 Encoding of the template
312
313 `analyze` : `AttributeAnalyzerInterface`
314 Attribute analyzer
315 """
316
318 """
319 Handle an encoding declaration
320
321 :Parameters:
322 `encoding` : ``str``
323 The encoding to handle
324 """
325
326
328 """ Interface for a factory returning a filter """
329
331 """
332 Determine the actual filter instance
333
334 :Parameters:
335 `builder` : `BuildingListenerInterface`
336 The next level builder
337
338 :Return: The new filter instance
339 :Rtype: `BuildingListenerInterface`
340 """
341
342
344 """
345 Decoder Interface
346
347 :IVariables:
348 `encoding` : ``str``
349 The source encoding
350 """
351
353 """
354 Normalize a name
355
356 :Parameters:
357 `name` : ``basestring``
358 The name to normalize
359
360 :Return: The normalized name
361 :Rtype: ``basestring``
362 """
363
364 - def decode(self, value, errors='strict'):
365 """
366 Decode an arbitrary value
367
368 :Parameters:
369 `value` : ``str``
370 attribute value
371
372 `errors` : ``str``
373 Error handler description
374
375 :Return: The decoded value
376 :Rtype: ``unicode``
377 """
378
379 - def attribute(self, value, errors='strict'):
380 """
381 Decode a raw attribute value
382
383 :Parameters:
384 `value` : ``str``
385 Raw attribute value
386
387 `errors` : ``str``
388 Error handler description
389
390 :Return: The decoded attribute
391 :Rtype: ``unicode``
392 """
393
394
396 """
397 Encoder Interface
398
399 :IVariables:
400 `encoding` : ``str``
401 The target encoding
402 """
403
404 - def starttag(self, name, attr, closed):
405 """
406 Build a starttag
407
408 :Parameters:
409 `name` : ``str``
410 The tag name
411
412 `attr` : iterable
413 The tag attributes (``((name, value), ...)``)
414
415 `closed` : ``bool``
416 Closed tag?
417
418 :Return: The starttag
419 :Rtype: ``str``
420 """
421
423 """
424 Build an endtag
425
426 :Parameters:
427 `name` : ``str``
428 Tag name
429
430 :Return: The endtag
431 :Rtype: ``str``
432 """
433
434 - def name(self, name):
435 """
436 Encode a name (tag or attribute name)
437
438 :Parameters:
439 `name` : ``basestring``
440 Name
441
442 :Return: The encoded name
443 :Rtype: ``str``
444 """
445
447 """
448 Attribute encoder
449
450 Note that this method also needs to put quotes around the attribute
451 (if applicable).
452
453 :Parameters:
454 `value` : ``basestring``
455 The value to encode
456
457 :Return: The encoded attribute
458 :Rtype: ``str``
459 """
460
461 - def content(self, value):
462 """
463 Regular text content encoder
464
465 :Parameters:
466 `value` : ``basestring``
467 The value to encode
468
469 :Return: The encoded attribute
470 :Rtype: ``str``
471 """
472
474 """
475 Character-encode a unicode string to `encoding`
476
477 :Parameters:
478 `value` : ``unicode``
479 The value to encode
480
481 :Return: The encoded value
482 :Rtype: ``str``
483 """
484
486 """
487 Escape text (scan for sequences needing escaping and escape them)
488
489 :Parameters:
490 `value` : ``str``
491 The value to escape
492
493 :Return: The escaped value
494 :Rtype: ``str``
495 """
496
497
499 """
500 Model Adapter Interface
501
502 :IVariables:
503 `modelmethod` : ``callable``
504 The function to resolve model methods
505
506 `emit_escaped` : ``bool``
507 Emit escaped text as escape sequence? (Needed for pre-rendering)
508 """
509
510
512 """
513 Interface for factory memoizers
514
515 :Note: dicts implement this easily, but without the (optional) local lock.
516
517 :IVariables:
518 `lock` : Lock
519 A lock object for the cache access. The lock needs an acquire method
520 and a release method. If the attribute does not exist or is ``None``,
521 cache access is serialized using a global lock. If you have multiple
522 caches (for whatever reasons) this local lock is handy.
523 """
524
526 """
527 Is this key memoized already?
528
529 :Parameters:
530 `key` : hashable
531 Key
532
533 :Return: Is it?
534 :Rtype: ``bool``
535
536 :Exceptions:
537 - `TypeError` : Unhashable key
538 """
539
541 """
542 Get memoized entry
543
544 :Parameters:
545 `key` : hashable
546 Key
547
548 :Return: The memoized value
549 :Rtype: any
550
551 :Exceptions:
552 - `TypeError` : Unhashable key
553 """
554
556 """
557 Memoize entry
558
559 :Parameters:
560 `key` : hashable
561 Key
562
563 `value` : any
564 The value to memoize
565
566 :Exceptions:
567 - `TypeError` : Unhashable key
568 """
569