Package tdi :: Module interfaces
[frames] | no frames]

Source Code for Module tdi.interfaces

  1  # -*- coding: ascii -*- 
  2  # 
  3  # Copyright 2007 - 2013 
  4  # Andr\xe9 Malo or his licensors, as applicable 
  5  # 
  6  # Licensed under the Apache License, Version 2.0 (the "License"); 
  7  # you may not use this file except in compliance with the License. 
  8  # You may obtain a copy of the License at 
  9  # 
 10  #     http://www.apache.org/licenses/LICENSE-2.0 
 11  # 
 12  # Unless required by applicable law or agreed to in writing, software 
 13  # distributed under the License is distributed on an "AS IS" BASIS, 
 14  # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 
 15  # See the License for the specific language governing permissions and 
 16  # limitations under the License. 
 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   
29 -def implements(obj, *interfaces):
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 # O(n**2), better ideas welcome, however, usually the list is pretty 59 # small. 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
69 -class ListenerInterface(object):
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
83 - def handle_escape(self, escaped, data):
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
95 - def handle_starttag(self, name, attrs, closed, data):
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
114 - def handle_endtag(self, name, data):
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
126 - def handle_comment(self, data):
127 """ 128 Handle comment (``<!-- ... -->``) 129 130 :Parameters: 131 `data` : ``str`` 132 The comment block 133 """
134
135 - def handle_msection(self, name, value, data):
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
156 - def handle_decl(self, name, value, data):
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
171 - def handle_pi(self, data):
172 """ 173 Handle Processing instruction (``<? ... ?>``) 174 175 :Parameters: 176 `data` : ``str`` 177 The PI block 178 """
179 180
181 -class ParserInterface(object):
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
193 - def finalize(self):
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
202 -class DTDInterface(object):
203 """ Interface for DTD query classes """ 204
205 - def cdata(self, name):
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
217 - def nestable(self, outer, inner):
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
232 - def empty(self, name):
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
245 -class AttributeAnalyzerInterface(object):
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
285 -class BuilderInterface(object):
286 """ Interface for builders """ 287
288 - def finalize(self):
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
299 -class BuildingListenerInterface(ListenerInterface):
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
317 - def handle_encoding(self, encoding):
318 """ 319 Handle an encoding declaration 320 321 :Parameters: 322 `encoding` : ``str`` 323 The encoding to handle 324 """
325 326
327 -class FilterFactoryInterface(object):
328 """ Interface for a factory returning a filter """ 329
330 - def __call__(self, builder):
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
343 -class DecoderInterface(object):
344 """ 345 Decoder Interface 346 347 :IVariables: 348 `encoding` : ``str`` 349 The source encoding 350 """ 351
352 - def normalize(self, name):
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
395 -class EncoderInterface(object):
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
422 - def endtag(self, name):
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
446 - def attribute(self, value):
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
473 - def encode(self, value):
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
485 - def escape(self, value):
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
498 -class ModelAdapterInterface(object):
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
511 -class MemoizerInterface(object):
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
525 - def __contains__(self, key):
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
540 - def __getitem__(self, key):
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
555 - def __setitem__(self, key, value):
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