Package epydoc :: Module apidoc
[hide private]
[frames] | no frames]

Source Code for Module epydoc.apidoc

   1  # epydoc -- API Documentation Classes 
   2  # 
   3  # Copyright (C) 2005 Edward Loper 
   4  # Author: Edward Loper <edloper@loper.org> 
   5  # URL: <http://epydoc.sf.net> 
   6  # 
   7  # $Id: apidoc.py 1729 2008-02-19 16:49:16Z edloper $ 
   8   
   9  """ 
  10  Classes for encoding API documentation about Python programs. 
  11  These classes are used as a common representation for combining 
  12  information derived from introspection and from parsing. 
  13   
  14  The API documentation for a Python program is encoded using a graph of 
  15  L{APIDoc} objects, each of which encodes information about a single 
  16  Python variable or value.  C{APIDoc} has two direct subclasses: 
  17  L{VariableDoc}, for documenting variables; and L{ValueDoc}, for 
  18  documenting values.  The C{ValueDoc} class is subclassed further, to 
  19  define the different pieces of information that should be recorded 
  20  about each value type: 
  21   
  22  G{classtree: APIDoc} 
  23   
  24  The distinction between variables and values is intentionally made 
  25  explicit.  This allows us to distinguish information about a variable 
  26  itself (such as whether it should be considered 'public' in its 
  27  containing namespace) from information about the value it contains 
  28  (such as what type the value has).  This distinction is also important 
  29  because several variables can contain the same value: each variable 
  30  should be described by a separate C{VariableDoc}; but we only need one 
  31  C{ValueDoc}, since they share a single value. 
  32   
  33  @todo: Add a cache to canonical name lookup? 
  34  """ 
  35  __docformat__ = 'epytext en' 
  36   
  37  ###################################################################### 
  38  ## Imports 
  39  ###################################################################### 
  40   
  41  import types, re, os.path, pickle 
  42  from epydoc import log 
  43  import epydoc 
  44  import __builtin__ 
  45  from epydoc.compat import * # Backwards compatibility 
  46  from epydoc.util import decode_with_backslashreplace, py_src_filename 
  47  import epydoc.markup.pyval_repr 
  48   
  49  ###################################################################### 
  50  # Dotted Names 
  51  ###################################################################### 
  52   
53 -class DottedName:
54 """ 55 A sequence of identifiers, separated by periods, used to name a 56 Python variable, value, or argument. The identifiers that make up 57 a dotted name can be accessed using the indexing operator: 58 59 >>> name = DottedName('epydoc', 'api_doc', 'DottedName') 60 >>> print name 61 epydoc.apidoc.DottedName 62 >>> name[1] 63 'api_doc' 64 """ 65 UNREACHABLE = "??" 66 _IDENTIFIER_RE = re.compile("""(?x) 67 (%s | # UNREACHABLE marker, or.. 68 (script-)? # Prefix: script (not a module) 69 \w+ # Identifier (yes, identifiers starting with a 70 # digit are allowed. See SF bug #1649347) 71 '?) # Suffix: submodule that is shadowed by a var 72 (-\d+)? # Suffix: unreachable vals with the same name 73 $""" 74 % re.escape(UNREACHABLE)) 75
76 - class InvalidDottedName(ValueError):
77 """ 78 An exception raised by the DottedName constructor when one of 79 its arguments is not a valid dotted name. 80 """
81 82 _ok_identifiers = set() 83 """A cache of identifier strings that have been checked against 84 _IDENTIFIER_RE and found to be acceptable.""" 85
86 - def __init__(self, *pieces, **options):
87 """ 88 Construct a new dotted name from the given sequence of pieces, 89 each of which can be either a C{string} or a C{DottedName}. 90 Each piece is divided into a sequence of identifiers, and 91 these sequences are combined together (in order) to form the 92 identifier sequence for the new C{DottedName}. If a piece 93 contains a string, then it is divided into substrings by 94 splitting on periods, and each substring is checked to see if 95 it is a valid identifier. 96 97 As an optimization, C{pieces} may also contain a single tuple 98 of values. In that case, that tuple will be used as the 99 C{DottedName}'s identifiers; it will I{not} be checked to 100 see if it's valid. 101 102 @kwparam strict: if true, then raise an L{InvalidDottedName} 103 if the given name is invalid. 104 """ 105 if len(pieces) == 1 and isinstance(pieces[0], tuple): 106 self._identifiers = pieces[0] # Optimization 107 return 108 if len(pieces) == 0: 109 raise DottedName.InvalidDottedName('Empty DottedName') 110 self._identifiers = [] 111 for piece in pieces: 112 if isinstance(piece, DottedName): 113 self._identifiers += piece._identifiers 114 elif isinstance(piece, basestring): 115 for subpiece in piece.split('.'): 116 if piece not in self._ok_identifiers: 117 if not self._IDENTIFIER_RE.match(subpiece): 118 if options.get('strict'): 119 raise DottedName.InvalidDottedName( 120 'Bad identifier %r' % (piece,)) 121 else: 122 log.warning("Identifier %r looks suspicious; " 123 "using it anyway." % piece) 124 self._ok_identifiers.add(piece) 125 self._identifiers.append(subpiece) 126 else: 127 raise TypeError('Bad identifier %r: expected ' 128 'DottedName or str' % (piece,)) 129 self._identifiers = tuple(self._identifiers)
130
131 - def __repr__(self):
132 idents = [`ident` for ident in self._identifiers] 133 return 'DottedName(' + ', '.join(idents) + ')'
134
135 - def __str__(self):
136 """ 137 Return the dotted name as a string formed by joining its 138 identifiers with periods: 139 140 >>> print DottedName('epydoc', 'api_doc', DottedName') 141 epydoc.apidoc.DottedName 142 """ 143 return '.'.join(self._identifiers)
144
145 - def __add__(self, other):
146 """ 147 Return a new C{DottedName} whose identifier sequence is formed 148 by adding C{other}'s identifier sequence to C{self}'s. 149 """ 150 if isinstance(other, (basestring, DottedName)): 151 return DottedName(self, other) 152 else: 153 return DottedName(self, *other)
154
155 - def __radd__(self, other):
156 """ 157 Return a new C{DottedName} whose identifier sequence is formed 158 by adding C{self}'s identifier sequence to C{other}'s. 159 """ 160 if isinstance(other, (basestring, DottedName)): 161 return DottedName(other, self) 162 else: 163 return DottedName(*(list(other)+[self]))
164
165 - def __getitem__(self, i):
166 """ 167 Return the C{i}th identifier in this C{DottedName}. If C{i} is 168 a non-empty slice, then return a C{DottedName} built from the 169 identifiers selected by the slice. If C{i} is an empty slice, 170 return an empty list (since empty C{DottedName}s are not valid). 171 """ 172 if isinstance(i, types.SliceType): 173 pieces = self._identifiers[i.start:i.stop] 174 if pieces: return DottedName(pieces) 175 else: return [] 176 else: 177 return self._identifiers[i]
178
179 - def __hash__(self):
180 return hash(self._identifiers)
181
182 - def __cmp__(self, other):
183 """ 184 Compare this dotted name to C{other}. Two dotted names are 185 considered equal if their identifier subsequences are equal. 186 Ordering between dotted names is lexicographic, in order of 187 identifier from left to right. 188 """ 189 if not isinstance(other, DottedName): 190 return -1 191 return cmp(self._identifiers, other._identifiers)
192
193 - def __len__(self):
194 """ 195 Return the number of identifiers in this dotted name. 196 """ 197 return len(self._identifiers)
198
199 - def container(self):
200 """ 201 Return the DottedName formed by removing the last identifier 202 from this dotted name's identifier sequence. If this dotted 203 name only has one name in its identifier sequence, return 204 C{None} instead. 205 """ 206 if len(self._identifiers) == 1: 207 return None 208 else: 209 return DottedName(*self._identifiers[:-1])
210
211 - def dominates(self, name, strict=False):
212 """ 213 Return true if this dotted name is equal to a prefix of 214 C{name}. If C{strict} is true, then also require that 215 C{self!=name}. 216 217 >>> DottedName('a.b').dominates(DottedName('a.b.c.d')) 218 True 219 """ 220 len_self = len(self._identifiers) 221 len_name = len(name._identifiers) 222 223 if (len_self > len_name) or (strict and len_self == len_name): 224 return False 225 # The following is redundant (the first clause is implied by 226 # the second), but is done as an optimization. 227 return ((self._identifiers[0] == name._identifiers[0]) and 228 self._identifiers == name._identifiers[:len_self])
229
230 - def contextualize(self, context):
231 """ 232 If C{self} and C{context} share a common ancestor, then return 233 a name for C{self}, relative to that ancestor. If they do not 234 share a common ancestor (or if C{context} is C{UNKNOWN}), then 235 simply return C{self}. 236 237 This is used to generate shorter versions of dotted names in 238 cases where users can infer the intended target from the 239 context. 240 241 @type context: L{DottedName} 242 @rtype: L{DottedName} 243 """ 244 if context is UNKNOWN or not context or len(self) <= 1: 245 return self 246 if self[0] == context[0]: 247 return self[1:].contextualize(context[1:]) 248 else: 249 return self 250 251 # Find the first index where self & context differ. 252 for i in range(min(len(context), len(self))): 253 if self._identifiers[i] != context._identifiers[i]: 254 first_difference = i 255 break 256 else: 257 first_difference = i+1 258 259 # Strip off anything before that index. 260 if first_difference == 0: 261 return self 262 elif first_difference == len(self): 263 return self[-1:] 264 else: 265 return self[first_difference:]
266 267 ###################################################################### 268 # UNKNOWN Value 269 ###################################################################### 270
271 -class _Sentinel:
272 """ 273 A unique value that won't compare equal to any other value. This 274 class is used to create L{UNKNOWN}. 275 """
276 - def __init__(self, name):
277 self.name = name
278 - def __repr__(self):
279 return '<%s>' % self.name
280 - def __nonzero__(self):
281 raise ValueError('Sentinel value <%s> can not be used as a boolean' % 282 self.name)
283 284 UNKNOWN = _Sentinel('UNKNOWN') 285 """A special value used to indicate that a given piece of 286 information about an object is unknown. This is used as the 287 default value for all instance variables.""" 288 289 ###################################################################### 290 # API Documentation Objects: Abstract Base Classes 291 ###################################################################### 292
293 -class APIDoc(object):
294 """ 295 API documentation information for a single element of a Python 296 program. C{APIDoc} itself is an abstract base class; subclasses 297 are used to specify what information should be recorded about each 298 type of program element. In particular, C{APIDoc} has two direct 299 subclasses, C{VariableDoc} for documenting variables and 300 C{ValueDoc} for documenting values; and the C{ValueDoc} class is 301 subclassed further for different value types. 302 303 Each C{APIDoc} subclass specifies the set of attributes that 304 should be used to record information about the corresponding 305 program element type. The default value for each attribute is 306 stored in the class; these default values can then be overridden 307 with instance variables. Most attributes use the special value 308 L{UNKNOWN} as their default value, to indicate that the correct 309 value for that attribute has not yet been determined. This makes 310 it easier to merge two C{APIDoc} objects that are documenting the 311 same element (in particular, to merge information about an element 312 that was derived from parsing with information that was derived 313 from introspection). 314 315 For all attributes with boolean values, use only the constants 316 C{True} and C{False} to designate true and false. In particular, 317 do I{not} use other values that evaluate as true or false, such as 318 C{2} or C{()}. This restriction makes it easier to handle 319 C{UNKNOWN} values. For example, to test if a boolean attribute is 320 C{True} or C{UNKNOWN}, use 'C{attrib in (True, UNKNOWN)}' or 321 'C{attrib is not False}'. 322 323 Two C{APIDoc} objects describing the same object can be X{merged}, 324 using the method L{merge_and_overwrite(other)}. After two 325 C{APIDoc}s are merged, any changes to one will be reflected in the 326 other. This is accomplished by setting the two C{APIDoc} objects 327 to use a shared instance dictionary. See the documentation for 328 L{merge_and_overwrite} for more information, and some important 329 caveats about hashing. 330 """ 331 #{ Docstrings 332 docstring = UNKNOWN 333 """@ivar: The documented item's docstring. 334 @type: C{string} or C{None}""" 335 336 docstring_lineno = UNKNOWN 337 """@ivar: The line number on which the documented item's docstring 338 begins. 339 @type: C{int}""" 340 #} end of "docstrings" group 341 342 #{ Information Extracted from Docstrings 343 descr = UNKNOWN 344 """@ivar: A description of the documented item, extracted from its 345 docstring. 346 @type: L{ParsedDocstring<epydoc.markup.ParsedDocstring>}""" 347 348 summary = UNKNOWN 349 """@ivar: A summary description of the documented item, extracted from 350 its docstring. 351 @type: L{ParsedDocstring<epydoc.markup.ParsedDocstring>}""" 352 353 other_docs = UNKNOWN 354 """@ivar: A flag indicating if the entire L{docstring} body (except tags 355 if any) is entirely included in the L{summary}. 356 @type: C{bool}""" 357 358 metadata = UNKNOWN 359 """@ivar: Metadata about the documented item, extracted from fields in 360 its docstring. I{Currently} this is encoded as a list of tuples 361 C{(field, arg, descr)}. But that may change. 362 @type: C{(str, str, L{ParsedDocstring<markup.ParsedDocstring>})}""" 363 364 extra_docstring_fields = UNKNOWN 365 """@ivar: A list of new docstring fields tags that are defined by the 366 documented item's docstring. These new field tags can be used by 367 this item or by any item it contains. 368 @type: L{DocstringField <epydoc.docstringparser.DocstringField>}""" 369 #} end of "information extracted from docstrings" group 370 371 #{ Source Information 372 docs_extracted_by = UNKNOWN # 'parser' or 'introspecter' or 'both' 373 """@ivar: Information about where the information contained by this 374 C{APIDoc} came from. Can be one of C{'parser'}, 375 C{'introspector'}, or C{'both'}. 376 @type: C{str}""" 377 #} end of "source information" group 378
379 - def __init__(self, **kwargs):
380 """ 381 Construct a new C{APIDoc} object. Keyword arguments may be 382 used to initialize the new C{APIDoc}'s attributes. 383 384 @raise TypeError: If a keyword argument is specified that does 385 not correspond to a valid attribute for this (sub)class of 386 C{APIDoc}. 387 """ 388 if epydoc.DEBUG: 389 for key in kwargs: 390 if key[0] != '_' and not hasattr(self.__class__, key): 391 raise TypeError('%s got unexpected arg %r' % 392 (self.__class__.__name__, key)) 393 self.__dict__.update(kwargs)
394
395 - def _debug_setattr(self, attr, val):
396 """ 397 Modify an C{APIDoc}'s attribute. This is used when 398 L{epydoc.DEBUG} is true, to make sure we don't accidentally 399 set any inappropriate attributes on C{APIDoc} objects. 400 401 @raise AttributeError: If C{attr} is not a valid attribute for 402 this (sub)class of C{APIDoc}. (C{attr} is considered a 403 valid attribute iff C{self.__class__} defines an attribute 404 with that name.) 405 """ 406 # Don't intercept special assignments like __class__, or 407 # assignments to private variables. 408 if attr.startswith('_'): 409 return object.__setattr__(self, attr, val) 410 if not hasattr(self, attr): 411 raise AttributeError('%s does not define attribute %r' % 412 (self.__class__.__name__, attr)) 413 self.__dict__[attr] = val
414 415 if epydoc.DEBUG: 416 __setattr__ = _debug_setattr 417
418 - def __repr__(self):
419 return '<%s>' % self.__class__.__name__
420
421 - def pp(self, doublespace=0, depth=5, exclude=(), include=()):
422 """ 423 Return a pretty-printed string representation for the 424 information contained in this C{APIDoc}. 425 """ 426 return pp_apidoc(self, doublespace, depth, exclude, include)
427 __str__ = pp 428
429 - def specialize_to(self, cls):
430 """ 431 Change C{self}'s class to C{cls}. C{cls} must be a subclass 432 of C{self}'s current class. For example, if a generic 433 C{ValueDoc} was created for a value, and it is determined that 434 the value is a routine, you can update its class with: 435 436 >>> valdoc.specialize_to(RoutineDoc) 437 """ 438 if not issubclass(cls, self.__class__): 439 raise ValueError('Can not specialize to %r' % cls) 440 # Update the class. 441 self.__class__ = cls 442 # Update the class of any other apidoc's in the mergeset. 443 if self.__mergeset is not None: 444 for apidoc in self.__mergeset: 445 apidoc.__class__ = cls 446 # Re-initialize self, in case the subclass constructor does 447 # any special processing on its arguments. 448 self.__init__(**self.__dict__)
449 450 __has_been_hashed = False 451 """True iff L{self.__hash__()} has ever been called.""" 452
453 - def __hash__(self):
454 self.__has_been_hashed = True 455 return id(self.__dict__)
456
457 - def __cmp__(self, other):
458 if not isinstance(other, APIDoc): return -1 459 if self.__dict__ is other.__dict__: return 0 460 name_cmp = cmp(self.canonical_name, other.canonical_name) 461 if name_cmp == 0: return -1 462 else: return name_cmp
463
464 - def is_detailed(self):
465 """ 466 Does this object deserve a box with extra details? 467 468 @return: True if the object needs extra details, else False. 469 @rtype: C{bool} 470 """ 471 if self.other_docs is True: 472 return True 473 474 if self.metadata is not UNKNOWN: 475 return bool(self.metadata)
476 477 __mergeset = None 478 """The set of all C{APIDoc} objects that have been merged with 479 this C{APIDoc} (using L{merge_and_overwrite()}). Each C{APIDoc} 480 in this set shares a common instance dictionary (C{__dict__}).""" 481
482 - def merge_and_overwrite(self, other, ignore_hash_conflict=False):
483 """ 484 Combine C{self} and C{other} into a X{merged object}, such 485 that any changes made to one will affect the other. Any 486 attributes that C{other} had before merging will be discarded. 487 This is accomplished by copying C{self.__dict__} over 488 C{other.__dict__} and C{self.__class__} over C{other.__class__}. 489 490 Care must be taken with this method, since it modifies the 491 hash value of C{other}. To help avoid the problems that this 492 can cause, C{merge_and_overwrite} will raise an exception if 493 C{other} has ever been hashed, unless C{ignore_hash_conflict} 494 is True. Note that adding C{other} to a dictionary, set, or 495 similar data structure will implicitly cause it to be hashed. 496 If you do set C{ignore_hash_conflict} to True, then any 497 existing data structures that rely on C{other}'s hash staying 498 constant may become corrupted. 499 500 @return: C{self} 501 @raise ValueError: If C{other} has ever been hashed. 502 """ 503 # If we're already merged, then there's nothing to do. 504 if (self.__dict__ is other.__dict__ and 505 self.__class__ is other.__class__): return self 506 507 if other.__has_been_hashed and not ignore_hash_conflict: 508 raise ValueError("%r has already been hashed! Merging it " 509 "would cause its hash value to change." % other) 510 511 # If other was itself already merged with anything, 512 # then we need to merge those too. 513 a,b = (self.__mergeset, other.__mergeset) 514 mergeset = (self.__mergeset or [self]) + (other.__mergeset or [other]) 515 other.__dict__.clear() 516 for apidoc in mergeset: 517 #if apidoc is self: pass 518 apidoc.__class__ = self.__class__ 519 apidoc.__dict__ = self.__dict__ 520 self.__mergeset = mergeset 521 # Sanity chacks. 522 assert self in mergeset and other in mergeset 523 for apidoc in mergeset: 524 assert apidoc.__dict__ is self.__dict__ 525 # Return self. 526 return self
527
551
552 -def reachable_valdocs(root, **filters):
553 """ 554 Return a list of all C{ValueDoc}s that can be reached, directly or 555 indirectly from the given root list of C{ValueDoc}s. 556 557 @param filters: A set of filters that can be used to prevent 558 C{reachable_valdocs} from following specific link types when 559 looking for C{ValueDoc}s that can be reached from the root 560 set. See C{APIDoc.apidoc_links} for a more complete 561 description. 562 """ 563 apidoc_queue = list(root) 564 val_set = set() 565 var_set = set() 566 while apidoc_queue: 567 api_doc = apidoc_queue.pop() 568 if isinstance(api_doc, ValueDoc): 569 val_set.add(api_doc) 570 else: 571 var_set.add(api_doc) 572 apidoc_queue.extend([v for v in api_doc.apidoc_links(**filters) 573 if v not in val_set and v not in var_set]) 574 return val_set
575 576 ###################################################################### 577 # Variable Documentation Objects 578 ###################################################################### 579
580 -class VariableDoc(APIDoc):
581 """ 582 API documentation information about a single Python variable. 583 584 @note: The only time a C{VariableDoc} will have its own docstring 585 is if that variable was created using an assignment statement, and 586 that assignment statement had a docstring-comment or was followed 587 by a pseudo-docstring. 588 """ 589 #{ Basic Variable Information 590 name = UNKNOWN 591 """@ivar: The name of this variable in its containing namespace. 592 @type: C{str}""" 593 594 container = UNKNOWN 595 """@ivar: API documentation for the namespace that contains this 596 variable. 597 @type: L{ValueDoc}""" 598 599 canonical_name = UNKNOWN 600 """@ivar: A dotted name that serves as a unique identifier for 601 this C{VariableDoc}. It should be formed by concatenating 602 the C{VariableDoc}'s C{container} with its C{name}. 603 @type: L{DottedName}""" 604 605 value = UNKNOWN 606 """@ivar: The API documentation for this variable's value. 607 @type: L{ValueDoc}""" 608 #} 609 610 #{ Information Extracted from Docstrings 611 type_descr = UNKNOWN 612 """@ivar: A description of the variable's expected type, extracted from 613 its docstring. 614 @type: L{ParsedDocstring<epydoc.markup.ParsedDocstring>}""" 615 #} end of "information extracted from docstrings" group 616 617 #{ Information about Imported Variables 618 imported_from = UNKNOWN 619 """@ivar: The fully qualified dotted name of the variable that this 620 variable's value was imported from. This attribute should only 621 be defined if C{is_instvar} is true. 622 @type: L{DottedName}""" 623 624 is_imported = UNKNOWN 625 """@ivar: Was this variable's value imported from another module? 626 (Exception: variables that are explicitly included in __all__ have 627 C{is_imported} set to C{False}, even if they are in fact 628 imported.) 629 @type: C{bool}""" 630 #} end of "information about imported variables" group 631 632 #{ Information about Variables in Classes 633 is_instvar = UNKNOWN 634 """@ivar: If true, then this variable is an instance variable; if false, 635 then this variable is a class variable. This attribute should 636 only be defined if the containing namespace is a class 637 @type: C{bool}""" 638 639 overrides = UNKNOWN # [XXX] rename -- don't use a verb. 640 """@ivar: The API documentation for the variable that is overridden by 641 this variable. This attribute should only be defined if the 642 containing namespace is a class. 643 @type: L{VariableDoc}""" 644 #} end of "information about variables in classes" group 645 646 #{ Flags 647 is_alias = UNKNOWN 648 """@ivar: Is this variable an alias for another variable with the same 649 value? If so, then this variable will be dispreferred when 650 assigning canonical names. 651 @type: C{bool}""" 652 653 is_public = UNKNOWN 654 """@ivar: Is this variable part of its container's public API? 655 @type: C{bool}""" 656 #} end of "flags" group 657
658 - def __init__(self, **kwargs):
659 APIDoc.__init__(self, **kwargs) 660 if self.is_public is UNKNOWN and self.name is not UNKNOWN: 661 self.is_public = (not self.name.startswith('_') or 662 self.name.endswith('_'))
663
664 - def __repr__(self):
665 if self.canonical_name is not UNKNOWN: 666 return '<%s %s>' % (self.__class__.__name__, self.canonical_name) 667 if self.name is not UNKNOWN: 668 return '<%s %s>' % (self.__class__.__name__, self.name) 669 else: 670 return '<%s>' % self.__class__.__name__
671
672 - def _get_defining_module(self):
673 if self.container is UNKNOWN: 674 return UNKNOWN 675 return self.container.defining_module
676 defining_module = property(_get_defining_module, doc=""" 677 A read-only property that can be used to get the variable's 678 defining module. This is defined as the defining module 679 of the variable's container.""") 680 692
693 - def is_detailed(self):
694 pval = super(VariableDoc, self).is_detailed() 695 if pval or self.value in (None, UNKNOWN): 696 return pval 697 698 if (self.overrides not in (None, UNKNOWN) and 699 isinstance(self.value, RoutineDoc)): 700 return True 701 702 if isinstance(self.value, GenericValueDoc): 703 # [XX] This is a little hackish -- we assume that the 704 # summary lines will have SUMMARY_REPR_LINELEN chars, 705 # that len(name) of those will be taken up by the name, 706 # and that 3 of those will be taken up by " = " between 707 # the name & val. Note that if any docwriter uses a 708 # different formula for maxlen for this, then it will 709 # not get the right value for is_detailed(). 710 maxlen = self.value.SUMMARY_REPR_LINELEN-3-len(self.name) 711 return (not self.value.summary_pyval_repr(maxlen).is_complete) 712 else: 713 return self.value.is_detailed()
714 715 ###################################################################### 716 # Value Documentation Objects 717 ###################################################################### 718
719 -class ValueDoc(APIDoc):
720 """ 721 API documentation information about a single Python value. 722 """ 723 canonical_name = UNKNOWN 724 """@ivar: A dotted name that serves as a unique identifier for 725 this C{ValueDoc}'s value. If the value can be reached using a 726 single sequence of identifiers (given the appropriate imports), 727 then that sequence of identifiers is used as its canonical name. 728 If the value can be reached by multiple sequences of identifiers 729 (i.e., if it has multiple aliases), then one of those sequences of 730 identifiers is used. If the value cannot be reached by any 731 sequence of identifiers (e.g., if it was used as a base class but 732 then its variable was deleted), then its canonical name will start 733 with C{'??'}. If necessary, a dash followed by a number will be 734 appended to the end of a non-reachable identifier to make its 735 canonical name unique. 736 737 When possible, canonical names are chosen when new C{ValueDoc}s 738 are created. However, this is sometimes not possible. If a 739 canonical name can not be chosen when the C{ValueDoc} is created, 740 then one will be assigned by L{assign_canonical_names() 741 <docbuilder.assign_canonical_names>}. 742 743 @type: L{DottedName}""" 744 745 #{ Value Representation 746 pyval = UNKNOWN 747 """@ivar: A pointer to the actual Python object described by this 748 C{ValueDoc}. This is used to display the value (e.g., when 749 describing a variable.) Use L{pyval_repr()} to generate a 750 plaintext string representation of this value. 751 @type: Python object""" 752 753 parse_repr = UNKNOWN 754 """@ivar: A text representation of this value, extracted from 755 parsing its source code. This representation may not accurately 756 reflect the actual value (e.g., if the value was modified after 757 the initial assignment). 758 @type: C{unicode}""" 759 760 REPR_MAXLINES = 5 761 """@cvar: The maximum number of lines of text that should be 762 generated by L{pyval_repr()}. If the string representation does 763 not fit in this number of lines, an ellpsis marker (...) will 764 be placed at the end of the formatted representation.""" 765 766 REPR_LINELEN = 75 767 """@cvar: The maximum number of characters for lines of text that 768 should be generated by L{pyval_repr()}. Any lines that exceed 769 this number of characters will be line-wrappped; The S{crarr} 770 symbol will be used to indicate that the line was wrapped.""" 771 772 SUMMARY_REPR_LINELEN = 75 773 """@cvar: The maximum number of characters for the single-line 774 text representation generated by L{summary_pyval_repr()}. If 775 the value's representation does not fit in this number of 776 characters, an ellipsis marker (...) will be placed at the end 777 of the formatted representation.""" 778 779 REPR_MIN_SCORE = 0 780 """@cvar: The minimum score that a value representation based on 781 L{pyval} should have in order to be used instead of L{parse_repr} 782 as the canonical representation for this C{ValueDoc}'s value. 783 @see: L{epydoc.markup.pyval_repr}""" 784 #} end of "value representation" group 785 786 #{ Context 787 defining_module = UNKNOWN 788 """@ivar: The documentation for the module that defines this 789 value. This is used, e.g., to lookup the appropriate markup 790 language for docstrings. For a C{ModuleDoc}, 791 C{defining_module} should be C{self}. 792 @type: L{ModuleDoc}""" 793 #} end of "context group" 794 795 #{ Information about Imported Variables 796 proxy_for = None # [xx] in progress. 797 """@ivar: If C{proxy_for} is not None, then this value was 798 imported from another file. C{proxy_for} is the dotted name of 799 the variable that this value was imported from. If that 800 variable is documented, then its C{value} may contain more 801 complete API documentation about this value. The C{proxy_for} 802 attribute is used by the source code parser to link imported 803 values to their source values (in particular, for base 804 classes). When possible, these proxy C{ValueDoc}s are replaced 805 by the imported value's C{ValueDoc} by 806 L{link_imports()<docbuilder.link_imports>}. 807 @type: L{DottedName}""" 808 #} end of "information about imported variables" group 809 810 #: @ivar: 811 #: This is currently used to extract values from __all__, etc, in 812 #: the docparser module; maybe I should specialize 813 #: process_assignment and extract it there? Although, for __all__, 814 #: it's not clear where I'd put the value, since I just use it to 815 #: set private/public/imported attribs on other vars (that might not 816 #: exist yet at the time.) 817 toktree = UNKNOWN 818
819 - def __repr__(self):
820 if self.canonical_name is not UNKNOWN: 821 return '<%s %s>' % (self.__class__.__name__, self.canonical_name) 822 else: 823 return '<%s %s>' % (self.__class__.__name__, 824 self.summary_pyval_repr().to_plaintext(None))
825
826 - def __setstate__(self, state):
827 self.__dict__ = state
828
829 - def __getstate__(self):
830 """ 831 State serializer for the pickle module. This is necessary 832 because sometimes the C{pyval} attribute contains an 833 un-pickleable value. 834 """ 835 # Construct our pickled dictionary. Maintain this dictionary 836 # as a private attribute, so we can reuse it later, since 837 # merged objects need to share a single dictionary. 838 if not hasattr(self, '_ValueDoc__pickle_state'): 839 # Make sure __pyval_repr & __summary_pyval_repr are cached: 840 self.pyval_repr(), self.summary_pyval_repr() 841 # Construct the dictionary; leave out 'pyval'. 842 self.__pickle_state = self.__dict__.copy() 843 self.__pickle_state['pyval'] = UNKNOWN 844 845 if not isinstance(self, GenericValueDoc): 846 assert self.__pickle_state != {} 847 # Return the pickle state. 848 return self.__pickle_state
849 850 #{ Value Representation
851 - def pyval_repr(self):
852 """ 853 Return a formatted representation of the Python object 854 described by this C{ValueDoc}. This representation may 855 include data from introspection or parsing, and is authorative 856 as 'the best way to represent a Python value.' Any lines that 857 go beyond L{REPR_LINELEN} characters will be wrapped; and if 858 the representation as a whole takes more than L{REPR_MAXLINES} 859 lines, then it will be truncated (with an ellipsis marker). 860 This function will never return L{UNKNOWN} or C{None}. 861 862 @rtype: L{ColorizedPyvalRepr} 863 """ 864 # Use self.__pyval_repr to cache the result. 865 if not hasattr(self, '_ValueDoc__pyval_repr'): 866 self.__pyval_repr = epydoc.markup.pyval_repr.colorize_pyval( 867 self.pyval, self.parse_repr, self.REPR_MIN_SCORE, 868 self.REPR_LINELEN, self.REPR_MAXLINES, linebreakok=True) 869 return self.__pyval_repr
870
871 - def summary_pyval_repr(self, max_len=None):
872 """ 873 Return a single-line formatted representation of the Python 874 object described by this C{ValueDoc}. This representation may 875 include data from introspection or parsing, and is authorative 876 as 'the best way to summarize a Python value.' If the 877 representation takes more then L{SUMMARY_REPR_LINELEN} 878 characters, then it will be truncated (with an ellipsis 879 marker). This function will never return L{UNKNOWN} or 880 C{None}. 881 882 @rtype: L{ColorizedPyvalRepr} 883 """ 884 # If max_len is specified, then do *not* cache the result. 885 if max_len is not None: 886 return epydoc.markup.pyval_repr.colorize_pyval( 887 self.pyval, self.parse_repr, self.REPR_MIN_SCORE, 888 max_len, maxlines=1, linebreakok=False) 889 890 # Use self.__summary_pyval_repr to cache the result. 891 if not hasattr(self, '_ValueDoc__summary_pyval_repr'): 892 self.__summary_pyval_repr = epydoc.markup.pyval_repr.colorize_pyval( 893 self.pyval, self.parse_repr, self.REPR_MIN_SCORE, 894 self.SUMMARY_REPR_LINELEN, maxlines=1, linebreakok=False) 895 return self.__summary_pyval_repr
896 #} end of "value representation" group 897
900
901 -class GenericValueDoc(ValueDoc):
902 """ 903 API documentation about a 'generic' value, i.e., one that does not 904 have its own docstring or any information other than its value and 905 parse representation. C{GenericValueDoc}s do not get assigned 906 cannonical names. 907 """ 908 canonical_name = None 909
910 - def is_detailed(self):
911 return (not self.summary_pyval_repr().is_complete)
912
913 -class NamespaceDoc(ValueDoc):
914 """ 915 API documentation information about a singe Python namespace 916 value. (I.e., a module or a class). 917 """ 918 #{ Information about Variables 919 variables = UNKNOWN 920 """@ivar: The contents of the namespace, encoded as a 921 dictionary mapping from identifiers to C{VariableDoc}s. This 922 dictionary contains all names defined by the namespace, 923 including imported variables, aliased variables, and variables 924 inherited from base classes (once L{inherit_docs() 925 <epydoc.docbuilder.inherit_docs>} has added them). 926 @type: C{dict} from C{string} to L{VariableDoc}""" 927 sorted_variables = UNKNOWN 928 """@ivar: A list of all variables defined by this 929 namespace, in sorted order. The elements of this list should 930 exactly match the values of L{variables}. The sort order for 931 this list is defined as follows: 932 - Any variables listed in a C{@sort} docstring field are 933 listed in the order given by that field. 934 - These are followed by any variables that were found while 935 parsing the source code, in the order in which they were 936 defined in the source file. 937 - Finally, any remaining variables are listed in 938 alphabetical order. 939 @type: C{list} of L{VariableDoc}""" 940 sort_spec = UNKNOWN 941 """@ivar: The order in which variables should be listed, 942 encoded as a list of names. Any variables whose names are not 943 included in this list should be listed alphabetically, 944 following the variables that are included. 945 @type: C{list} of C{str}""" 946 group_specs = UNKNOWN 947 """@ivar: The groups that are defined by this namespace's 948 docstrings. C{group_specs} is encoded as an ordered list of 949 tuples C{(group_name, elt_names)}, where C{group_name} is the 950 951 name of a group and C{elt_names} is a list of element names in 952 that group. (An element can be a variable or a submodule.) A 953 '*' in an element name will match any string of characters. 954 @type: C{list} of C{(str,list)}""" 955 variable_groups = UNKNOWN 956 """@ivar: A dictionary specifying what group each 957 variable belongs to. The keys of the dictionary are group 958 names, and the values are lists of C{VariableDoc}s. The order 959 that groups should be listed in should be taken from 960 L{group_specs}. 961 @type: C{dict} from C{str} to C{list} of L{VariableDoc}""" 962 #} end of group "information about variables" 963
964 - def __init__(self, **kwargs):
965 kwargs.setdefault('variables', {}) 966 APIDoc.__init__(self, **kwargs) 967 assert self.variables is not UNKNOWN
968
969 - def is_detailed(self):
970 return True
971 990
991 - def init_sorted_variables(self):
992 """ 993 Initialize the L{sorted_variables} attribute, based on the 994 L{variables} and L{sort_spec} attributes. This should usually 995 be called after all variables have been added to C{variables} 996 (including any inherited variables for classes). 997 """ 998 unsorted = self.variables.copy() 999 self.sorted_variables = [] 1000 1001 # Add any variables that are listed in sort_spec 1002 if self.sort_spec is not UNKNOWN: 1003 unused_idents = set(self.sort_spec) 1004 for ident in self.sort_spec: 1005 if ident in unsorted: 1006 self.sorted_variables.append(unsorted.pop(ident)) 1007 unused_idents.discard(ident) 1008 elif '*' in ident: 1009 regexp = re.compile('^%s$' % ident.replace('*', '(.*)')) 1010 # sort within matching group? 1011 for name, var_doc in unsorted.items(): 1012 if regexp.match(name): 1013 self.sorted_variables.append(unsorted.pop(name)) 1014 unused_idents.discard(ident) 1015 for ident in unused_idents: 1016 if ident not in ['__all__', '__docformat__', '__path__']: 1017 log.warning("@sort: %s.%s not found" % 1018 (self.canonical_name, ident)) 1019 1020 1021 # Add any remaining variables in alphabetical order. 1022 var_docs = unsorted.items() 1023 var_docs.sort() 1024 for name, var_doc in var_docs: 1025 self.sorted_variables.append(var_doc)
1026
1027 - def init_variable_groups(self):
1028 """ 1029 Initialize the L{variable_groups} attribute, based on the 1030 L{sorted_variables} and L{group_specs} attributes. 1031 """ 1032 if self.sorted_variables is UNKNOWN: 1033 self.init_sorted_variables() 1034 assert len(self.sorted_variables) == len(self.variables) 1035 1036 elts = [(v.name, v) for v in self.sorted_variables] 1037 self._unused_groups = dict([(n,set(i)) for (n,i) in self.group_specs]) 1038 self.variable_groups = self._init_grouping(elts)
1039
1040 - def group_names(self):
1041 """ 1042 Return a list of the group names defined by this namespace, in 1043 the order in which they should be listed, with no duplicates. 1044 """ 1045 name_list = [''] 1046 name_set = set() 1047 for name, spec in self.group_specs: 1048 if name not in name_set: 1049 name_set.add(name) 1050 name_list.append(name) 1051 return name_list
1052
1053 - def _init_grouping(self, elts):
1054 """ 1055 Divide a given a list of APIDoc objects into groups, as 1056 specified by L{self.group_specs}. 1057 1058 @param elts: A list of tuples C{(name, apidoc)}. 1059 1060 @return: A list of tuples C{(groupname, elts)}, where 1061 C{groupname} is the name of a group and C{elts} is a list of 1062 C{APIDoc}s in that group. The first tuple has name C{''}, and 1063 is used for ungrouped elements. The remaining tuples are 1064 listed in the order that they appear in C{self.group_specs}. 1065 Within each tuple, the elements are listed in the order that 1066 they appear in C{api_docs}. 1067 """ 1068 # Make the common case fast. 1069 if len(self.group_specs) == 0: 1070 return {'': [elt[1] for elt in elts]} 1071 1072 ungrouped = set([elt_doc for (elt_name, elt_doc) in elts]) 1073 1074 ungrouped = dict(elts) 1075 groups = {} 1076 for elt_name, elt_doc in elts: 1077 for (group_name, idents) in self.group_specs: 1078 group = groups.setdefault(group_name, []) 1079 unused_groups = self._unused_groups[group_name] 1080 for ident in idents: 1081 if re.match('^%s$' % ident.replace('*', '(.*)'), elt_name): 1082 unused_groups.discard(ident) 1083 if elt_name in ungrouped: 1084 group.append(ungrouped.pop(elt_name)) 1085 elif elt_name not in set(idents): 1086 log.warning("%s.%s in multiple groups" % 1087 (self.canonical_name, elt_name)) 1088 1089 # Convert ungrouped from an unordered set to an ordered list. 1090 groups[''] = [elt_doc for (elt_name, elt_doc) in elts 1091 if elt_name in ungrouped] 1092 return groups
1093
1094 - def report_unused_groups(self):
1095 """ 1096 Issue a warning for any @group items that were not used by 1097 L{_init_grouping()}. 1098 """ 1099 for (group, unused_idents) in self._unused_groups.items(): 1100 for ident in unused_idents: 1101 log.warning("@group %s: %s.%s not found" % 1102 (group, self.canonical_name, ident))
1103
1104 -class ModuleDoc(NamespaceDoc):
1105 """ 1106 API documentation information about a single module. 1107 """ 1108 #{ Information about the Module 1109 filename = UNKNOWN 1110 """@ivar: The name of the file that defines the module. 1111 @type: C{string}""" 1112 docformat = UNKNOWN 1113 """@ivar: The markup language used by docstrings in this module. 1114 @type: C{string}""" 1115 #{ Information about Submodules 1116 submodules = UNKNOWN 1117 """@ivar: Modules contained by this module (if this module 1118 is a package). (Note: on rare occasions, a module may have a 1119 submodule that is shadowed by a variable with the same name.) 1120 @type: C{list} of L{ModuleDoc}""" 1121 submodule_groups = UNKNOWN 1122 """@ivar: A dictionary specifying what group each 1123 submodule belongs to. The keys of the dictionary are group 1124 names, and the values are lists of C{ModuleDoc}s. The order 1125 that groups should be listed in should be taken from 1126 L{group_specs}. 1127 @type: C{dict} from C{str} to C{list} of L{ModuleDoc}""" 1128 #{ Information about Packages 1129 package = UNKNOWN 1130 """@ivar: API documentation for the module's containing package. 1131 @type: L{ModuleDoc}""" 1132 is_package = UNKNOWN 1133 """@ivar: True if this C{ModuleDoc} describes a package. 1134 @type: C{bool}""" 1135 path = UNKNOWN 1136 """@ivar: If this C{ModuleDoc} describes a package, then C{path} 1137 contains a list of directories that constitute its path (i.e., 1138 the value of its C{__path__} variable). 1139 @type: C{list} of C{str}""" 1140 #{ Information about Imported Variables 1141 imports = UNKNOWN 1142 """@ivar: A list of the source names of variables imported into 1143 this module. This is used to construct import graphs. 1144 @type: C{list} of L{DottedName}""" 1145 #} 1146 1156
1157 - def init_submodule_groups(self):
1158 """ 1159 Initialize the L{submodule_groups} attribute, based on the 1160 L{submodules} and L{group_specs} attributes. 1161 """ 1162 if self.submodules in (None, UNKNOWN): 1163 return 1164 self.submodules = sorted(self.submodules, 1165 key=lambda m:m.canonical_name) 1166 elts = [(m.canonical_name[-1], m) for m in self.submodules] 1167 self.submodule_groups = self._init_grouping(elts)
1168
1169 - def select_variables(self, group=None, value_type=None, public=None, 1170 imported=None, detailed=None):
1171 """ 1172 Return a specified subset of this module's L{sorted_variables} 1173 list. If C{value_type} is given, then only return variables 1174 whose values have the specified type. If C{group} is given, 1175 then only return variables that belong to the specified group. 1176 1177 @require: The L{sorted_variables}, L{variable_groups}, and 1178 L{submodule_groups} attributes must be initialized before 1179 this method can be used. See L{init_sorted_variables()}, 1180 L{init_variable_groups()}, and L{init_submodule_groups()}. 1181 1182 @param value_type: A string specifying the value type for 1183 which variables should be returned. Valid values are: 1184 - 'class' - variables whose values are classes or types. 1185 - 'function' - variables whose values are functions. 1186 - 'other' - variables whose values are not classes, 1187 exceptions, types, or functions. 1188 @type value_type: C{string} 1189 1190 @param group: The name of the group for which variables should 1191 be returned. A complete list of the groups defined by 1192 this C{ModuleDoc} is available in the L{group_names} 1193 instance variable. The first element of this list is 1194 always the special group name C{''}, which is used for 1195 variables that do not belong to any group. 1196 @type group: C{string} 1197 1198 @param detailed: If True (False), return only the variables 1199 deserving (not deserving) a detailed informative box. 1200 If C{None}, don't care. 1201 @type detailed: C{bool} 1202 """ 1203 if (self.sorted_variables is UNKNOWN or 1204 self.variable_groups is UNKNOWN): 1205 raise ValueError('sorted_variables and variable_groups ' 1206 'must be initialized first.') 1207 1208 if group is None: var_list = self.sorted_variables 1209 else: 1210 var_list = self.variable_groups.get(group, self.sorted_variables) 1211 1212 # Public/private filter (Count UNKNOWN as public) 1213 if public is True: 1214 var_list = [v for v in var_list if v.is_public is not False] 1215 elif public is False: 1216 var_list = [v for v in var_list if v.is_public is False] 1217 1218 # Imported filter (Count UNKNOWN as non-imported) 1219 if imported is True: 1220 var_list = [v for v in var_list if v.is_imported is True] 1221 elif imported is False: 1222 var_list = [v for v in var_list if v.is_imported is not True] 1223 1224 # Detailed filter 1225 if detailed is True: 1226 var_list = [v for v in var_list if v.is_detailed() is True] 1227 elif detailed is False: 1228 var_list = [v for v in var_list if v.is_detailed() is not True] 1229 1230 # [xx] Modules are not currently included in any of these 1231 # value types. 1232 if value_type is None: 1233 return var_list 1234 elif value_type == 'class': 1235 return [var_doc for var_doc in var_list 1236 if (isinstance(var_doc.value, ClassDoc))] 1237 elif value_type == 'function': 1238 return [var_doc for var_doc in var_list 1239 if isinstance(var_doc.value, RoutineDoc)] 1240 elif value_type == 'other': 1241 return [var_doc for var_doc in var_list 1242 if not isinstance(var_doc.value, 1243 (ClassDoc, RoutineDoc, ModuleDoc))] 1244 else: 1245 raise ValueError('Bad value type %r' % value_type)
1246
1247 -class ClassDoc(NamespaceDoc):
1248 """ 1249 API documentation information about a single class. 1250 """ 1251 #{ Information about Base Classes 1252 bases = UNKNOWN 1253 """@ivar: API documentation for the class's base classes. 1254 @type: C{list} of L{ClassDoc}""" 1255 #{ Information about Subclasses 1256 subclasses = UNKNOWN 1257 """@ivar: API documentation for the class's known subclasses. 1258 @type: C{list} of L{ClassDoc}""" 1259 #} 1260 #{ Information about Metaclasses 1261 metaclass = UNKNOWN 1262 #} 1263 1273
1274 - def is_type(self):
1275 if self.canonical_name == DottedName('type'): return True 1276 if self.bases is UNKNOWN: return False 1277 for base in self.bases: 1278 if isinstance(base, ClassDoc) and base.is_type(): 1279 return True 1280 return False
1281
1282 - def is_exception(self):
1283 if self.canonical_name == DottedName('Exception'): return True 1284 if self.bases is UNKNOWN: return False 1285 for base in self.bases: 1286 if isinstance(base, ClassDoc) and base.is_exception(): 1287 return True 1288 return False
1289
1290 - def is_newstyle_class(self):
1291 if self.canonical_name == DottedName('object'): return True 1292 if self.bases is UNKNOWN: return False 1293 for base in self.bases: 1294 if isinstance(base, ClassDoc) and base.is_newstyle_class(): 1295 return True 1296 return False
1297
1298 - def mro(self, warn_about_bad_bases=False):
1299 if self.is_newstyle_class(): 1300 try: 1301 return self._c3_mro(warn_about_bad_bases) 1302 except ValueError, e: # (inconsistent hierarchy) 1303 log.error('Error finding mro for %s: %s' % 1304 (self.canonical_name, e)) 1305 # Better than nothing: 1306 return self._dfs_bases([], set(), warn_about_bad_bases) 1307 else: 1308 return self._dfs_bases([], set(), warn_about_bad_bases)
1309
1310 - def _dfs_bases(self, mro, seen, warn_about_bad_bases):
1311 if self in seen: return mro 1312 mro.append(self) 1313 seen.add(self) 1314 if self.bases is not UNKNOWN: 1315 for base in self.bases: 1316 if isinstance(base, ClassDoc) and base.proxy_for is None: 1317 base._dfs_bases(mro, seen, warn_about_bad_bases) 1318 elif warn_about_bad_bases: 1319 self._report_bad_base(base) 1320 return mro
1321
1322 - def _c3_mro(self, warn_about_bad_bases):
1323 """ 1324 Compute the class precedence list (mro) according to C3. 1325 @seealso: U{http://www.python.org/2.3/mro.html} 1326 """ 1327 bases = [base for base in self.bases if isinstance(base, ClassDoc)] 1328 if len(bases) != len(self.bases) and warn_about_bad_bases: 1329 for base in self.bases: 1330 if (not isinstance(base, ClassDoc) or 1331 base.proxy_for is not None): 1332 self._report_bad_base(base) 1333 w = [warn_about_bad_bases]*len(bases) 1334 return self._c3_merge([[self]] + map(ClassDoc._c3_mro, bases, w) + 1335 [list(bases)])
1336
1337 - def _report_bad_base(self, base):
1338 if not isinstance(base, ClassDoc): 1339 if not isinstance(base, GenericValueDoc): 1340 base_name = base.canonical_name 1341 elif base.parse_repr is not UNKNOWN: 1342 base_name = base.parse_repr 1343 else: 1344 base_name = '%r' % base 1345 log.warning("%s's base %s is not a class" % 1346 (self.canonical_name, base_name)) 1347 elif base.proxy_for is not None: 1348 log.warning("No information available for %s's base %s" % 1349 (self.canonical_name, base.proxy_for))
1350
1351 - def _c3_merge(self, seqs):
1352 """ 1353 Helper function for L{_c3_mro}. 1354 """ 1355 res = [] 1356 while 1: 1357 nonemptyseqs=[seq for seq in seqs if seq] 1358 if not nonemptyseqs: return res 1359 for seq in nonemptyseqs: # find merge candidates among seq heads 1360 cand = seq[0] 1361 nothead=[s for s in nonemptyseqs if cand in s[1:]] 1362 if nothead: cand=None #reject candidate 1363 else: break 1364 if not cand: raise ValueError("Inconsistent hierarchy") 1365 res.append(cand) 1366 for seq in nonemptyseqs: # remove cand 1367 if seq[0] == cand: del seq[0]
1368
1369 - def select_variables(self, group=None, value_type=None, inherited=None, 1370 public=None, imported=None, detailed=None):
1371 """ 1372 Return a specified subset of this class's L{sorted_variables} 1373 list. If C{value_type} is given, then only return variables 1374 whose values have the specified type. If C{group} is given, 1375 then only return variables that belong to the specified group. 1376 If C{inherited} is True, then only return inherited variables; 1377 if C{inherited} is False, then only return local variables. 1378 1379 @require: The L{sorted_variables} and L{variable_groups} 1380 attributes must be initialized before this method can be 1381 used. See L{init_sorted_variables()} and 1382 L{init_variable_groups()}. 1383 1384 @param value_type: A string specifying the value type for 1385 which variables should be returned. Valid values are: 1386 - 'instancemethod' - variables whose values are 1387 instance methods. 1388 - 'classmethod' - variables whose values are class 1389 methods. 1390 - 'staticmethod' - variables whose values are static 1391 methods. 1392 - 'properties' - variables whose values are properties. 1393 - 'class' - variables whose values are nested classes 1394 (including exceptions and types). 1395 - 'instancevariable' - instance variables. This includes 1396 any variables that are explicitly marked as instance 1397 variables with docstring fields; and variables with 1398 docstrings that are initialized in the constructor. 1399 - 'classvariable' - class variables. This includes any 1400 variables that are not included in any of the above 1401 categories. 1402 @type value_type: C{string} 1403 1404 @param group: The name of the group for which variables should 1405 be returned. A complete list of the groups defined by 1406 this C{ClassDoc} is available in the L{group_names} 1407 instance variable. The first element of this list is 1408 always the special group name C{''}, which is used for 1409 variables that do not belong to any group. 1410 @type group: C{string} 1411 1412 @param inherited: If C{None}, then return both inherited and 1413 local variables; if C{True}, then return only inherited 1414 variables; if C{False}, then return only local variables. 1415 1416 @param detailed: If True (False), return only the variables 1417 deserving (not deserving) a detailed informative box. 1418 If C{None}, don't care. 1419 @type detailed: C{bool} 1420 """ 1421 if (self.sorted_variables is UNKNOWN or 1422 self.variable_groups is UNKNOWN): 1423 raise ValueError('sorted_variables and variable_groups ' 1424 'must be initialized first.') 1425 1426 if group is None: var_list = self.sorted_variables 1427 else: var_list = self.variable_groups[group] 1428 1429 # Public/private filter (Count UNKNOWN as public) 1430 if public is True: 1431 var_list = [v for v in var_list if v.is_public is not False] 1432 elif public is False: 1433 var_list = [v for v in var_list if v.is_public is False] 1434 1435 # Inherited filter (Count UNKNOWN as non-inherited) 1436 if inherited is None: pass 1437 elif inherited: 1438 var_list = [v for v in var_list if v.container != self] 1439 else: 1440 var_list = [v for v in var_list if v.container == self ] 1441 1442 # Imported filter (Count UNKNOWN as non-imported) 1443 if imported is True: 1444 var_list = [v for v in var_list if v.is_imported is True] 1445 elif imported is False: 1446 var_list = [v for v in var_list if v.is_imported is not True] 1447 1448 # Detailed filter 1449 if detailed is True: 1450 var_list = [v for v in var_list if v.is_detailed() is True] 1451 elif detailed is False: 1452 var_list = [v for v in var_list if v.is_detailed() is not True] 1453 1454 if value_type is None: 1455 return var_list 1456 elif value_type == 'method': 1457 return [var_doc for var_doc in var_list 1458 if (isinstance(var_doc.value, RoutineDoc) and 1459 var_doc.is_instvar in (False, UNKNOWN))] 1460 elif value_type == 'instancemethod': 1461 return [var_doc for var_doc in var_list 1462 if (isinstance(var_doc.value, RoutineDoc) and 1463 not isinstance(var_doc.value, ClassMethodDoc) and 1464 not isinstance(var_doc.value, StaticMethodDoc) and 1465 var_doc.is_instvar in (False, UNKNOWN))] 1466 elif value_type == 'classmethod': 1467 return [var_doc for var_doc in var_list 1468 if (isinstance(var_doc.value, ClassMethodDoc) and 1469 var_doc.is_instvar in (False, UNKNOWN))] 1470 elif value_type == 'staticmethod': 1471 return [var_doc for var_doc in var_list 1472 if (isinstance(var_doc.value, StaticMethodDoc) and 1473 var_doc.is_instvar in (False, UNKNOWN))] 1474 elif value_type == 'property': 1475 return [var_doc for var_doc in var_list 1476 if (isinstance(var_doc.value, PropertyDoc) and 1477 var_doc.is_instvar in (False, UNKNOWN))] 1478 elif value_type == 'class': 1479 return [var_doc for var_doc in var_list 1480 if (isinstance(var_doc.value, ClassDoc) and 1481 var_doc.is_instvar in (False, UNKNOWN))] 1482 elif value_type == 'instancevariable': 1483 return [var_doc for var_doc in var_list 1484 if var_doc.is_instvar is True] 1485 elif value_type == 'classvariable': 1486 return [var_doc for var_doc in var_list 1487 if (var_doc.is_instvar in (False, UNKNOWN) and 1488 not isinstance(var_doc.value, 1489 (RoutineDoc, ClassDoc, PropertyDoc)))] 1490 else: 1491 raise ValueError('Bad value type %r' % value_type)
1492
1493 -class RoutineDoc(ValueDoc):
1494 """ 1495 API documentation information about a single routine. 1496 """ 1497 #{ Signature 1498 posargs = UNKNOWN 1499 """@ivar: The names of the routine's positional arguments. 1500 If an argument list contains \"unpacking\" arguments, then 1501 their names will be specified using nested lists. E.g., if 1502 a function's argument list is C{((x1,y1), (x2,y2))}, then 1503 posargs will be C{[['x1','y1'], ['x2','y2']]}. 1504 @type: C{list}""" 1505 posarg_defaults = UNKNOWN 1506 """@ivar: API documentation for the positional arguments' 1507 default values. This list has the same length as C{posargs}, and 1508 each element of C{posarg_defaults} describes the corresponding 1509 argument in C{posargs}. For positional arguments with no default, 1510 C{posargs_defaults} will contain None. 1511 @type: C{list} of C{ValueDoc} or C{None}""" 1512 vararg = UNKNOWN 1513 """@ivar: The name of the routine's vararg argument, or C{None} if 1514 it has no vararg argument. 1515 @type: C{string} or C{None}""" 1516 kwarg = UNKNOWN 1517 """@ivar: The name of the routine's keyword argument, or C{None} if 1518 it has no keyword argument. 1519 @type: C{string} or C{None}""" 1520 lineno = UNKNOWN # used to look up profiling info from pstats. 1521 """@ivar: The line number of the first line of the function's 1522 signature. For Python functions, this is equal to 1523 C{func.func_code.co_firstlineno}. The first line of a file 1524 is considered line 1. 1525 @type: C{int}""" 1526 #} end of "signature" group 1527 1528 #{ Decorators 1529 decorators = UNKNOWN 1530 """@ivar: A list of names of decorators that were applied to this 1531 routine, in the order that they are listed in the source code. 1532 (I.e., in the reverse of the order that they were applied in.) 1533 @type: C{list} of C{string}""" 1534 #} end of "decorators" group 1535 1536 #{ Information Extracted from Docstrings 1537 arg_descrs = UNKNOWN 1538 """@ivar: A list of descriptions of the routine's 1539 arguments. Each element of this list is a tuple C{(args, 1540 descr)}, where C{args} is a list of argument names; and 1541 C{descr} is a L{ParsedDocstring 1542 <epydoc.markup.ParsedDocstring>} describing the argument(s) 1543 specified by C{arg}. 1544 @type: C{list}""" 1545 arg_types = UNKNOWN 1546 """@ivar: Descriptions of the expected types for the 1547 routine's arguments, encoded as a dictionary mapping from 1548 argument names to type descriptions. 1549 @type: C{dict} from C{string} to L{ParsedDocstring 1550 <epydoc.markup.ParsedDocstring>}""" 1551 return_descr = UNKNOWN 1552 """@ivar: A description of the value returned by this routine. 1553 @type: L{ParsedDocstring<epydoc.markup.ParsedDocstring>}""" 1554 return_type = UNKNOWN 1555 """@ivar: A description of expected type for the value 1556 returned by this routine. 1557 @type: L{ParsedDocstring<epydoc.markup.ParsedDocstring>}""" 1558 exception_descrs = UNKNOWN 1559 """@ivar: A list of descriptions of exceptions 1560 that the routine might raise. Each element of this list is a 1561 tuple C{(exc, descr)}, where C{exc} is a string contianing the 1562 exception name; and C{descr} is a L{ParsedDocstring 1563 <epydoc.markup.ParsedDocstring>} describing the circumstances 1564 under which the exception specified by C{exc} is raised. 1565 @type: C{list}""" 1566 #} end of "information extracted from docstrings" group 1567 callgraph_uid = None 1568 """@ivar: L{DotGraph}.uid of the call graph for the function. 1569 @type: C{str}""" 1570
1571 - def is_detailed(self):
1572 if super(RoutineDoc, self).is_detailed(): 1573 return True 1574 1575 if self.arg_descrs not in (None, UNKNOWN) and self.arg_descrs: 1576 return True 1577 1578 if self.arg_types not in (None, UNKNOWN) and self.arg_types: 1579 return True 1580 1581 if self.return_descr not in (None, UNKNOWN): 1582 return True 1583 1584 if self.exception_descrs not in (None, UNKNOWN) and self.exception_descrs: 1585 return True 1586 1587 if (self.decorators not in (None, UNKNOWN) 1588 and [ d for d in self.decorators 1589 if d not in ('classmethod', 'staticmethod') ]): 1590 return True 1591 1592 return False
1593
1594 - def all_args(self):
1595 """ 1596 @return: A list of the names of all arguments (positional, 1597 vararg, and keyword), in order. If a positional argument 1598 consists of a tuple of names, then that tuple will be 1599 flattened. 1600 """ 1601 if self.posargs is UNKNOWN: 1602 return UNKNOWN 1603 1604 all_args = _flatten(self.posargs) 1605 if self.vararg not in (None, UNKNOWN): 1606 all_args.append(self.vararg) 1607 if self.kwarg not in (None, UNKNOWN): 1608 all_args.append(self.kwarg) 1609 return all_args
1610
1611 -def _flatten(lst, out=None):
1612 """ 1613 Return a flattened version of C{lst}. 1614 """ 1615 if out is None: out = [] 1616 for elt in lst: 1617 if isinstance(elt, (list,tuple)): 1618 _flatten(elt, out) 1619 else: 1620 out.append(elt) 1621 return out
1622
1623 -class ClassMethodDoc(RoutineDoc): pass
1624 -class StaticMethodDoc(RoutineDoc): pass
1625
1626 -class PropertyDoc(ValueDoc):
1627 """ 1628 API documentation information about a single property. 1629 """ 1630 #{ Property Access Functions 1631 fget = UNKNOWN 1632 """@ivar: API documentation for the property's get function. 1633 @type: L{RoutineDoc}""" 1634 fset = UNKNOWN 1635 """@ivar: API documentation for the property's set function. 1636 @type: L{RoutineDoc}""" 1637 fdel = UNKNOWN 1638 """@ivar: API documentation for the property's delete function. 1639 @type: L{RoutineDoc}""" 1640 #} 1641 #{ Information Extracted from Docstrings 1642 type_descr = UNKNOWN 1643 """@ivar: A description of the property's expected type, extracted 1644 from its docstring. 1645 @type: L{ParsedDocstring<epydoc.markup.ParsedDocstring>}""" 1646 #} end of "information extracted from docstrings" group 1647 1654
1655 - def is_detailed(self):
1656 if super(PropertyDoc, self).is_detailed(): 1657 return True 1658 1659 if self.fget not in (None, UNKNOWN) and self.fget.pyval is not None: 1660 return True 1661 if self.fset not in (None, UNKNOWN) and self.fset.pyval is not None: 1662 return True 1663 if self.fdel not in (None, UNKNOWN) and self.fdel.pyval is not None: 1664 return True 1665 1666 return False
1667 1668 ###################################################################### 1669 ## Index 1670 ###################################################################### 1671
1672 -class DocIndex:
1673 """ 1674 [xx] out of date. 1675 1676 An index that .. hmm... it *can't* be used to access some things, 1677 cuz they're not at the root level. Do I want to add them or what? 1678 And if so, then I have a sort of a new top level. hmm.. so 1679 basically the question is what to do with a name that's not in the 1680 root var's name space. 2 types: 1681 - entirely outside (eg os.path) 1682 - inside but not known (eg a submodule that we didn't look at?) 1683 - container of current thing not examined? 1684 1685 An index of all the C{APIDoc} objects that can be reached from a 1686 root set of C{ValueDoc}s. 1687 1688 The members of this index can be accessed by dotted name. In 1689 particular, C{DocIndex} defines two mappings, accessed via the 1690 L{get_vardoc()} and L{get_valdoc()} methods, which can be used to 1691 access C{VariableDoc}s or C{ValueDoc}s respectively by name. (Two 1692 separate mappings are necessary because a single name can be used 1693 to refer to both a variable and to the value contained by that 1694 variable.) 1695 1696 Additionally, the index defines two sets of C{ValueDoc}s: 1697 \"reachable C{ValueDoc}s\" and \"contained C{ValueDoc}s\". The 1698 X{reachable C{ValueDoc}s} are defined as the set of all 1699 C{ValueDoc}s that can be reached from the root set by following 1700 I{any} sequence of pointers to C{ValueDoc}s or C{VariableDoc}s. 1701 The X{contained C{ValueDoc}s} are defined as the set of all 1702 C{ValueDoc}s that can be reached from the root set by following 1703 only the C{ValueDoc} pointers defined by non-imported 1704 C{VariableDoc}s. For example, if the root set contains a module 1705 C{m}, then the contained C{ValueDoc}s includes the C{ValueDoc}s 1706 for any functions, variables, or classes defined in that module, 1707 as well as methods and variables defined in classes defined in the 1708 module. The reachable C{ValueDoc}s includes all of those 1709 C{ValueDoc}s, as well as C{ValueDoc}s for any values imported into 1710 the module, and base classes for classes defined in the module. 1711 """ 1712
1713 - def __init__(self, root):
1714 """ 1715 Create a new documentation index, based on the given root set 1716 of C{ValueDoc}s. If any C{APIDoc}s reachable from the root 1717 set does not have a canonical name, then it will be assigned 1718 one. etc. 1719 1720 @param root: A list of C{ValueDoc}s. 1721 """ 1722 for apidoc in root: 1723 if apidoc.canonical_name in (None, UNKNOWN): 1724 raise ValueError("All APIdocs passed to DocIndexer " 1725 "must already have canonical names.") 1726 1727 # Initialize the root items list. We sort them by length in 1728 # ascending order. (This ensures that variables will shadow 1729 # submodules when appropriate.) 1730 # When the elements name is the same, list in alphabetical order: 1731 # this is needed by the check for duplicates below. 1732 self.root = sorted(root, 1733 key=lambda d: (len(d.canonical_name), d.canonical_name)) 1734 """The list of C{ValueDoc}s to document. 1735 @type: C{list}""" 1736 1737 # Drop duplicated modules 1738 # [xx] maybe what causes duplicates should be fixed instead. 1739 # If fixed, adjust the sort here above: sorting by names will not 1740 # be required anymore 1741 i = 1 1742 while i < len(self.root): 1743 if self.root[i-1] is self.root[i]: 1744 del self.root[i] 1745 else: 1746 i += 1 1747 1748 self.mlclasses = self._get_module_classes(self.root) 1749 """A mapping from class names to L{ClassDoc}. Contains 1750 classes defined at module level for modules in L{root} 1751 and which can be used as fallback by L{find()} if looking 1752 in containing namespaces fails. 1753 @type: C{dict} from C{str} to L{ClassDoc} or C{list}""" 1754 1755 self.callers = None 1756 """A dictionary mapping from C{RoutineDoc}s in this index 1757 to lists of C{RoutineDoc}s for the routine's callers. 1758 This dictionary is initialized by calling 1759 L{read_profiling_info()}. 1760 @type: C{list} of L{RoutineDoc}""" 1761 1762 self.callees = None 1763 """A dictionary mapping from C{RoutineDoc}s in this index 1764 to lists of C{RoutineDoc}s for the routine's callees. 1765 This dictionary is initialized by calling 1766 L{read_profiling_info()}. 1767 @type: C{list} of L{RoutineDoc}""" 1768 1769 self._funcid_to_doc = {} 1770 """A mapping from C{profile} function ids to corresponding 1771 C{APIDoc} objects. A function id is a tuple of the form 1772 C{(filename, lineno, funcname)}. This is used to update 1773 the L{callers} and L{callees} variables.""" 1774 1775 self._container_cache = {} 1776 """A cache for the L{container()} method, to increase speed.""" 1777 1778 self._get_cache = {} 1779 """A cache for the L{get_vardoc()} and L{get_valdoc()} methods, 1780 to increase speed."""
1781 1782 #//////////////////////////////////////////////////////////// 1783 # Lookup methods 1784 #//////////////////////////////////////////////////////////// 1785 # [xx] 1786 # Currently these only work for things reachable from the 1787 # root... :-/ I might want to change this so that imported 1788 # values can be accessed even if they're not contained. 1789 # Also, I might want canonical names to not start with ?? 1790 # if the thing is a top-level imported module..? 1791
1792 - def get_vardoc(self, name):
1793 """ 1794 Return the C{VariableDoc} with the given name, or C{None} if this 1795 index does not contain a C{VariableDoc} with the given name. 1796 """ 1797 var, val = self._get(name) 1798 return var
1799
1800 - def get_valdoc(self, name):
1801 """ 1802 Return the C{ValueDoc} with the given name, or C{None} if this 1803 index does not contain a C{ValueDoc} with the given name. 1804 """ 1805 var, val = self._get(name) 1806 return val
1807
1808 - def _get(self, name):
1809 """ 1810 A helper function that's used to implement L{get_vardoc()} 1811 and L{get_valdoc()}. 1812 """ 1813 # Convert name to a DottedName, if necessary. 1814 if not isinstance(name, DottedName): 1815 name = DottedName(name) 1816 1817 # Check if the result is cached. 1818 val = self._get_cache.get(name) 1819 if val is not None: return val 1820 1821 # Look for an element in the root set whose name is a prefix 1822 # of `name`. If we can't find one, then return None. 1823 for root_valdoc in self.root: 1824 if root_valdoc.canonical_name.dominates(name): 1825 # Starting at the root valdoc, walk down the variable/ 1826 # submodule chain until we find the requested item. 1827 var_doc = None 1828 val_doc = root_valdoc 1829 for identifier in name[len(root_valdoc.canonical_name):]: 1830 if val_doc is None: break 1831 var_doc, val_doc = self._get_from(val_doc, identifier) 1832 else: 1833 # If we found it, then return. 1834 if var_doc is not None or val_doc is not None: 1835 self._get_cache[name] = (var_doc, val_doc) 1836 return var_doc, val_doc 1837 1838 # We didn't find it. 1839 self._get_cache[name] = (None, None) 1840 return None, None
1841
1842 - def _get_from(self, val_doc, identifier):
1843 if isinstance(val_doc, NamespaceDoc): 1844 child_var = val_doc.variables.get(identifier) 1845 if child_var is not None: 1846 child_val = child_var.value 1847 if child_val is UNKNOWN: child_val = None 1848 return child_var, child_val 1849 1850 # If that fails, then see if it's a submodule. 1851 if (isinstance(val_doc, ModuleDoc) and 1852 val_doc.submodules is not UNKNOWN): 1853 for submodule in val_doc.submodules: 1854 if submodule.canonical_name[-1] == identifier: 1855 var_doc = None 1856 val_doc = submodule 1857 if val_doc is UNKNOWN: val_doc = None 1858 return var_doc, val_doc 1859 1860 return None, None
1861
1862 - def find(self, name, context):
1863 """ 1864 Look for an C{APIDoc} named C{name}, relative to C{context}. 1865 Return the C{APIDoc} if one is found; otherwise, return 1866 C{None}. C{find} looks in the following places, in order: 1867 - Function parameters (if one matches, return C{None}) 1868 - All enclosing namespaces, from closest to furthest. 1869 - If C{name} starts with C{'self'}, then strip it off and 1870 look for the remaining part of the name using C{find} 1871 - Builtins 1872 - Parameter attributes 1873 - Classes at module level (if the name is not ambiguous) 1874 1875 @type name: C{str} or L{DottedName} 1876 @type context: L{APIDoc} 1877 """ 1878 if isinstance(name, basestring): 1879 name = re.sub(r'\(.*\)$', '', name.strip()) 1880 if re.match('^([a-zA-Z_]\w*)(\.[a-zA-Z_]\w*)*$', name): 1881 name = DottedName(name) 1882 else: 1883 return None 1884 elif not isinstance(name, DottedName): 1885 raise TypeError("'name' should be a string or DottedName") 1886 1887 if context is None or context.canonical_name is None: 1888 container_name = [] 1889 else: 1890 container_name = context.canonical_name 1891 1892 # Check for the name in all containing namespaces, starting 1893 # with the closest one. 1894 for i in range(len(container_name), -1, -1): 1895 relative_name = container_name[:i]+name 1896 # Is `name` the absolute name of a documented value? 1897 # (excepting GenericValueDoc values.) 1898 val_doc = self.get_valdoc(relative_name) 1899 if (val_doc is not None and 1900 not isinstance(val_doc, GenericValueDoc)): 1901 return val_doc 1902 # Is `name` the absolute name of a documented variable? 1903 var_doc = self.get_vardoc(relative_name) 1904 if var_doc is not None: return var_doc 1905 1906 # If the name begins with 'self', then try stripping that off 1907 # and see if we can find the variable. 1908 if name[0] == 'self': 1909 doc = self.find('.'.join(name[1:]), context) 1910 if doc is not None: return doc 1911 1912 # Is it the name of a builtin? 1913 if len(name)==1 and hasattr(__builtin__, name[0]): 1914 return None 1915 1916 # Is it a parameter's name or an attribute of a parameter? 1917 if isinstance(context, RoutineDoc): 1918 all_args = context.all_args() 1919 if all_args is not UNKNOWN and name[0] in all_args: 1920 return None 1921 1922 # Is this an object directly contained by any module? 1923 doc = self.mlclasses.get(name[-1]) 1924 if isinstance(doc, APIDoc): 1925 return doc 1926 elif isinstance(doc, list): 1927 log.warning("%s is an ambiguous name: it may be %s" % ( 1928 name[-1], 1929 ", ".join([ "'%s'" % d.canonical_name for d in doc ]))) 1930 1931 # Drop this item so that the warning is reported only once. 1932 # fail() will fail anyway. 1933 del self.mlclasses[name[-1]]
1934
1935 - def _get_module_classes(self, docs):
1936 """ 1937 Gather all the classes defined in a list of modules. 1938 1939 Very often people refers to classes only by class name, 1940 even if they are not imported in the namespace. Linking 1941 to such classes will fail if we look for them only in nested 1942 namespaces. Allow them to retrieve only by name. 1943 1944 @param docs: containers of the objects to collect 1945 @type docs: C{list} of C{APIDoc} 1946 @return: mapping from objects name to the object(s) with that name 1947 @rtype: C{dict} from C{str} to L{ClassDoc} or C{list} 1948 """ 1949 classes = {} 1950 for doc in docs: 1951 if not isinstance(doc, ModuleDoc): 1952 continue 1953 1954 for var in doc.variables.values(): 1955 if not isinstance(var.value, ClassDoc): 1956 continue 1957 1958 val = var.value 1959 if val in (None, UNKNOWN) or val.defining_module is not doc: 1960 continue 1961 if val.canonical_name in (None, UNKNOWN): 1962 continue 1963 1964 name = val.canonical_name[-1] 1965 vals = classes.get(name) 1966 if vals is None: 1967 classes[name] = val 1968 elif not isinstance(vals, list): 1969 classes[name] = [ vals, val ] 1970 else: 1971 vals.append(val) 1972 1973 return classes
1974 1975 #//////////////////////////////////////////////////////////// 1976 # etc 1977 #//////////////////////////////////////////////////////////// 1978
1979 - def reachable_valdocs(self, **filters):
1980 """ 1981 Return a list of all C{ValueDoc}s that can be reached, 1982 directly or indirectly from this C{DocIndex}'s root set. 1983 1984 @param filters: A set of filters that can be used to prevent 1985 C{reachable_valdocs} from following specific link types 1986 when looking for C{ValueDoc}s that can be reached from the 1987 root set. See C{APIDoc.apidoc_links} for a more complete 1988 description. 1989 """ 1990 return reachable_valdocs(self.root, **filters)
1991
1992 - def container(self, api_doc):
1993 """ 1994 Return the C{ValueDoc} that contains the given C{APIDoc}, or 1995 C{None} if its container is not in the index. 1996 """ 1997 # Check if the result is cached. 1998 val = self._container_cache.get(api_doc) 1999 if val is not None: return val 2000 2001 if isinstance(api_doc, GenericValueDoc): 2002 self._container_cache[api_doc] = None 2003 return None # [xx] unknown. 2004 if isinstance(api_doc, VariableDoc): 2005 self._container_cache[api_doc] = api_doc.container 2006 return api_doc.container 2007 if len(api_doc.canonical_name) == 1: 2008 self._container_cache[api_doc] = None 2009 return None 2010 elif isinstance(api_doc, ModuleDoc) and api_doc.package is not UNKNOWN: 2011 self._container_cache[api_doc] = api_doc.package 2012 return api_doc.package 2013 else: 2014 parent = self.get_valdoc(api_doc.canonical_name.container()) 2015 self._container_cache[api_doc] = parent 2016 return parent
2017 2018 #//////////////////////////////////////////////////////////// 2019 # Profiling information 2020 #//////////////////////////////////////////////////////////// 2021
2022 - def read_profiling_info(self, profile_stats):
2023 """ 2024 Initialize the L{callers} and L{callees} variables, given a 2025 C{Stat} object from the C{pstats} module. 2026 2027 @warning: This method uses undocumented data structures inside 2028 of C{profile_stats}. 2029 """ 2030 if self.callers is None: self.callers = {} 2031 if self.callees is None: self.callees = {} 2032 2033 # The Stat object encodes functions using `funcid`s, or 2034 # tuples of (filename, lineno, funcname). Create a mapping 2035 # from these `funcid`s to `RoutineDoc`s. 2036 self._update_funcid_to_doc(profile_stats) 2037 2038 for callee, (cc, nc, tt, ct, callers) in profile_stats.stats.items(): 2039 callee = self._funcid_to_doc.get(callee) 2040 if callee is None: continue 2041 for caller in callers: 2042 caller = self._funcid_to_doc.get(caller) 2043 if caller is None: continue 2044 self.callers.setdefault(callee, []).append(caller) 2045 self.callees.setdefault(caller, []).append(callee)
2046
2047 - def _update_funcid_to_doc(self, profile_stats):
2048 """ 2049 Update the dictionary mapping from C{pstat.Stat} funciton ids to 2050 C{RoutineDoc}s. C{pstat.Stat} function ids are tuples of 2051 C{(filename, lineno, funcname)}. 2052 """ 2053 # Maps (filename, lineno, funcname) -> RoutineDoc 2054 for val_doc in self.reachable_valdocs(): 2055 # We only care about routines. 2056 if not isinstance(val_doc, RoutineDoc): continue 2057 # Get the filename from the defining module. 2058 module = val_doc.defining_module 2059 if module is UNKNOWN or module.filename is UNKNOWN: continue 2060 # Normalize the filename. 2061 filename = os.path.abspath(module.filename) 2062 try: filename = py_src_filename(filename) 2063 except: pass 2064 # Look up the stat_func_id 2065 funcid = (filename, val_doc.lineno, val_doc.canonical_name[-1]) 2066 if funcid in profile_stats.stats: 2067 self._funcid_to_doc[funcid] = val_doc
2068 2069 ###################################################################### 2070 ## Pretty Printing 2071 ###################################################################### 2072
2073 -def pp_apidoc(api_doc, doublespace=0, depth=5, exclude=(), include=(), 2074 backpointers=None):
2075 """ 2076 @return: A multiline pretty-printed string representation for the 2077 given C{APIDoc}. 2078 @param doublespace: If true, then extra lines will be 2079 inserted to make the output more readable. 2080 @param depth: The maximum depth that pp_apidoc will descend 2081 into descendent VarDocs. To put no limit on 2082 depth, use C{depth=-1}. 2083 @param exclude: A list of names of attributes whose values should 2084 not be shown. 2085 @param backpointers: For internal use. 2086 """ 2087 pyid = id(api_doc.__dict__) 2088 if backpointers is None: backpointers = {} 2089 if (hasattr(api_doc, 'canonical_name') and 2090 api_doc.canonical_name not in (None, UNKNOWN)): 2091 name = '%s for %s' % (api_doc.__class__.__name__, 2092 api_doc.canonical_name) 2093 elif getattr(api_doc, 'name', None) not in (UNKNOWN, None): 2094 if (getattr(api_doc, 'container', None) not in (UNKNOWN, None) and 2095 getattr(api_doc.container, 'canonical_name', None) 2096 not in (UNKNOWN, None)): 2097 name ='%s for %s' % (api_doc.__class__.__name__, 2098 api_doc.container.canonical_name+ 2099 api_doc.name) 2100 else: 2101 name = '%s for %s' % (api_doc.__class__.__name__, api_doc.name) 2102 else: 2103 name = api_doc.__class__.__name__ 2104 2105 if pyid in backpointers: 2106 return '%s [%s] (defined above)' % (name, backpointers[pyid]) 2107 2108 if depth == 0: 2109 if hasattr(api_doc, 'name') and api_doc.name is not None: 2110 return '%s...' % api_doc.name 2111 else: 2112 return '...' 2113 2114 backpointers[pyid] = len(backpointers) 2115 s = '%s [%s]' % (name, backpointers[pyid]) 2116 2117 # Only print non-empty fields: 2118 fields = [field for field in api_doc.__dict__.keys() 2119 if (field in include or 2120 (getattr(api_doc, field) is not UNKNOWN 2121 and field not in exclude))] 2122 if include: 2123 fields = [field for field in dir(api_doc) 2124 if field in include] 2125 else: 2126 fields = [field for field in api_doc.__dict__.keys() 2127 if (getattr(api_doc, field) is not UNKNOWN 2128 and field not in exclude)] 2129 fields.sort() 2130 2131 for field in fields: 2132 fieldval = getattr(api_doc, field) 2133 if doublespace: s += '\n |' 2134 s += '\n +- %s' % field 2135 2136 if (isinstance(fieldval, types.ListType) and 2137 len(fieldval)>0 and 2138 isinstance(fieldval[0], APIDoc)): 2139 s += _pp_list(api_doc, fieldval, doublespace, depth, 2140 exclude, include, backpointers, 2141 (field is fields[-1])) 2142 elif (isinstance(fieldval, types.DictType) and 2143 len(fieldval)>0 and 2144 isinstance(fieldval.values()[0], APIDoc)): 2145 s += _pp_dict(api_doc, fieldval, doublespace, 2146 depth, exclude, include, backpointers, 2147 (field is fields[-1])) 2148 elif isinstance(fieldval, APIDoc): 2149 s += _pp_apidoc(api_doc, fieldval, doublespace, depth, 2150 exclude, include, backpointers, 2151 (field is fields[-1])) 2152 else: 2153 s += ' = ' + _pp_val(api_doc, fieldval, doublespace, 2154 depth, exclude, include, backpointers) 2155 2156 return s
2157
2158 -def _pp_list(api_doc, items, doublespace, depth, exclude, include, 2159 backpointers, is_last):
2160 line1 = (is_last and ' ') or '|' 2161 s = '' 2162 for item in items: 2163 line2 = ((item is items[-1]) and ' ') or '|' 2164 joiner = '\n %s %s ' % (line1, line2) 2165 if doublespace: s += '\n %s |' % line1 2166 s += '\n %s +- ' % line1 2167 valstr = _pp_val(api_doc, item, doublespace, depth, exclude, include, 2168 backpointers) 2169 s += joiner.join(valstr.split('\n')) 2170 return s
2171
2172 -def _pp_dict(api_doc, dict, doublespace, depth, exclude, include, 2173 backpointers, is_last):
2174 items = dict.items() 2175 items.sort() 2176 line1 = (is_last and ' ') or '|' 2177 s = '' 2178 for item in items: 2179 line2 = ((item is items[-1]) and ' ') or '|' 2180 joiner = '\n %s %s ' % (line1, line2) 2181 if doublespace: s += '\n %s |' % line1 2182 s += '\n %s +- ' % line1 2183 valstr = _pp_val(api_doc, item[1], doublespace, depth, exclude, 2184 include, backpointers) 2185 s += joiner.join(('%s => %s' % (item[0], valstr)).split('\n')) 2186 return s
2187
2188 -def _pp_apidoc(api_doc, val, doublespace, depth, exclude, include, 2189 backpointers, is_last):
2190 line1 = (is_last and ' ') or '|' 2191 s = '' 2192 if doublespace: s += '\n %s | ' % line1 2193 s += '\n %s +- ' % line1 2194 joiner = '\n %s ' % line1 2195 childstr = pp_apidoc(val, doublespace, depth-1, exclude, 2196 include, backpointers) 2197 return s + joiner.join(childstr.split('\n'))
2198
2199 -def _pp_val(api_doc, val, doublespace, depth, exclude, include, backpointers):
2200 from epydoc import markup 2201 if isinstance(val, APIDoc): 2202 return pp_apidoc(val, doublespace, depth-1, exclude, 2203 include, backpointers) 2204 elif isinstance(val, markup.ParsedDocstring): 2205 valrepr = `val.to_plaintext(None)` 2206 if len(valrepr) < 40: return valrepr 2207 else: return valrepr[:37]+'...' 2208 else: 2209 valrepr = repr(val) 2210 if len(valrepr) < 40: return valrepr 2211 else: return valrepr[:37]+'...'
2212