1
2
3
4
5
6
7
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 __docformat__ = 'epytext en'
34
35
36
37
38
39 import types, re, os.path
40 from epydoc import log
41 import epydoc
42 import __builtin__
43 from epydoc.compat import *
44 from epydoc.util import decode_with_backslashreplace, py_src_filename
45
46
47
48
49
51 """
52 A sequence of identifiers, separated by periods, used to name a
53 Python variable, value, or argument. The identifiers that make up
54 a dotted name can be accessed using the indexing operator:
55
56 >>> name = DottedName('epydoc', 'api_doc', 'DottedName')
57 >>> print name
58 epydoc.apidoc.DottedName
59 >>> name[1]
60 'api_doc'
61 """
62 UNREACHABLE = "??"
63 _IDENTIFIER_RE = re.compile("""(?x)
64 (%s | # UNREACHABLE marker, or..
65 (script-)? # Prefix: script (not a module)
66 [a-zA-Z_]\w* # Identifier
67 '?) # Suffix: submodule that is shadowed by a var
68 (-\d+)? # Suffix: unreachable vals with the same name
69 $"""
70 % re.escape(UNREACHABLE))
71
73 """
74 An exception raised by the DottedName constructor when one of
75 its arguments is not a valid dotted name.
76 """
77
79 """
80 Construct a new dotted name from the given sequence of pieces,
81 each of which can be either a C{string} or a C{DottedName}.
82 Each piece is divided into a sequence of identifiers, and
83 these sequences are combined together (in order) to form the
84 identifier sequence for the new C{DottedName}. If a piece
85 contains a string, then it is divided into substrings by
86 splitting on periods, and each substring is checked to see if
87 it is a valid identifier.
88 """
89 if len(pieces) == 0:
90 raise DottedName.InvalidDottedName('Empty DottedName')
91 self._identifiers = []
92 for piece in pieces:
93 if isinstance(piece, DottedName):
94 self._identifiers += piece._identifiers
95 elif isinstance(piece, basestring):
96 for subpiece in piece.split('.'):
97 if not self._IDENTIFIER_RE.match(subpiece):
98 raise DottedName.InvalidDottedName(
99 'Bad identifier %r' % (piece,))
100 self._identifiers.append(subpiece)
101 else:
102 raise DottedName.InvalidDottedName(
103 'Bad identifier %r' % (piece,))
104 self._identifiers = tuple(self._identifiers)
105
107 idents = [`ident` for ident in self._identifiers]
108 return 'DottedName(' + ', '.join(idents) + ')'
109
111 """
112 Return the dotted name as a string formed by joining its
113 identifiers with periods:
114
115 >>> print DottedName('epydoc', 'api_doc', DottedName')
116 epydoc.apidoc.DottedName
117 """
118 return '.'.join(self._identifiers)
119
121 """
122 Return a new C{DottedName} whose identifier sequence is formed
123 by adding C{other}'s identifier sequence to C{self}'s.
124 """
125 if isinstance(other, (basestring, DottedName)):
126 return DottedName(self, other)
127 else:
128 return DottedName(self, *other)
129
131 """
132 Return a new C{DottedName} whose identifier sequence is formed
133 by adding C{self}'s identifier sequence to C{other}'s.
134 """
135 if isinstance(other, (basestring, DottedName)):
136 return DottedName(other, self)
137 else:
138 return DottedName(*(list(other)+[self]))
139
141 """
142 Return the C{i}th identifier in this C{DottedName}. If C{i} is
143 a non-empty slice, then return a C{DottedName} built from the
144 identifiers selected by the slice. If C{i} is an empty slice,
145 return an empty list (since empty C{DottedName}s are not valid).
146 """
147 if isinstance(i, types.SliceType):
148 pieces = self._identifiers[i.start:i.stop]
149 if pieces: return DottedName(*pieces)
150 else: return []
151 else:
152 return self._identifiers[i]
153
155 return hash(self._identifiers)
156
158 """
159 Compare this dotted name to C{other}. Two dotted names are
160 considered equal if their identifier subsequences are equal.
161 Ordering between dotted names is lexicographic, in order of
162 identifier from left to right.
163 """
164 if not isinstance(other, DottedName):
165 return -1
166 return cmp(self._identifiers, other._identifiers)
167
169 """
170 Return the number of identifiers in this dotted name.
171 """
172 return len(self._identifiers)
173
175 """
176 Return the DottedName formed by removing the last identifier
177 from this dotted name's identifier sequence. If this dotted
178 name only has one name in its identifier sequence, return
179 C{None} instead.
180 """
181 if len(self._identifiers) == 1:
182 return None
183 else:
184 return DottedName(*self._identifiers[:-1])
185
187 """
188 Return true if this dotted name is equal to a prefix of
189 C{name}. If C{strict} is true, then also require that
190 C{self!=name}.
191
192 >>> DottedName('a.b').dominates(DottedName('a.b.c.d'))
193 True
194 """
195 if strict and len(self._identifiers)==len(name._identifiers):
196 return False
197 return self._identifiers == name._identifiers[:len(self)]
198
199 - def contextualize(self, context):
200 """
201 If C{self} and C{context} share a common ancestor, then return
202 a name for C{self}, relative to that ancestor. If they do not
203 share a common ancestor (or if C{context} is C{UNKNOWN}), then
204 simply return C{self}.
205
206 This is used to generate shorter versions of dotted names in
207 cases where users can infer the intended target from the
208 context.
209
210 @type context: L{DottedName}
211 @rtype: L{DottedName}
212 """
213 if context is UNKNOWN or not context or len(self) <= 1:
214 return self
215 if self[0] == context[0]:
216 return self[1:].contextualize(context[1:])
217 else:
218 return self
219
220
221
222
223
225 """
226 A unique value that won't compare equal to any other value. This
227 class is used to create L{UNKNOWN}.
228 """
232 return '<%s>' % self.name
234 raise ValueError('Sentinel value <%s> can not be used as a boolean' %
235 self.name)
236
237 UNKNOWN = _Sentinel('UNKNOWN')
238 """A special value used to indicate that a given piece of
239 information about an object is unknown. This is used as the
240 default value for all instance variables."""
241
242
243
244
245
247 """
248 API documentation information for a single element of a Python
249 program. C{APIDoc} itself is an abstract base class; subclasses
250 are used to specify what information should be recorded about each
251 type of program element. In particular, C{APIDoc} has two direct
252 subclasses, C{VariableDoc} for documenting variables and
253 C{ValueDoc} for documenting values; and the C{ValueDoc} class is
254 subclassed further for different value types.
255
256 Each C{APIDoc} subclass specifies the set of attributes that
257 should be used to record information about the corresponding
258 program element type. The default value for each attribute is
259 stored in the class; these default values can then be overridden
260 with instance variables. Most attributes use the special value
261 L{UNKNOWN} as their default value, to indicate that the correct
262 value for that attribute has not yet been determined. This makes
263 it easier to merge two C{APIDoc} objects that are documenting the
264 same element (in particular, to merge information about an element
265 that was derived from parsing with information that was derived
266 from introspection).
267
268 For all attributes with boolean values, use only the constants
269 C{True} and C{False} to designate true and false. In particular,
270 do I{not} use other values that evaluate as true or false, such as
271 C{2} or C{()}. This restriction makes it easier to handle
272 C{UNKNOWN} values. For example, to test if a boolean attribute is
273 C{True} or C{UNKNOWN}, use 'C{attrib in (True, UNKNOWN)}' or
274 'C{attrib is not False}'.
275
276 Two C{APIDoc} objects describing the same object can be X{merged},
277 using the method L{merge_and_overwrite(other)}. After two
278 C{APIDoc}s are merged, any changes to one will be reflected in the
279 other. This is accomplished by setting the two C{APIDoc} objects
280 to use a shared instance dictionary. See the documentation for
281 L{merge_and_overwrite} for more information, and some important
282 caveats about hashing.
283 """
284
285 docstring = UNKNOWN
286 """@ivar: The documented item's docstring.
287 @type: C{string} or C{None}"""
288
289 docstring_lineno = UNKNOWN
290 """@ivar: The line number on which the documented item's docstring
291 begins.
292 @type: C{int}"""
293
294
295
296 descr = UNKNOWN
297 """@ivar: A description of the documented item, extracted from its
298 docstring.
299 @type: L{ParsedDocstring<epydoc.markup.ParsedDocstring>}"""
300
301 summary = UNKNOWN
302 """@ivar: A summary description of the documented item, extracted from
303 its docstring.
304 @type: L{ParsedDocstring<epydoc.markup.ParsedDocstring>}"""
305
306 metadata = UNKNOWN
307 """@ivar: Metadata about the documented item, extracted from fields in
308 its docstring. I{Currently} this is encoded as a list of tuples
309 C{(field, arg, descr)}. But that may change.
310 @type: C{(str, str, L{ParsedDocstring<markup.ParsedDocstring>})}"""
311
312 extra_docstring_fields = UNKNOWN
313 """@ivar: A list of new docstring fields tags that are defined by the
314 documented item's docstring. These new field tags can be used by
315 this item or by any item it contains.
316 @type: L{DocstringField <epydoc.docstringparser.DocstringField>}"""
317
318
319
320 docs_extracted_by = UNKNOWN
321 """@ivar: Information about where the information contained by this
322 C{APIDoc} came from. Can be one of C{'parser'},
323 C{'introspector'}, or C{'both'}.
324 @type: C{str}"""
325
326
328 """
329 Construct a new C{APIDoc} object. Keyword arguments may be
330 used to initialize the new C{APIDoc}'s attributes.
331
332 @raise TypeError: If a keyword argument is specified that does
333 not correspond to a valid attribute for this (sub)class of
334 C{APIDoc}.
335 """
336 if epydoc.DEBUG:
337 for key in kwargs:
338 if not hasattr(self.__class__, key):
339 raise TypeError('%s got unexpected arg %r' %
340 (self.__class__.__name__, key))
341 self.__dict__.update(kwargs)
342
344 """
345 Modify an C{APIDoc}'s attribute. This is used when
346 L{epydoc.DEBUG} is true, to make sure we don't accidentally
347 set any inappropriate attributes on C{APIDoc} objects.
348
349 @raise AttributeError: If C{attr} is not a valid attribute for
350 this (sub)class of C{APIDoc}. (C{attr} is considered a
351 valid attribute iff C{self.__class__} defines an attribute
352 with that name.)
353 """
354
355
356 if attr.startswith('_'):
357 return object.__setattr__(self, attr, val)
358 if not hasattr(self, attr):
359 raise AttributeError('%s does not define attribute %r' %
360 (self.__class__.__name__, attr))
361 self.__dict__[attr] = val
362
363 if epydoc.DEBUG:
364 __setattr__ = _debug_setattr
365
367 return '<%s>' % self.__class__.__name__
368
369 - def pp(self, doublespace=0, depth=5, exclude=(), include=()):
370 """
371 Return a pretty-printed string representation for the
372 information contained in this C{APIDoc}.
373 """
374 return pp_apidoc(self, doublespace, depth, exclude, include)
375 __str__ = pp
376
378 """
379 Change C{self}'s class to C{cls}. C{cls} must be a subclass
380 of C{self}'s current class. For example, if a generic
381 C{ValueDoc} was created for a value, and it is determined that
382 the value is a routine, you can update its class with:
383
384 >>> valdoc.specialize_to(RoutineDoc)
385 """
386 if not issubclass(cls, self.__class__):
387 raise ValueError('Can not specialize to %r' % cls)
388
389 self.__class__ = cls
390
391 if self.__mergeset is not None:
392 for apidoc in self.__mergeset:
393 apidoc.__class__ = cls
394
395
396 self.__init__(**self.__dict__)
397
398 __has_been_hashed = False
399 """True iff L{self.__hash__()} has ever been called."""
400
404
406 if not isinstance(other, APIDoc): return -1
407 if self.__dict__ is other.__dict__: return 0
408 name_cmp = cmp(self.canonical_name, other.canonical_name)
409 if name_cmp == 0: return -1
410 else: return name_cmp
411
412 __mergeset = None
413 """The set of all C{APIDoc} objects that have been merged with
414 this C{APIDoc} (using L{merge_and_overwrite()}). Each C{APIDoc}
415 in this set shares a common instance dictionary (C{__dict__})."""
416
418 """
419 Combine C{self} and C{other} into a X{merged object}, such
420 that any changes made to one will affect the other. Any
421 attributes that C{other} had before merging will be discarded.
422 This is accomplished by copying C{self.__dict__} over
423 C{other.__dict__} and C{self.__class__} over C{other.__class__}.
424
425 Care must be taken with this method, since it modifies the
426 hash value of C{other}. To help avoid the problems that this
427 can cause, C{merge_and_overwrite} will raise an exception if
428 C{other} has ever been hashed, unless C{ignore_hash_conflict}
429 is True. Note that adding C{other} to a dictionary, set, or
430 similar data structure will implicitly cause it to be hashed.
431 If you do set C{ignore_hash_conflict} to True, then any
432 existing data structures that rely on C{other}'s hash staying
433 constant may become corrupted.
434
435 @return: C{self}
436 @raise ValueError: If C{other} has ever been hashed.
437 """
438
439 if (self.__dict__ is other.__dict__ and
440 self.__class__ is other.__class__): return self
441
442 if other.__has_been_hashed and not ignore_hash_conflict:
443 raise ValueError("%r has already been hashed! Merging it "
444 "would cause its has value to change." % other)
445
446
447
448 a,b = (self.__mergeset, other.__mergeset)
449 mergeset = (self.__mergeset or [self]) + (other.__mergeset or [other])
450 other.__dict__.clear()
451 for apidoc in mergeset:
452
453 apidoc.__class__ = self.__class__
454 apidoc.__dict__ = self.__dict__
455 self.__mergeset = mergeset
456
457 assert self in mergeset and other in mergeset
458 for apidoc in mergeset:
459 assert apidoc.__dict__ is self.__dict__
460
461 return self
462
464 """
465 Return a list of all C{APIDoc}s that are directly linked from
466 this C{APIDoc} (i.e., are contained or pointed to by one or
467 more of this C{APIDoc}'s attributes.)
468
469 Keyword argument C{filters} can be used to selectively exclude
470 certain categories of attribute value. For example, using
471 C{includes=False} will exclude variables that were imported
472 from other modules; and C{subclasses=False} will exclude
473 subclasses. The filter categories currently supported by
474 epydoc are:
475 - C{imports}: Imported variables.
476 - C{packages}: Containing packages for modules.
477 - C{submodules}: Contained submodules for packages.
478 - C{bases}: Bases for classes.
479 - C{subclasses}: Subclasses for classes.
480 - C{variables}: All variables.
481 - C{private}: Private variables.
482 """
483 return []
484
486 """
487 Return a list of all C{ValueDoc}s that can be reached, directly or
488 indirectly from the given root list of C{ValueDoc}s.
489
490 @param filters: A set of filters that can be used to prevent
491 C{reachable_valdocs} from following specific link types when
492 looking for C{ValueDoc}s that can be reached from the root
493 set. See C{APIDoc.apidoc_links} for a more complete
494 description.
495 """
496 apidoc_queue = list(root)
497 val_set = set()
498 var_set = set()
499 while apidoc_queue:
500 api_doc = apidoc_queue.pop()
501 if isinstance(api_doc, ValueDoc):
502 val_set.add(api_doc)
503 else:
504 var_set.add(api_doc)
505 apidoc_queue.extend([v for v in api_doc.apidoc_links(**filters)
506 if v not in val_set and v not in var_set])
507 return val_set
508
509
510
511
512
514 """
515 API documentation information about a single Python variable.
516
517 @note: The only time a C{VariableDoc} will have its own docstring
518 is if that variable was created using an assignment statement, and
519 that assignment statement had a docstring-comment or was followed
520 by a pseudo-docstring.
521 """
522
523 name = UNKNOWN
524 """@ivar: The name of this variable in its containing namespace.
525 @type: C{str}"""
526
527 container = UNKNOWN
528 """@ivar: API documentation for the namespace that contains this
529 variable.
530 @type: L{ValueDoc}"""
531
532 value = UNKNOWN
533 """@ivar: The API documentation for this variable's value.
534 @type: L{ValueDoc}"""
535
536
537
538 type_descr = UNKNOWN
539 """@ivar: A description of the variable's expected type, extracted from
540 its docstring.
541 @type: L{ParsedDocstring<epydoc.markup.ParsedDocstring>}"""
542
543
544
545 imported_from = UNKNOWN
546 """@ivar: The fully qualified dotted name of the variable that this
547 variable's value was imported from. This attribute should only
548 be defined if C{is_instvar} is true.
549 @type: L{DottedName}"""
550
551 is_imported = UNKNOWN
552 """@ivar: Was this variable's value imported from another module?
553 (Exception: variables that are explicitly included in __all__ have
554 C{is_imported} set to C{False}, even if they are in fact
555 imported.)
556 @type: C{bool}"""
557
558
559
560 is_instvar = UNKNOWN
561 """@ivar: If true, then this variable is an instance variable; if false,
562 then this variable is a class variable. This attribute should
563 only be defined if the containing namespace is a class
564 @type: C{bool}"""
565
566 overrides = UNKNOWN
567 """@ivar: The API documentation for the variable that is overridden by
568 this variable. This attribute should only be defined if the
569 containing namespace is a class.
570 @type: L{VariableDoc}"""
571
572
573
574 is_alias = UNKNOWN
575 """@ivar: Is this variable an alias for another variable with the same
576 value? If so, then this variable will be dispreferred when
577 assigning canonical names.
578 @type: C{bool}"""
579
580 is_public = UNKNOWN
581 """@ivar: Is this variable part of its container's public API?
582 @type: C{bool}"""
583
584
590
600
609 canonical_name = property(_get_canonical_name, doc="""
610 A read-only property that can be used to get the variable's
611 canonical name. This is formed by taking the varaible's
612 container's cannonical name, and adding the variable's name
613 to it.""")
614
619 defining_module = property(_get_defining_module, doc="""
620 A read-only property that can be used to get the variable's
621 defining module. This is defined as the defining module
622 of the variable's container.""")
623
625 if self.value in (None, UNKNOWN):
626 return []
627 else:
628 return [self.value]
629
630
631
632
633
635 """
636 API documentation information about a single Python value.
637 """
638 canonical_name = UNKNOWN
639 """@ivar: A dotted name that serves as a unique identifier for
640 this C{ValueDoc}'s value. If the value can be reached using a
641 single sequence of identifiers (given the appropriate imports),
642 then that sequence of identifiers is used as its canonical name.
643 If the value can be reached by multiple sequences of identifiers
644 (i.e., if it has multiple aliases), then one of those sequences of
645 identifiers is used. If the value cannot be reached by any
646 sequence of identifiers (e.g., if it was used as a base class but
647 then its variable was deleted), then its canonical name will start
648 with C{'??'}. If necessary, a dash followed by a number will be
649 appended to the end of a non-reachable identifier to make its
650 canonical name unique.
651
652 When possible, canonical names are chosen when new C{ValueDoc}s
653 are created. However, this is sometimes not possible. If a
654 canonical name can not be chosen when the C{ValueDoc} is created,
655 then one will be assigned by L{assign_canonical_names()
656 <docbuilder.assign_canonical_names>}.
657
658 @type: L{DottedName}"""
659
660
661 pyval = UNKNOWN
662 """@ivar: A pointer to the actual Python object described by this
663 C{ValueDoc}. This is used to display the value (e.g., when
664 describing a variable.) Use L{pyval_repr()} to generate a
665 plaintext string representation of this value.
666 @type: Python object"""
667
668 parse_repr = UNKNOWN
669 """@ivar: A text representation of this value, extracted from
670 parsing its source code. This representation may not accurately
671 reflect the actual value (e.g., if the value was modified after
672 the initial assignment).
673 @type: C{unicode}"""
674
675
676
677 defining_module = UNKNOWN
678 """@ivar: The documentation for the module that defines this
679 value. This is used, e.g., to lookup the appropriate markup
680 language for docstrings. For a C{ModuleDoc},
681 C{defining_module} should be C{self}.
682 @type: L{ModuleDoc}"""
683
684
685
686 proxy_for = None
687 """@ivar: If C{proxy_for} is not None, then this value was
688 imported from another file. C{proxy_for} is the dotted name of
689 the variable that this value was imported from. If that
690 variable is documented, then its C{value} may contain more
691 complete API documentation about this value. The C{proxy_for}
692 attribute is used by the source code parser to link imported
693 values to their source values (in particular, for base
694 classes). When possible, these proxy C{ValueDoc}s are replaced
695 by the imported value's C{ValueDoc} by
696 L{link_imports()<docbuilder.link_imports>}.
697 @type: L{DottedName}"""
698
699
700
701
702
703
704
705
706
707 toktree = UNKNOWN
708
718
720 """
721 Return a string representation of this value based on its pyval;
722 or UNKNOWN if we don't succeed. This should probably eventually
723 be replaced by more of a safe-repr variant.
724 """
725 if self.pyval == UNKNOWN:
726 return UNKNOWN
727 try:
728 s = '%r' % self.pyval
729 if isinstance(s, str):
730 s = decode_with_backslashreplace(s)
731 return s
732 except KeyboardInterrupt: raise
733 except: return UNKNOWN
734
736 return []
737
739 """
740 API documentation about a 'generic' value, i.e., one that does not
741 have its own docstring or any information other than its value and
742 parse representation. C{GenericValueDoc}s do not get assigned
743 cannonical names.
744 """
745 canonical_name = None
746
748 """
749 API documentation information about a singe Python namespace
750 value. (I.e., a module or a class).
751 """
752
753 variables = UNKNOWN
754 """@ivar: The contents of the namespace, encoded as a
755 dictionary mapping from identifiers to C{VariableDoc}s. This
756 dictionary contains all names defined by the namespace,
757 including imported variables, aliased variables, and variables
758 inherited from base classes (once L{DocInheriter
759 <epydoc.docinheriter.DocInheriter>} has added them).
760 @type: C{dict} from C{string} to L{VariableDoc}"""
761 sorted_variables = UNKNOWN
762 """@ivar: A list of all variables defined by this
763 namespace, in sorted order. The elements of this list should
764 exactly match the values of L{variables}. The sort order for
765 this list is defined as follows:
766 - Any variables listed in a C{@sort} docstring field are
767 listed in the order given by that field.
768 - These are followed by any variables that were found while
769 parsing the source code, in the order in which they were
770 defined in the source file.
771 - Finally, any remaining variables are listed in
772 alphabetical order.
773 @type: C{list} of L{VariableDoc}"""
774 sort_spec = UNKNOWN
775 """@ivar: The order in which variables should be listed,
776 encoded as a list of names. Any variables whose names are not
777 included in this list should be listed alphabetically,
778 following the variables that are included.
779 @type: C{list} of C{str}"""
780 group_specs = UNKNOWN
781 """@ivar: The groups that are defined by this namespace's
782 docstrings. C{group_specs} is encoded as an ordered list of
783 tuples C{(group_name, elt_names)}, where C{group_name} is the
784
785 name of a group and C{elt_names} is a list of element names in
786 that group. (An element can be a variable or a submodule.) A
787 '*' in an element name will match any string of characters.
788 @type: C{list} of C{(str,list)}"""
789 variable_groups = UNKNOWN
790 """@ivar: A dictionary specifying what group each
791 variable belongs to. The keys of the dictionary are group
792 names, and the values are lists of C{VariableDoc}s. The order
793 that groups should be listed in should be taken from
794 L{group_specs}.
795 @type: C{dict} from C{str} to C{list} of L{APIDoc}"""
796
797
802
821
823 """
824 Initialize the L{sorted_variables} attribute, based on the
825 L{variables} and L{sort_spec} attributes. This should usually
826 be called after all variables have been added to C{variables}
827 (including any inherited variables for classes).
828 """
829 unsorted = self.variables.copy()
830 self.sorted_variables = []
831
832
833 if self.sort_spec is not UNKNOWN:
834 for ident in self.sort_spec:
835 if ident in unsorted:
836 self.sorted_variables.append(unsorted[ident])
837 del unsorted[ident]
838 elif '*' in ident:
839 regexp = re.compile('^%s$' % ident.replace('*', '(.*)'))
840
841 for name, var_doc in unsorted.items():
842 if regexp.match(name):
843 self.sorted_variables.append(var_doc)
844 unsorted.remove(var_doc)
845
846
847 var_docs = unsorted.items()
848 var_docs.sort()
849 for name, var_doc in var_docs:
850 self.sorted_variables.append(var_doc)
851
863
865 """
866 Return a list of the group names defined by this namespace, in
867 the order in which they should be listed, with no duplicates.
868 """
869 name_list = ['']
870 name_set = set()
871 for name, spec in self.group_specs:
872 if name not in name_set:
873 name_set.add(name)
874 name_list.append(name)
875 return name_list
876
878 """
879 Divide a given a list of APIDoc objects into groups, as
880 specified by L{self.group_specs}.
881
882 @param elts: A list of tuples C{(name, apidoc)}.
883
884 @return: A list of tuples C{(groupname, elts)}, where
885 C{groupname} is the name of a group and C{elts} is a list of
886 C{APIDoc}s in that group. The first tuple has name C{''}, and
887 is used for ungrouped elements. The remaining tuples are
888 listed in the order that they appear in C{self.group_specs}.
889 Within each tuple, the elements are listed in the order that
890 they appear in C{api_docs}.
891 """
892
893 if len(self.group_specs) == 0:
894 return {'': [elt[1] for elt in elts]}
895
896 ungrouped = set([elt_doc for (elt_name, elt_doc) in elts])
897 groups = {}
898 for (group_name, elt_names) in self.group_specs:
899 group_re = re.compile('|'.join([n.replace('*','.*')+'$'
900 for n in elt_names]))
901 group = groups.get(group_name, [])
902 for elt_name, elt_doc in list(elts):
903 if group_re.match(elt_name):
904 group.append(elt_doc)
905 if elt_doc in ungrouped:
906 ungrouped.remove(elt_doc)
907 else:
908
909 log.warning("%s.%s is in multiple groups" %
910 (self.canonical_name, elt_name))
911 groups[group_name] = group
912
913
914 groups[''] = [elt_doc for (elt_name, elt_doc) in elts
915 if elt_doc in ungrouped]
916 return groups
917
919 """
920 API documentation information about a single module.
921 """
922
923 filename = UNKNOWN
924 """@ivar: The name of the file that defines the module.
925 @type: C{string}"""
926 docformat = UNKNOWN
927 """@ivar: The markup language used by docstrings in this module.
928 @type: C{string}"""
929
930 submodules = UNKNOWN
931 """@ivar: Modules contained by this module (if this module
932 is a package). (Note: on rare occasions, a module may have a
933 submodule that is shadowed by a variable with the same name.)
934 @type: C{list} of L{ModuleDoc}"""
935 submodule_groups = UNKNOWN
936 """@ivar: A dictionary specifying what group each
937 submodule belongs to. The keys of the dictionary are group
938 names, and the values are lists of C{ModuleDoc}s. The order
939 that groups should be listed in should be taken from
940 L{group_specs}.
941 @type: C{dict} from C{str} to C{list} of L{APIDoc}"""
942
943 package = UNKNOWN
944 """@ivar: API documentation for the module's containing package.
945 @type: L{ModuleDoc}"""
946 is_package = UNKNOWN
947 """@ivar: True if this C{ModuleDoc} describes a package.
948 @type: C{bool}"""
949 path = UNKNOWN
950 """@ivar: If this C{ModuleDoc} describes a package, then C{path}
951 contains a list of directories that constitute its path (i.e.,
952 the value of its C{__path__} variable).
953 @type: C{list} of C{str}"""
954
955 imports = UNKNOWN
956 """@ivar: A list of the source names of variables imported into
957 this module. This is used to construct import graphs.
958 @type: C{list} of L{DottedName}"""
959
960
970
982
983 - def select_variables(self, group=None, value_type=None, public=None,
984 imported=None):
985 """
986 Return a specified subset of this module's L{sorted_variables}
987 list. If C{value_type} is given, then only return variables
988 whose values have the specified type. If C{group} is given,
989 then only return variables that belong to the specified group.
990
991 @require: The L{sorted_variables} and L{groups} attributes
992 must be initialized before this method can be used. See
993 L{init_sorted_variables()} and L{init_groups()}.
994
995 @param value_type: A string specifying the value type for
996 which variables should be returned. Valid values are:
997 - 'class' - variables whose values are classes or types.
998 - 'function' - variables whose values are functions.
999 - 'other' - variables whose values are not classes,
1000 exceptions, types, or functions.
1001 @type value_type: C{string}
1002
1003 @param group: The name of the group for which variables should
1004 be returned. A complete list of the groups defined by
1005 this C{ModuleDoc} is available in the L{group_names}
1006 instance variable. The first element of this list is
1007 always the special group name C{''}, which is used for
1008 variables that do not belong to any group.
1009 @type group: C{string}
1010 """
1011 if (self.sorted_variables == UNKNOWN or
1012 self.variable_groups == UNKNOWN):
1013 raise ValueError('sorted_variables and variable_groups '
1014 'must be initialized first.')
1015
1016 if group is None: var_list = self.sorted_variables
1017 else:
1018 var_list = self.variable_groups[group]
1019
1020
1021 if public is True:
1022 var_list = [v for v in var_list if v.is_public is not False]
1023 elif public is False:
1024 var_list = [v for v in var_list if v.is_public is False]
1025
1026
1027 if imported is True:
1028 var_list = [v for v in var_list if v.is_imported is True]
1029 elif imported is False:
1030 var_list = [v for v in var_list if v.is_imported is not True]
1031
1032
1033
1034 if value_type is None:
1035 return var_list
1036 elif value_type == 'class':
1037 return [var_doc for var_doc in var_list
1038 if (isinstance(var_doc.value, ClassDoc))]
1039 elif value_type == 'function':
1040 return [var_doc for var_doc in var_list
1041 if isinstance(var_doc.value, RoutineDoc)]
1042 elif value_type == 'other':
1043 return [var_doc for var_doc in var_list
1044 if not isinstance(var_doc.value,
1045 (ClassDoc, RoutineDoc, ModuleDoc))]
1046 else:
1047 raise ValueError('Bad value type %r' % value_type)
1048
1050 """
1051 API documentation information about a single class.
1052 """
1053
1054 bases = UNKNOWN
1055 """@ivar: API documentation for the class's base classes.
1056 @type: C{list} of L{ClassDoc}"""
1057
1058 subclasses = UNKNOWN
1059 """@ivar: API documentation for the class's known subclasses.
1060 @type: C{list} of L{ClassDoc}"""
1061
1062
1072
1080
1088
1096
1097 - def mro(self, warn_about_bad_bases=False):
1102
1103 - def _dfs_bases(self, mro, seen, warn_about_bad_bases):
1114
1115 - def _c3_mro(self, warn_about_bad_bases):
1116 """
1117 Compute the class precedence list (mro) according to C3.
1118 @seealso: U{http://www.python.org/2.3/mro.html}
1119 """
1120 bases = [base for base in self.bases if isinstance(base, ClassDoc)]
1121 if len(bases) != len(self.bases) and warn_about_bad_bases:
1122 for base in self.bases:
1123 if (not isinstance(base, ClassDoc) or
1124 base.proxy_for is not None):
1125 self._report_bad_base(base)
1126 w = [warn_about_bad_bases]*len(bases)
1127 return self._c3_merge([[self]] + map(ClassDoc._c3_mro, bases, w) +
1128 [list(bases)])
1129
1137
1139 """
1140 Helper function for L{_c3_mro}.
1141 """
1142 res = []
1143 while 1:
1144 nonemptyseqs=[seq for seq in seqs if seq]
1145 if not nonemptyseqs: return res
1146 for seq in nonemptyseqs:
1147 cand = seq[0]
1148 nothead=[s for s in nonemptyseqs if cand in s[1:]]
1149 if nothead: cand=None
1150 else: break
1151 if not cand: raise "Inconsistent hierarchy"
1152 res.append(cand)
1153 for seq in nonemptyseqs:
1154 if seq[0] == cand: del seq[0]
1155
1156 - def select_variables(self, group=None, value_type=None,
1157 inherited=None, public=None, imported=None):
1158 """
1159 Return a specified subset of this class's L{sorted_variables}
1160 list. If C{value_type} is given, then only return variables
1161 whose values have the specified type. If C{group} is given,
1162 then only return variables that belong to the specified group.
1163 If C{inherited} is True, then only return inherited variables;
1164 if C{inherited} is False, then only return local variables.
1165
1166 @require: The L{sorted_variables} and L{groups} attributes
1167 must be initialized before this method can be used. See
1168 L{init_sorted_variables()} and L{init_groups()}.
1169
1170 @param value_type: A string specifying the value type for
1171 which variables should be returned. Valid values are:
1172 - 'instancemethod' - variables whose values are
1173 instance methods.
1174 - 'classmethod' - variables whose values are class
1175 methods.
1176 - 'staticmethod' - variables whose values are static
1177 methods.
1178 - 'properties' - variables whose values are properties.
1179 - 'class' - variables whose values are nested classes
1180 (including exceptions and types).
1181 - 'instancevariable' - instance variables. This includes
1182 any variables that are explicitly marked as instance
1183 variables with docstring fields; and variables with
1184 docstrings that are initialized in the constructor.
1185 - 'classvariable' - class variables. This includes any
1186 variables that are not included in any of the above
1187 categories.
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{ClassDoc} 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 inherited: If C{None}, then return both inherited and
1199 local variables; if C{True}, then return only inherited
1200 variables; if C{False}, then return only local variables.
1201 """
1202 if (self.sorted_variables == UNKNOWN or
1203 self.variable_groups == UNKNOWN):
1204 raise ValueError('sorted_variables and variable_groups '
1205 'must be initialized first.')
1206
1207 if group is None: var_list = self.sorted_variables
1208 else: var_list = self.variable_groups[group]
1209
1210
1211 if public is True:
1212 var_list = [v for v in var_list if v.is_public is not False]
1213 elif public is False:
1214 var_list = [v for v in var_list if v.is_public is False]
1215
1216
1217 if inherited is None: pass
1218 elif inherited:
1219 var_list = [v for v in var_list if v.container != self]
1220 else:
1221 var_list = [v for v in var_list if v.container == self ]
1222
1223
1224 if imported is True:
1225 var_list = [v for v in var_list if v.is_imported is True]
1226 elif imported is False:
1227 var_list = [v for v in var_list if v.is_imported is not True]
1228
1229 if value_type is None:
1230 return var_list
1231 elif value_type == 'method':
1232 return [var_doc for var_doc in var_list
1233 if (isinstance(var_doc.value, RoutineDoc) and
1234 var_doc.is_instvar in (False, UNKNOWN))]
1235 elif value_type == 'instancemethod':
1236 return [var_doc for var_doc in var_list
1237 if (isinstance(var_doc.value, RoutineDoc) and
1238 not isinstance(var_doc.value, ClassMethodDoc) and
1239 not isinstance(var_doc.value, StaticMethodDoc) and
1240 var_doc.is_instvar in (False, UNKNOWN))]
1241 elif value_type == 'classmethod':
1242 return [var_doc for var_doc in var_list
1243 if (isinstance(var_doc.value, ClassMethodDoc) and
1244 var_doc.is_instvar in (False, UNKNOWN))]
1245 elif value_type == 'staticmethod':
1246 return [var_doc for var_doc in var_list
1247 if (isinstance(var_doc.value, StaticMethodDoc) and
1248 var_doc.is_instvar in (False, UNKNOWN))]
1249 elif value_type == 'property':
1250 return [var_doc for var_doc in var_list
1251 if (isinstance(var_doc.value, PropertyDoc) and
1252 var_doc.is_instvar in (False, UNKNOWN))]
1253 elif value_type == 'class':
1254 return [var_doc for var_doc in var_list
1255 if (isinstance(var_doc.value, ClassDoc) and
1256 var_doc.is_instvar in (False, UNKNOWN))]
1257 elif value_type == 'instancevariable':
1258 return [var_doc for var_doc in var_list
1259 if var_doc.is_instvar is True]
1260 elif value_type == 'classvariable':
1261 return [var_doc for var_doc in var_list
1262 if (var_doc.is_instvar in (False, UNKNOWN) and
1263 not isinstance(var_doc.value,
1264 (RoutineDoc, ClassDoc, PropertyDoc)))]
1265 else:
1266 raise ValueError('Bad value type %r' % value_type)
1267
1269 """
1270 API documentation information about a single routine.
1271 """
1272
1273 posargs = UNKNOWN
1274 """@ivar: The names of the routine's positional arguments.
1275 If an argument list contains \"unpacking\" arguments, then
1276 their names will be specified using nested lists. E.g., if
1277 a function's argument list is C{((x1,y1), (x2,y2))}, then
1278 posargs will be C{[['x1','y1'], ['x2','y2']]}.
1279 @type: C{list}"""
1280 posarg_defaults = UNKNOWN
1281 """@ivar: API documentation for the positional arguments'
1282 default values. This list has the same length as C{posargs}, and
1283 each element of C{posarg_defaults} describes the corresponding
1284 argument in C{posargs}. For positional arguments with no default,
1285 C{posargs_defaults} will contain None.
1286 @type: C{list} of C{ValueDoc} or C{None}"""
1287 vararg = UNKNOWN
1288 """@ivar: The name of the routine's vararg argument, or C{None} if
1289 it has no vararg argument.
1290 @type: C{string} or C{None}"""
1291 kwarg = UNKNOWN
1292 """@ivar: The name of the routine's keyword argument, or C{None} if
1293 it has no keyword argument.
1294 @type: C{string} or C{None}"""
1295 lineno = UNKNOWN
1296 """@ivar: The line number of the first line of the function's
1297 signature. For Python functions, this is equal to
1298 C{func.func_code.co_firstlineno}. The first line of a file
1299 is considered line 1.
1300 @type: C{int}"""
1301
1302
1303
1304 arg_descrs = UNKNOWN
1305 """@ivar: A list of descriptions of the routine's
1306 arguments. Each element of this list is a tuple C{(arg,
1307 descr)}, where C{arg} is an argument name (or a tuple of
1308 of argument names); and C{descr} is a L{ParsedDocstring
1309 <epydoc.markup.ParsedDocstring>} describing the argument(s)
1310 specified by C{arg}.
1311 @type: C{list}"""
1312 arg_types = UNKNOWN
1313 """@ivar: Descriptions of the expected types for the
1314 routine's arguments, encoded as a dictionary mapping from
1315 argument names to type descriptions.
1316 @type: C{dict} from C{string} to L{ParsedDocstring
1317 <epydoc.markup.ParsedDocstring>}"""
1318 return_descr = UNKNOWN
1319 """@ivar: A description of the value returned by this routine.
1320 @type: L{ParsedDocstring<epydoc.markup.ParsedDocstring>}"""
1321 return_type = UNKNOWN
1322 """@ivar: A description of expected type for the value
1323 returned by this routine.
1324 @type: L{ParsedDocstring<epydoc.markup.ParsedDocstring>}"""
1325 exception_descrs = UNKNOWN
1326 """@ivar: A list of descriptions of exceptions
1327 that the routine might raise. Each element of this list is a
1328 tuple C{(exc, descr)}, where C{exc} is a string contianing the
1329 exception name; and C{descr} is a L{ParsedDocstring
1330 <epydoc.markup.ParsedDocstring>} describing the circumstances
1331 under which the exception specified by C{exc} is raised.
1332 @type: C{list}"""
1333
1334
1336 """
1337 @return: A list of the names of all arguments (positional,
1338 vararg, and keyword), in order. If a positional argument
1339 consists of a tuple of names, then that tuple will be
1340 flattened.
1341 """
1342 all_args = _flatten(self.posargs)
1343 if self.vararg not in (None, UNKNOWN):
1344 all_args.append(self.vararg)
1345 if self.kwarg not in (None, UNKNOWN):
1346 all_args.append(self.kwarg)
1347 return all_args
1348
1350 """
1351 Return a flattened version of C{lst}.
1352 """
1353 if out is None: out = []
1354 for elt in lst:
1355 if isinstance(elt, (list,tuple)):
1356 _flatten(elt, out)
1357 else:
1358 out.append(elt)
1359 return out
1360
1363
1365 """
1366 API documentation information about a single property.
1367 """
1368
1369 fget = UNKNOWN
1370 """@ivar: API documentation for the property's get function.
1371 @type: L{RoutineDoc}"""
1372 fset = UNKNOWN
1373 """@ivar: API documentation for the property's set function.
1374 @type: L{RoutineDoc}"""
1375 fdel = UNKNOWN
1376 """@ivar: API documentation for the property's delete function.
1377 @type: L{RoutineDoc}"""
1378
1379
1380 type_descr = UNKNOWN
1381 """@ivar: A description of the property's expected type, extracted
1382 from its docstring.
1383 @type: L{ParsedDocstring<epydoc.markup.ParsedDocstring>}"""
1384
1385
1387 val_docs = []
1388 if self.fget not in (None, UNKNOWN): val_docs.append(self.fget)
1389 if self.fset not in (None, UNKNOWN): val_docs.append(self.fset)
1390 if self.fdel not in (None, UNKNOWN): val_docs.append(self.fdel)
1391 return val_docs
1392
1393
1394
1395
1396
1398 """
1399 [xx] out of date.
1400
1401 An index that .. hmm... it *can't* be used to access some things,
1402 cuz they're not at the root level. Do I want to add them or what?
1403 And if so, then I have a sort of a new top level. hmm.. so
1404 basically the question is what to do with a name that's not in the
1405 root var's name space. 2 types:
1406 - entirely outside (eg os.path)
1407 - inside but not known (eg a submodule that we didn't look at?)
1408 - container of current thing not examined?
1409
1410 An index of all the C{APIDoc} objects that can be reached from a
1411 root set of C{ValueDoc}s.
1412
1413 The members of this index can be accessed by dotted name. In
1414 particular, C{DocIndex} defines two mappings, accessed via the
1415 L{get_vardoc()} and L{get_valdoc()} methods, which can be used to
1416 access C{VariableDoc}s or C{ValueDoc}s respectively by name. (Two
1417 separate mappings are necessary because a single name can be used
1418 to refer to both a variable and to the value contained by that
1419 variable.)
1420
1421 Additionally, the index defines two sets of C{ValueDoc}s:
1422 \"reachable C{ValueDoc}s\" and \"contained C{ValueDoc}s\". The
1423 X{reachable C{ValueDoc}s} are defined as the set of all
1424 C{ValueDoc}s that can be reached from the root set by following
1425 I{any} sequence of pointers to C{ValueDoc}s or C{VariableDoc}s.
1426 The X{contained C{ValueDoc}s} are defined as the set of all
1427 C{ValueDoc}s that can be reached from the root set by following
1428 only the C{ValueDoc} pointers defined by non-imported
1429 C{VariableDoc}s. For example, if the root set contains a module
1430 C{m}, then the contained C{ValueDoc}s includes the C{ValueDoc}s
1431 for any functions, variables, or classes defined in that module,
1432 as well as methods and variables defined in classes defined in the
1433 module. The reachable C{ValueDoc}s includes all of those
1434 C{ValueDoc}s, as well as C{ValueDoc}s for any values imported into
1435 the module, and base classes for classes defined in the module.
1436 """
1437
1439 """
1440 Create a new documentation index, based on the given root set
1441 of C{ValueDoc}s. If any C{APIDoc}s reachable from the root
1442 set does not have a canonical name, then it will be assigned
1443 one. etc.
1444
1445 @param root: A list of C{ValueDoc}s.
1446 """
1447 for apidoc in root:
1448 if apidoc.canonical_name in (None, UNKNOWN):
1449 raise ValueError("All APIdocs passed to DocIndexer "
1450 "must already have canonical names.")
1451
1452
1453
1454
1455 self.root = sorted(root, key=lambda d:len(d.canonical_name))
1456
1457 self.callers = None
1458 """A dictionary mapping from C{RoutineDoc}s in this index
1459 to lists of C{RoutineDoc}s for the routine's callers.
1460 This dictionary is initialized by calling
1461 L{read_profiling_info()}.
1462 @type: C{list} of L{RoutineDoc}"""
1463
1464 self.callees = None
1465 """A dictionary mapping from C{RoutineDoc}s in this index
1466 to lists of C{RoutineDoc}s for the routine's callees.
1467 This dictionary is initialized by calling
1468 L{read_profiling_info()}.
1469 @type: C{list} of L{RoutineDoc}"""
1470
1471 self._funcid_to_doc = {}
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1484 """
1485 Return the C{VariableDoc} with the given name, or C{None} if this
1486 index does not contain a C{VariableDoc} with the given name.
1487 """
1488 var, val = self._get(name)
1489 return var
1490
1492 """
1493 Return the C{ValueDoc} with the given name, or C{None} if this
1494 index does not contain a C{ValueDoc} with the given name.
1495 """
1496 var, val = self._get(name)
1497 return val
1498
1499 - def _get(self, name):
1500 """
1501 A helper function that's used to implement L{get_vardoc()}
1502 and L{get_valdoc()}.
1503 """
1504
1505 name = DottedName(name)
1506
1507
1508
1509 for root_valdoc in self.root:
1510 if root_valdoc.canonical_name.dominates(name):
1511
1512
1513 var_doc = None
1514 val_doc = root_valdoc
1515 for identifier in name[len(root_valdoc.canonical_name):]:
1516 if val_doc is None: break
1517 var_doc, val_doc = self._get_from(val_doc, identifier)
1518 else:
1519
1520 if var_doc is not None or val_doc is not None:
1521 return var_doc, val_doc
1522
1523
1524 return None, None
1525
1527 if isinstance(val_doc, NamespaceDoc):
1528 child_var = val_doc.variables.get(identifier)
1529 if child_var is not None:
1530 child_val = child_var.value
1531 if child_val == UNKNOWN: child_val = None
1532 return child_var, child_val
1533
1534
1535 if (isinstance(val_doc, ModuleDoc) and
1536 val_doc.submodules is not UNKNOWN):
1537 for submodule in val_doc.submodules:
1538 if (submodule.canonical_name ==
1539 DottedName(val_doc.canonical_name, identifier)):
1540 var_doc = None
1541 val_doc = submodule
1542 if val_doc is UNKNOWN: val_doc = None
1543 return var_doc, val_doc
1544
1545 return None, None
1546
1547 - def find(self, name, context):
1548 """
1549 Look for a C{ValueDoc} named C{name}, relative to C{context}.
1550 Return the C{ValueDoc} if one is found; otherwise, return
1551 C{None}. C{find} looks in the following places, in order:
1552 - Function parameters (if one matches, return C{None})
1553 - All enclosing namespaces, from closest to furthest.
1554 - If C{name} starts with C{'self'}, then strip it off and
1555 look for the remaining part of the name using C{find}
1556 - Builtins
1557 - Parameter attributes
1558
1559 @type name: C{str} or L{DottedName}
1560 @type context: L{ValueDoc}
1561 """
1562 if isinstance(name, basestring):
1563 name = re.sub(r'\(.*\)$', '', name.strip())
1564 if re.match('^([a-zA-Z_]\w*)(\.[a-zA-Z_]\w*)*$', name):
1565 name = DottedName(name)
1566 else:
1567 return None
1568 elif not isinstance(name, DottedName):
1569 raise TypeError("'name' should be a string or DottedName")
1570
1571 if context is None or context.canonical_name is None:
1572 container_name = []
1573 else:
1574 container_name = context.canonical_name
1575
1576
1577
1578 for i in range(len(container_name), -1, -1):
1579 relative_name = container_name[:i]+name
1580
1581 val_doc = self.get_valdoc(relative_name)
1582 if val_doc is not None: return val_doc
1583
1584 var_doc = self.get_vardoc(relative_name)
1585 if var_doc is not None: return var_doc
1586
1587
1588
1589 if name[0] == 'self':
1590 doc = self.find('.'.join(name[1:]), context)
1591 if doc is not None: return doc
1592
1593
1594 if len(name)==1 and hasattr(__builtin__, name[0]):
1595 return None
1596
1597
1598 if (isinstance(context, RoutineDoc) and
1599 name[0] in context.all_args()):
1600 return None
1601
1602
1603
1604
1605
1607 """
1608 Return a list of all C{ValueDoc}s that can be reached,
1609 directly or indirectly from this C{DocIndex}'s root set.
1610
1611 @param filters: A set of filters that can be used to prevent
1612 C{reachable_valdocs} from following specific link types
1613 when looking for C{ValueDoc}s that can be reached from the
1614 root set. See C{APIDoc.apidoc_links} for a more complete
1615 description.
1616 """
1617 return reachable_valdocs(self.root, **filters)
1618
1635
1636
1637
1638
1639
1641 """
1642 Initialize the L{callers} and L{callees} variables, given a
1643 C{Stat} object from the C{pstats} module.
1644
1645 @warning: This method uses undocumented data structures inside
1646 of C{profile_stats}.
1647 """
1648 if self.callers is None: self.callers = {}
1649 if self.callees is None: self.callees = {}
1650
1651
1652
1653
1654 self._update_funcid_to_doc(profile_stats)
1655
1656 for callee, (cc, nc, tt, ct, callers) in profile_stats.stats.items():
1657 callee = self._funcid_to_doc.get(callee)
1658 if callee is None: continue
1659 for caller in callers:
1660 caller = self._funcid_to_doc.get(caller)
1661 if caller is None: continue
1662 self.callers.setdefault(callee, []).append(caller)
1663 self.callees.setdefault(caller, []).append(callee)
1664
1686
1687
1688
1689
1690
1691 -def pp_apidoc(api_doc, doublespace=0, depth=5, exclude=(), include=(),
1692 backpointers=None):
1693 """
1694 @return: A multiline pretty-printed string representation for the
1695 given C{APIDoc}.
1696 @param doublespace: If true, then extra lines will be
1697 inserted to make the output more readable.
1698 @param depth: The maximum depth that pp_apidoc will descend
1699 into descendent VarDocs. To put no limit on
1700 depth, use C{depth=-1}.
1701 @param exclude: A list of names of attributes whose values should
1702 not be shown.
1703 @param backpointers: For internal use.
1704 """
1705 pyid = id(api_doc.__dict__)
1706 if backpointers is None: backpointers = {}
1707 if (hasattr(api_doc, 'canonical_name') and
1708 api_doc.canonical_name not in (None, UNKNOWN)):
1709 name = '%s for %s' % (api_doc.__class__.__name__,
1710 api_doc.canonical_name)
1711 elif hasattr(api_doc, 'name') and api_doc.name not in (UNKNOWN, None):
1712 name = '%s for %s' % (api_doc.__class__.__name__, api_doc.name)
1713 else:
1714 name = api_doc.__class__.__name__
1715
1716 if pyid in backpointers:
1717 return '%s [%s] (defined above)' % (name, backpointers[pyid])
1718
1719 if depth == 0:
1720 if hasattr(api_doc, 'name') and api_doc.name is not None:
1721 return '%s...' % api_doc.name
1722 else:
1723 return '...'
1724
1725 backpointers[pyid] = len(backpointers)
1726 s = '%s [%s]' % (name, backpointers[pyid])
1727
1728
1729 fields = [field for field in api_doc.__dict__.keys()
1730 if (field in include or
1731 (getattr(api_doc, field) is not UNKNOWN
1732 and field not in exclude))]
1733 if include:
1734 fields = [field for field in dir(api_doc)
1735 if field in include]
1736 else:
1737 fields = [field for field in api_doc.__dict__.keys()
1738 if (getattr(api_doc, field) is not UNKNOWN
1739 and field not in exclude)]
1740 fields.sort()
1741
1742 for field in fields:
1743 fieldval = getattr(api_doc, field)
1744 if doublespace: s += '\n |'
1745 s += '\n +- %s' % field
1746
1747 if (isinstance(fieldval, types.ListType) and
1748 len(fieldval)>0 and
1749 isinstance(fieldval[0], APIDoc)):
1750 s += _pp_list(api_doc, fieldval, doublespace, depth,
1751 exclude, include, backpointers,
1752 (field is fields[-1]))
1753 elif (isinstance(fieldval, types.DictType) and
1754 len(fieldval)>0 and
1755 isinstance(fieldval.values()[0], APIDoc)):
1756 s += _pp_dict(api_doc, fieldval, doublespace,
1757 depth, exclude, include, backpointers,
1758 (field is fields[-1]))
1759 elif isinstance(fieldval, APIDoc):
1760 s += _pp_apidoc(api_doc, fieldval, doublespace, depth,
1761 exclude, include, backpointers,
1762 (field is fields[-1]))
1763 else:
1764 s += ' = ' + _pp_val(api_doc, fieldval, doublespace,
1765 depth, exclude, include, backpointers)
1766
1767 return s
1768
1769 -def _pp_list(api_doc, items, doublespace, depth, exclude, include,
1770 backpointers, is_last):
1771 line1 = (is_last and ' ') or '|'
1772 s = ''
1773 for item in items:
1774 line2 = ((item is items[-1]) and ' ') or '|'
1775 joiner = '\n %s %s ' % (line1, line2)
1776 if doublespace: s += '\n %s |' % line1
1777 s += '\n %s +- ' % line1
1778 valstr = _pp_val(api_doc, item, doublespace, depth, exclude, include,
1779 backpointers)
1780 s += joiner.join(valstr.split('\n'))
1781 return s
1782
1783 -def _pp_dict(api_doc, dict, doublespace, depth, exclude, include,
1784 backpointers, is_last):
1785 items = dict.items()
1786 items.sort()
1787 line1 = (is_last and ' ') or '|'
1788 s = ''
1789 for item in items:
1790 line2 = ((item is items[-1]) and ' ') or '|'
1791 joiner = '\n %s %s ' % (line1, line2)
1792 if doublespace: s += '\n %s |' % line1
1793 s += '\n %s +- ' % line1
1794 valstr = _pp_val(api_doc, item[1], doublespace, depth, exclude,
1795 include, backpointers)
1796 s += joiner.join(('%s => %s' % (item[0], valstr)).split('\n'))
1797 return s
1798
1799 -def _pp_apidoc(api_doc, val, doublespace, depth, exclude, include,
1800 backpointers, is_last):
1801 line1 = (is_last and ' ') or '|'
1802 s = ''
1803 if doublespace: s += '\n %s | ' % line1
1804 s += '\n %s +- ' % line1
1805 joiner = '\n %s ' % line1
1806 childstr = pp_apidoc(val, doublespace, depth-1, exclude,
1807 include, backpointers)
1808 return s + joiner.join(childstr.split('\n'))
1809
1810 -def _pp_val(api_doc, val, doublespace, depth, exclude, include, backpointers):
1811 from epydoc import markup
1812 if isinstance(val, APIDoc):
1813 return pp_apidoc(val, doublespace, depth-1, exclude,
1814 include, backpointers)
1815 elif isinstance(val, markup.ParsedDocstring):
1816 valrepr = `val.to_plaintext(None)`
1817 if len(valrepr) < 40: return valrepr
1818 else: return valrepr[:37]+'...'
1819 else:
1820 valrepr = repr(val)
1821 if len(valrepr) < 40: return valrepr
1822 else: return valrepr[:37]+'...'
1823