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

Source Code for Module tdi.interfaces

  1  # -*- coding: ascii -*- 
  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   
33 -def implements(obj, *interfaces):
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 # O(n**2), better ideas welcome, however, usually the list is pretty 63 # small. 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
73 -class ListenerInterface(object):
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
87 - def handle_escape(self, escaped, data):
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
99 - def handle_starttag(self, name, attrs, closed, data):
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
118 - def handle_endtag(self, name, data):
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
130 - def handle_comment(self, data):
131 """ 132 Handle comment (``<!-- ... -->``) 133 134 :Parameters: 135 `data` : ``str`` 136 The comment block 137 """
138
139 - def handle_msection(self, name, value, data):
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
160 - def handle_decl(self, name, value, data):
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
175 - def handle_pi(self, data):
176 """ 177 Handle Processing instruction (``<? ... ?>``) 178 179 :Parameters: 180 `data` : ``str`` 181 The PI block 182 """
183 184
185 -class ParserInterface(object):
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
197 - def finalize(self):
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
206 -class DTDInterface(object):
207 """ Interface for DTD query classes """ 208
209 - def cdata(self, name):
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
221 - def nestable(self, outer, inner):
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
236 - def empty(self, name):
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
249 -class AttributeAnalyzerInterface(object):
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
289 -class BuilderInterface(object):
290 """ Interface for builders """ 291
292 - def finalize(self):
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
303 -class BuildingListenerInterface(ListenerInterface):
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
321 - def handle_encoding(self, encoding):
322 """ 323 Handle an encoding declaration 324 325 :Parameters: 326 `encoding` : ``str`` 327 The encoding to handle 328 """
329 330
331 -class FilterFactoryInterface(object):
332 """ Interface for a factory returning a filter """ 333
334 - def __call__(self, builder):
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
347 -class DecoderInterface(object):
348 """ 349 Decoder Interface 350 351 :IVariables: 352 `encoding` : ``str`` 353 The source encoding 354 """ 355
356 - def normalize(self, name):
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
399 -class EncoderInterface(object):
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
426 - def endtag(self, name):
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
450 - def attribute(self, value):
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
477 - def encode(self, value):
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
489 - def escape(self, value):
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
502 -class ModelAdapterInterface(object):
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
518 -class MemoizerInterface(object):
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
532 - def __contains__(self, key):
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
547 - def __getitem__(self, key):
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
562 - def __setitem__(self, key, value):
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