tdi.interfaces

1 # -*- coding: ascii -*- 2 r""" 3 :Copyright: 4 5 Copyright 2007 - 2015 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 if __doc__: 30 # pylint: disable = redefined-builtin 31 __doc__ = __doc__.encode('ascii').decode('unicode_escape') 32 __author__ = r"Andr\xe9 Malo".encode('ascii').decode('unicode_escape') 33 __docformat__ = "restructuredtext en" 34 35

36 -def implements(obj, *interfaces):

37 """ 38 Check if `obj` implements one or more interfaces. 39 40 The check looks for the ``__implements__`` attribute of ``obj``, which 41 is expected to be an iterable containing the implemented interfaces. 42 43 :Parameters: 44 `obj` : ``type`` or ``object`` 45 The object to inspect 46 47 `interfaces` : ``tuple`` 48 Interface classes to check 49 50 :Return: Are all interfaces implemented? 51 :Rtype: ``bool`` 52 """ 53 try: 54 impls = tuple(obj.__implements__) 55 except AttributeError: 56 return False 57 58 def subclass(sub, sup, _subclass=issubclass): 59 """ Type error proof subclass check """ 60 try: 61 return _subclass(sub, sup) 62 except TypeError: 63 return False

64 65 # O(n**2), better ideas welcome, however, usually the list is pretty 66 # small. 67 for interface in interfaces: 68 for impl in impls: 69 if subclass(impl, interface): 70 break 71 else: 72 return False 73 return True 74 75

76 -class ListenerInterface(object):

77 """ 78 Interface for a parser/lexer event listener. 79 """ 80

81 - def handle_text(self, data):

82 """ 83 Handle text data 84 85 :Parameters: 86 `data` : ``str`` 87 The text data to handle 88 """

89

90 - def handle_escape(self, escaped, data):

91 """ 92 Handle escaped data 93 94 :Parameters: 95 `escaped` : ``str`` 96 The escaped string (unescaped, despite the name) 97 98 `data` : ``str`` 99 The full escape sequence 100 """

101

102 - def handle_starttag(self, name, attrs, closed, data):

103 """ 104 Handle start tag (``<foo ....>``) 105 106 :Parameters: 107 `name` : ``str`` 108 The element name (``''`` for empty tag) 109 110 `attrs` : ``list`` 111 The attributes (``[(name, value), ...]``), where ``value`` 112 may be ``None`` for short attributes. 113 114 `closed` : ``bool`` 115 Is the start tag closed? In that case, no endtag will be needed. 116 117 `data` : ``str`` 118 The raw tag string 119 """

120

121 - def handle_endtag(self, name, data):

122 """ 123 Handle end tag (``</foo>``) 124 125 :Parameters: 126 `name` : ``str`` 127 The element name (``''`` for empty tag) 128 129 `data` : ``str`` 130 The raw tag string 131 """

132

133 - def handle_comment(self, data):

134 """ 135 Handle comment (````) 136 137 :Parameters: 138 `data` : ``str`` 139 The comment block 140 """

141

142 - def handle_msection(self, name, value, data):

143 """ 144 Handle marked section (``<![name[...]]>`` or ``<![name ...]>``) 145 146 The ``<![name ... ]>`` sections are MS specific. ``markupbase`` 147 comments:: 148 149 # An analysis of the MS-Word extensions is available at 150 # http://www.planetpublish.com/xmlarena/xap/Thursday/WordtoXML.pdf 151 152 :Parameters: 153 `name` : ``str`` 154 The section name 155 156 `value` : ``str`` 157 The section value 158 159 `data` : ``str`` 160 The section block 161 """

162

163 - def handle_decl(self, name, value, data):

164 """ 165 Handle declaration (``<!...>``) 166 167 :Parameters: 168 `name` : ``str`` 169 The name of the declaration block 170 171 `value` : ``str`` 172 The value of the declaration block 173 174 `data` : ``str`` 175 The declaration block 176 """

177

178 - def handle_pi(self, data):

179 """ 180 Handle Processing instruction (``<? ... ?>``) 181 182 :Parameters: 183 `data` : ``str`` 184 The PI block 185 """

186 187

188 -class ParserInterface(object):

189 """ Interface for template parsers """ 190

191 - def feed(self, food):

192 """ 193 Take a chunk of data and generate parser events out of it 194 195 :Parameters: 196 `food` : ``str`` 197 The data to process 198 """

199

200 - def finalize(self):

201 """ 202 Finish the parser 203 204 Calling `finalize` indicates that `feed` is not called any more 205 and advises the parser to flush all pending events. 206 """

207 208

209 -class DTDInterface(object):

210 """ Interface for DTD query classes """ 211

212 - def cdata(self, name):

213 """ 214 Determine if the element `name` is a CDATA element 215 216 :Parameters: 217 `name` : ``str`` 218 The name of the element (lowercased) 219 220 :Return: CDATA element? 221 :Rtype: ``bool`` 222 """

223

224 - def nestable(self, outer, inner):

225 """ 226 Determine if the element `inner` may occur in `outer`. 227 228 :Parameters: 229 `outer` : ``str`` 230 The name of the outer element (lowercased) 231 232 `inner` : ``str`` 233 The name of the inner element (lowercased) 234 235 :Return: nestable? 236 :Rtype: ``bool`` 237 """

238

239 - def empty(self, name):

240 """ 241 Determines if the element `name` is empty. 242 243 :Parameters: 244 `name` : ``str`` 245 The element name (lowercased) 246 247 :Return: Empty element? 248 :Rtype: ``bool`` 249 """

250 251

252 -class AttributeAnalyzerInterface(object):

253 """ 254 Interface for Attribute analyzers 255 256 :IVariables: 257 `attribute` : ``str`` 258 The attribute name 259 260 `scope` : ``str`` 261 The scope attribute name 262 """ 263

264 - def __call__(self, normalize, attr, name=''):

265 """ 266 Analyze attributes 267 268 :Parameters: 269 `normalize` : ``callable`` 270 Element and attribute name normalizer 271 272 `attr` : sequence 273 (key, value) list of attributes. value may be ``None`` 274 275 `name` : ``str`` 276 Name to treat as attribute. Only applied if set and not empty. 277 278 :Return: The (possibly) reduced attributes and a dict of special 279 attributes. All of the special attributes are optional: 280 281 ``attribute`` 282 ``(flags, name)`` 283 ``overlay`` 284 ``(flags, name)`` or ``None`` 285 ``scope`` 286 ``(flags, name)`` or ``None`` 287 288 :Rtype: ``tuple`` 289 """

290 291

292 -class BuilderInterface(object):

293 """ Interface for builders """ 294

295 - def finalize(self):

296 """ 297 Finalize the build 298 299 Flush all buffers, finalize the parse tree, etc 300 301 :Return: The built result 302 :Rtype: any 303 """

304 305

306 -class BuildingListenerInterface(ListenerInterface):

307 """ 308 Extensions to the listener interface 309 310 :IVariables: 311 `encoder` : `EncoderInterface` 312 Encoder 313 314 `decoder` : `DecoderInterface` 315 Decoder 316 317 `encoding` : ``str`` 318 Encoding of the template 319 320 `analyze` : `AttributeAnalyzerInterface` 321 Attribute analyzer 322 """ 323

324 - def handle_encoding(self, encoding):

325 """ 326 Handle an encoding declaration 327 328 :Parameters: 329 `encoding` : ``str`` 330 The encoding to handle 331 """

332 333

334 -class FilterFactoryInterface(object):

335 """ Interface for a factory returning a filter """ 336

337 - def __call__(self, builder):

338 """ 339 Determine the actual filter instance 340 341 :Parameters: 342 `builder` : `BuildingListenerInterface` 343 The next level builder 344 345 :Return: The new filter instance 346 :Rtype: `BuildingListenerInterface` 347 """

348 349

350 -class DecoderInterface(object):

351 """ 352 Decoder Interface 353 354 :IVariables: 355 `encoding` : ``str`` 356 The source encoding 357 """ 358

359 - def normalize(self, name):

360 """ 361 Normalize a name 362 363 :Parameters: 364 `name` : ``basestring`` 365 The name to normalize 366 367 :Return: The normalized name 368 :Rtype: ``basestring`` 369 """

370

371 - def decode(self, value, errors='strict'):

372 """ 373 Decode an arbitrary value 374 375 :Parameters: 376 `value` : ``str`` 377 attribute value 378 379 `errors` : ``str`` 380 Error handler description 381 382 :Return: The decoded value 383 :Rtype: ``unicode`` 384 """

385

386 - def attribute(self, value, errors='strict'):

387 """ 388 Decode a raw attribute value 389 390 :Parameters: 391 `value` : ``str`` 392 Raw attribute value 393 394 `errors` : ``str`` 395 Error handler description 396 397 :Return: The decoded attribute 398 :Rtype: ``unicode`` 399 """

400 401

402 -class EncoderInterface(object):

403 """ 404 Encoder Interface 405 406 :IVariables: 407 `encoding` : ``str`` 408 The target encoding 409 """ 410

411 - def starttag(self, name, attr, closed):

412 """ 413 Build a starttag 414 415 :Parameters: 416 `name` : ``str`` 417 The tag name 418 419 `attr` : iterable 420 The tag attributes (``((name, value), ...)``) 421 422 `closed` : ``bool`` 423 Closed tag? 424 425 :Return: The starttag 426 :Rtype: ``str`` 427 """

428

429 - def endtag(self, name):

430 """ 431 Build an endtag 432 433 :Parameters: 434 `name` : ``str`` 435 Tag name 436 437 :Return: The endtag 438 :Rtype: ``str`` 439 """

440

441 - def name(self, name):

442 """ 443 Encode a name (tag or attribute name) 444 445 :Parameters: 446 `name` : ``basestring`` 447 Name 448 449 :Return: The encoded name 450 :Rtype: ``str`` 451 """

452

453 - def attribute(self, value):

454 """ 455 Attribute encoder 456 457 Note that this method also needs to put quotes around the attribute 458 (if applicable). 459 460 :Parameters: 461 `value` : ``basestring`` 462 The value to encode 463 464 :Return: The encoded attribute 465 :Rtype: ``str`` 466 """

467

468 - def content(self, value):

469 """ 470 Regular text content encoder 471 472 :Parameters: 473 `value` : ``basestring`` 474 The value to encode 475 476 :Return: The encoded attribute 477 :Rtype: ``str`` 478 """

479

480 - def encode(self, value):

481 """ 482 Character-encode a unicode string to `encoding` 483 484 :Parameters: 485 `value` : ``unicode`` 486 The value to encode 487 488 :Return: The encoded value 489 :Rtype: ``str`` 490 """

491

492 - def escape(self, value):

493 """ 494 Escape text (scan for sequences needing escaping and escape them) 495 496 :Parameters: 497 `value` : ``str`` 498 The value to escape 499 500 :Return: The escaped value 501 :Rtype: ``str`` 502 """

503 504

505 -class ModelAdapterInterface(object):

506 """ 507 Model Adapter Interface 508 509 :IVariables: 510 `modelmethod` : ``callable`` 511 Function to resolve model methods 512 513 `new` : ``callable`` 514 Function to create an adapter with a new model instance. 515 516 `emit_escaped` : ``bool`` 517 Emit escaped text as escape sequence? (Needed for pre-rendering) 518 """

519 520

521 -class MemoizerInterface(object):

522 """ 523 Interface for factory memoizers 524 525 :Note: dicts implement this easily, but without the (optional) local lock. 526 527 :IVariables: 528 `lock` : Lock 529 A lock object for the cache access. The lock needs an acquire method 530 and a release method. If the attribute does not exist or is ``None``, 531 cache access is serialized using a global lock. If you have multiple 532 caches (for whatever reasons) this local lock is handy. 533 """ 534

535 - def __contains__(self, key):

536 """ 537 Is this key memoized already? 538 539 :Parameters: 540 `key` : hashable 541 Key 542 543 :Return: Is it? 544 :Rtype: ``bool`` 545 546 :Exceptions: 547 - `TypeError` : Unhashable key 548 """

549

550 - def __getitem__(self, key):

551 """ 552 Get memoized entry 553 554 :Parameters: 555 `key` : hashable 556 Key 557 558 :Return: The memoized value 559 :Rtype: any 560 561 :Exceptions: 562 - `TypeError` : Unhashable key 563 """

564

565 - def __setitem__(self, key, value):

566 """ 567 Memoize entry 568 569 :Parameters: 570 `key` : hashable 571 Key 572 573 `value` : any 574 The value to memoize 575 576 :Exceptions: 577 - `TypeError` : Unhashable key 578 """

579

Source Code for Module tdi.interfaces