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