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 @todo: Add a cache to canonical name lookup?
34 """
35 __docformat__ = 'epytext en'
36
37
38
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 *
46 from epydoc.util import decode_with_backslashreplace, py_src_filename
47 import epydoc.markup.pyval_repr
48
49
50
51
52
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
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
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]
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
132 idents = [`ident` for ident in self._identifiers]
133 return 'DottedName(' + ', '.join(idents) + ')'
134
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
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
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
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
180 return hash(self._identifiers)
181
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
194 """
195 Return the number of identifiers in this dotted name.
196 """
197 return len(self._identifiers)
198
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
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
226
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
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
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
269
270
272 """
273 A unique value that won't compare equal to any other value. This
274 class is used to create L{UNKNOWN}.
275 """
279 return '<%s>' % self.name
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
291
292
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
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
341
342
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
370
371
372 docs_extracted_by = UNKNOWN
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
378
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
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
407
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
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
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
441 self.__class__ = cls
442
443 if self.__mergeset is not None:
444 for apidoc in self.__mergeset:
445 apidoc.__class__ = cls
446
447
448 self.__init__(**self.__dict__)
449
450 __has_been_hashed = False
451 """True iff L{self.__hash__()} has ever been called."""
452
456
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
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
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
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 has value to change." % other)
510
511
512
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
518 apidoc.__class__ = self.__class__
519 apidoc.__dict__ = self.__dict__
520 self.__mergeset = mergeset
521
522 assert self in mergeset and other in mergeset
523 for apidoc in mergeset:
524 assert apidoc.__dict__ is self.__dict__
525
526 return self
527
529 """
530 Return a list of all C{APIDoc}s that are directly linked from
531 this C{APIDoc} (i.e., are contained or pointed to by one or
532 more of this C{APIDoc}'s attributes.)
533
534 Keyword argument C{filters} can be used to selectively exclude
535 certain categories of attribute value. For example, using
536 C{includes=False} will exclude variables that were imported
537 from other modules; and C{subclasses=False} will exclude
538 subclasses. The filter categories currently supported by
539 epydoc are:
540 - C{imports}: Imported variables.
541 - C{packages}: Containing packages for modules.
542 - C{submodules}: Contained submodules for packages.
543 - C{bases}: Bases for classes.
544 - C{subclasses}: Subclasses for classes.
545 - C{variables}: All variables.
546 - C{private}: Private variables.
547 - C{overrides}: Points from class variables to the variables
548 they override. This filter is False by default.
549 """
550 return []
551
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
578
579
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
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
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
616
617
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
631
632
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
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
645
646
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
657
663
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
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
714
715
716
717
718
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
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
785
786
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
794
795
796 proxy_for = None
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
809
810
811
812
813
814
815
816
817 toktree = UNKNOWN
818
825
827 self.__dict__ = state
828
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
836
837
838 if not hasattr(self, '_ValueDoc__pickle_state'):
839
840 self.pyval_repr(), self.summary_pyval_repr()
841
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
848 return self.__pickle_state
849
850
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
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
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
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
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
897
900
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
912
914 """
915 API documentation information about a singe Python namespace
916 value. (I.e., a module or a class).
917 """
918
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
963
968
971
990
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
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
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
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
1039
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
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
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 else:
1086 log.warning("%s.%s in multiple groups" %
1087 (self.canonical_name, elt_name))
1088
1089
1090 groups[''] = [elt_doc for (elt_name, elt_doc) in elts
1091 if elt_name in ungrouped]
1092 return groups
1093
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
1105 """
1106 API documentation information about a single module.
1107 """
1108
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
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
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
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
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
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
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
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
1231
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
1248 """
1249 API documentation information about a single class.
1250 """
1251
1252 bases = UNKNOWN
1253 """@ivar: API documentation for the class's base classes.
1254 @type: C{list} of L{ClassDoc}"""
1255
1256 subclasses = UNKNOWN
1257 """@ivar: API documentation for the class's known subclasses.
1258 @type: C{list} of L{ClassDoc}"""
1259
1260
1270
1278
1286
1294
1295 - def mro(self, warn_about_bad_bases=False):
1300
1301 - def _dfs_bases(self, mro, seen, warn_about_bad_bases):
1312
1313 - def _c3_mro(self, warn_about_bad_bases):
1314 """
1315 Compute the class precedence list (mro) according to C3.
1316 @seealso: U{http://www.python.org/2.3/mro.html}
1317 """
1318 bases = [base for base in self.bases if isinstance(base, ClassDoc)]
1319 if len(bases) != len(self.bases) and warn_about_bad_bases:
1320 for base in self.bases:
1321 if (not isinstance(base, ClassDoc) or
1322 base.proxy_for is not None):
1323 self._report_bad_base(base)
1324 w = [warn_about_bad_bases]*len(bases)
1325 return self._c3_merge([[self]] + map(ClassDoc._c3_mro, bases, w) +
1326 [list(bases)])
1327
1341
1343 """
1344 Helper function for L{_c3_mro}.
1345 """
1346 res = []
1347 while 1:
1348 nonemptyseqs=[seq for seq in seqs if seq]
1349 if not nonemptyseqs: return res
1350 for seq in nonemptyseqs:
1351 cand = seq[0]
1352 nothead=[s for s in nonemptyseqs if cand in s[1:]]
1353 if nothead: cand=None
1354 else: break
1355 if not cand: raise "Inconsistent hierarchy"
1356 res.append(cand)
1357 for seq in nonemptyseqs:
1358 if seq[0] == cand: del seq[0]
1359
1360 - def select_variables(self, group=None, value_type=None, inherited=None,
1361 public=None, imported=None, detailed=None):
1362 """
1363 Return a specified subset of this class's L{sorted_variables}
1364 list. If C{value_type} is given, then only return variables
1365 whose values have the specified type. If C{group} is given,
1366 then only return variables that belong to the specified group.
1367 If C{inherited} is True, then only return inherited variables;
1368 if C{inherited} is False, then only return local variables.
1369
1370 @require: The L{sorted_variables} and L{variable_groups}
1371 attributes must be initialized before this method can be
1372 used. See L{init_sorted_variables()} and
1373 L{init_variable_groups()}.
1374
1375 @param value_type: A string specifying the value type for
1376 which variables should be returned. Valid values are:
1377 - 'instancemethod' - variables whose values are
1378 instance methods.
1379 - 'classmethod' - variables whose values are class
1380 methods.
1381 - 'staticmethod' - variables whose values are static
1382 methods.
1383 - 'properties' - variables whose values are properties.
1384 - 'class' - variables whose values are nested classes
1385 (including exceptions and types).
1386 - 'instancevariable' - instance variables. This includes
1387 any variables that are explicitly marked as instance
1388 variables with docstring fields; and variables with
1389 docstrings that are initialized in the constructor.
1390 - 'classvariable' - class variables. This includes any
1391 variables that are not included in any of the above
1392 categories.
1393 @type value_type: C{string}
1394
1395 @param group: The name of the group for which variables should
1396 be returned. A complete list of the groups defined by
1397 this C{ClassDoc} is available in the L{group_names}
1398 instance variable. The first element of this list is
1399 always the special group name C{''}, which is used for
1400 variables that do not belong to any group.
1401 @type group: C{string}
1402
1403 @param inherited: If C{None}, then return both inherited and
1404 local variables; if C{True}, then return only inherited
1405 variables; if C{False}, then return only local variables.
1406
1407 @param detailed: If True (False), return only the variables
1408 deserving (not deserving) a detailed informative box.
1409 If C{None}, don't care.
1410 @type detailed: C{bool}
1411 """
1412 if (self.sorted_variables is UNKNOWN or
1413 self.variable_groups is UNKNOWN):
1414 raise ValueError('sorted_variables and variable_groups '
1415 'must be initialized first.')
1416
1417 if group is None: var_list = self.sorted_variables
1418 else: var_list = self.variable_groups[group]
1419
1420
1421 if public is True:
1422 var_list = [v for v in var_list if v.is_public is not False]
1423 elif public is False:
1424 var_list = [v for v in var_list if v.is_public is False]
1425
1426
1427 if inherited is None: pass
1428 elif inherited:
1429 var_list = [v for v in var_list if v.container != self]
1430 else:
1431 var_list = [v for v in var_list if v.container == self ]
1432
1433
1434 if imported is True:
1435 var_list = [v for v in var_list if v.is_imported is True]
1436 elif imported is False:
1437 var_list = [v for v in var_list if v.is_imported is not True]
1438
1439
1440 if detailed is True:
1441 var_list = [v for v in var_list if v.is_detailed() is True]
1442 elif detailed is False:
1443 var_list = [v for v in var_list if v.is_detailed() is not True]
1444
1445 if value_type is None:
1446 return var_list
1447 elif value_type == 'method':
1448 return [var_doc for var_doc in var_list
1449 if (isinstance(var_doc.value, RoutineDoc) and
1450 var_doc.is_instvar in (False, UNKNOWN))]
1451 elif value_type == 'instancemethod':
1452 return [var_doc for var_doc in var_list
1453 if (isinstance(var_doc.value, RoutineDoc) and
1454 not isinstance(var_doc.value, ClassMethodDoc) and
1455 not isinstance(var_doc.value, StaticMethodDoc) and
1456 var_doc.is_instvar in (False, UNKNOWN))]
1457 elif value_type == 'classmethod':
1458 return [var_doc for var_doc in var_list
1459 if (isinstance(var_doc.value, ClassMethodDoc) and
1460 var_doc.is_instvar in (False, UNKNOWN))]
1461 elif value_type == 'staticmethod':
1462 return [var_doc for var_doc in var_list
1463 if (isinstance(var_doc.value, StaticMethodDoc) and
1464 var_doc.is_instvar in (False, UNKNOWN))]
1465 elif value_type == 'property':
1466 return [var_doc for var_doc in var_list
1467 if (isinstance(var_doc.value, PropertyDoc) and
1468 var_doc.is_instvar in (False, UNKNOWN))]
1469 elif value_type == 'class':
1470 return [var_doc for var_doc in var_list
1471 if (isinstance(var_doc.value, ClassDoc) and
1472 var_doc.is_instvar in (False, UNKNOWN))]
1473 elif value_type == 'instancevariable':
1474 return [var_doc for var_doc in var_list
1475 if var_doc.is_instvar is True]
1476 elif value_type == 'classvariable':
1477 return [var_doc for var_doc in var_list
1478 if (var_doc.is_instvar in (False, UNKNOWN) and
1479 not isinstance(var_doc.value,
1480 (RoutineDoc, ClassDoc, PropertyDoc)))]
1481 else:
1482 raise ValueError('Bad value type %r' % value_type)
1483
1485 """
1486 API documentation information about a single routine.
1487 """
1488
1489 posargs = UNKNOWN
1490 """@ivar: The names of the routine's positional arguments.
1491 If an argument list contains \"unpacking\" arguments, then
1492 their names will be specified using nested lists. E.g., if
1493 a function's argument list is C{((x1,y1), (x2,y2))}, then
1494 posargs will be C{[['x1','y1'], ['x2','y2']]}.
1495 @type: C{list}"""
1496 posarg_defaults = UNKNOWN
1497 """@ivar: API documentation for the positional arguments'
1498 default values. This list has the same length as C{posargs}, and
1499 each element of C{posarg_defaults} describes the corresponding
1500 argument in C{posargs}. For positional arguments with no default,
1501 C{posargs_defaults} will contain None.
1502 @type: C{list} of C{ValueDoc} or C{None}"""
1503 vararg = UNKNOWN
1504 """@ivar: The name of the routine's vararg argument, or C{None} if
1505 it has no vararg argument.
1506 @type: C{string} or C{None}"""
1507 kwarg = UNKNOWN
1508 """@ivar: The name of the routine's keyword argument, or C{None} if
1509 it has no keyword argument.
1510 @type: C{string} or C{None}"""
1511 lineno = UNKNOWN
1512 """@ivar: The line number of the first line of the function's
1513 signature. For Python functions, this is equal to
1514 C{func.func_code.co_firstlineno}. The first line of a file
1515 is considered line 1.
1516 @type: C{int}"""
1517
1518
1519
1520 decorators = UNKNOWN
1521 """@ivar: A list of names of decorators that were applied to this
1522 routine, in the order that they are listed in the source code.
1523 (I.e., in the reverse of the order that they were applied in.)
1524 @type: C{list} of C{string}"""
1525
1526
1527
1528 arg_descrs = UNKNOWN
1529 """@ivar: A list of descriptions of the routine's
1530 arguments. Each element of this list is a tuple C{(args,
1531 descr)}, where C{args} is a list of argument names; and
1532 C{descr} is a L{ParsedDocstring
1533 <epydoc.markup.ParsedDocstring>} describing the argument(s)
1534 specified by C{arg}.
1535 @type: C{list}"""
1536 arg_types = UNKNOWN
1537 """@ivar: Descriptions of the expected types for the
1538 routine's arguments, encoded as a dictionary mapping from
1539 argument names to type descriptions.
1540 @type: C{dict} from C{string} to L{ParsedDocstring
1541 <epydoc.markup.ParsedDocstring>}"""
1542 return_descr = UNKNOWN
1543 """@ivar: A description of the value returned by this routine.
1544 @type: L{ParsedDocstring<epydoc.markup.ParsedDocstring>}"""
1545 return_type = UNKNOWN
1546 """@ivar: A description of expected type for the value
1547 returned by this routine.
1548 @type: L{ParsedDocstring<epydoc.markup.ParsedDocstring>}"""
1549 exception_descrs = UNKNOWN
1550 """@ivar: A list of descriptions of exceptions
1551 that the routine might raise. Each element of this list is a
1552 tuple C{(exc, descr)}, where C{exc} is a string contianing the
1553 exception name; and C{descr} is a L{ParsedDocstring
1554 <epydoc.markup.ParsedDocstring>} describing the circumstances
1555 under which the exception specified by C{exc} is raised.
1556 @type: C{list}"""
1557
1558 callgraph_uid = None
1559 """@ivar: L{DotGraph}.uid of the call graph for the function.
1560 @type: C{str}"""
1561
1584
1601
1603 """
1604 Return a flattened version of C{lst}.
1605 """
1606 if out is None: out = []
1607 for elt in lst:
1608 if isinstance(elt, (list,tuple)):
1609 _flatten(elt, out)
1610 else:
1611 out.append(elt)
1612 return out
1613
1616
1618 """
1619 API documentation information about a single property.
1620 """
1621
1622 fget = UNKNOWN
1623 """@ivar: API documentation for the property's get function.
1624 @type: L{RoutineDoc}"""
1625 fset = UNKNOWN
1626 """@ivar: API documentation for the property's set function.
1627 @type: L{RoutineDoc}"""
1628 fdel = UNKNOWN
1629 """@ivar: API documentation for the property's delete function.
1630 @type: L{RoutineDoc}"""
1631
1632
1633 type_descr = UNKNOWN
1634 """@ivar: A description of the property's expected type, extracted
1635 from its docstring.
1636 @type: L{ParsedDocstring<epydoc.markup.ParsedDocstring>}"""
1637
1638
1640 val_docs = []
1641 if self.fget not in (None, UNKNOWN): val_docs.append(self.fget)
1642 if self.fset not in (None, UNKNOWN): val_docs.append(self.fset)
1643 if self.fdel not in (None, UNKNOWN): val_docs.append(self.fdel)
1644 return val_docs
1645
1658
1659
1660
1661
1662
1664 """
1665 [xx] out of date.
1666
1667 An index that .. hmm... it *can't* be used to access some things,
1668 cuz they're not at the root level. Do I want to add them or what?
1669 And if so, then I have a sort of a new top level. hmm.. so
1670 basically the question is what to do with a name that's not in the
1671 root var's name space. 2 types:
1672 - entirely outside (eg os.path)
1673 - inside but not known (eg a submodule that we didn't look at?)
1674 - container of current thing not examined?
1675
1676 An index of all the C{APIDoc} objects that can be reached from a
1677 root set of C{ValueDoc}s.
1678
1679 The members of this index can be accessed by dotted name. In
1680 particular, C{DocIndex} defines two mappings, accessed via the
1681 L{get_vardoc()} and L{get_valdoc()} methods, which can be used to
1682 access C{VariableDoc}s or C{ValueDoc}s respectively by name. (Two
1683 separate mappings are necessary because a single name can be used
1684 to refer to both a variable and to the value contained by that
1685 variable.)
1686
1687 Additionally, the index defines two sets of C{ValueDoc}s:
1688 \"reachable C{ValueDoc}s\" and \"contained C{ValueDoc}s\". The
1689 X{reachable C{ValueDoc}s} are defined as the set of all
1690 C{ValueDoc}s that can be reached from the root set by following
1691 I{any} sequence of pointers to C{ValueDoc}s or C{VariableDoc}s.
1692 The X{contained C{ValueDoc}s} are defined as the set of all
1693 C{ValueDoc}s that can be reached from the root set by following
1694 only the C{ValueDoc} pointers defined by non-imported
1695 C{VariableDoc}s. For example, if the root set contains a module
1696 C{m}, then the contained C{ValueDoc}s includes the C{ValueDoc}s
1697 for any functions, variables, or classes defined in that module,
1698 as well as methods and variables defined in classes defined in the
1699 module. The reachable C{ValueDoc}s includes all of those
1700 C{ValueDoc}s, as well as C{ValueDoc}s for any values imported into
1701 the module, and base classes for classes defined in the module.
1702 """
1703
1705 """
1706 Create a new documentation index, based on the given root set
1707 of C{ValueDoc}s. If any C{APIDoc}s reachable from the root
1708 set does not have a canonical name, then it will be assigned
1709 one. etc.
1710
1711 @param root: A list of C{ValueDoc}s.
1712 """
1713 for apidoc in root:
1714 if apidoc.canonical_name in (None, UNKNOWN):
1715 raise ValueError("All APIdocs passed to DocIndexer "
1716 "must already have canonical names.")
1717
1718
1719
1720
1721
1722
1723 self.root = sorted(root,
1724 key=lambda d: (len(d.canonical_name), d.canonical_name))
1725 """The list of C{ValueDoc}s to document.
1726 @type: C{list}"""
1727
1728
1729
1730
1731
1732 i = 1
1733 while i < len(self.root):
1734 if self.root[i-1] is self.root[i]:
1735 del self.root[i]
1736 else:
1737 i += 1
1738
1739 self.mlclasses = self._get_module_classes(self.root)
1740 """A mapping from class names to L{ClassDoc}. Contains
1741 classes defined at module level for modules in L{root}
1742 and which can be used as fallback by L{find()} if looking
1743 in containing namespaces fails.
1744 @type: C{dict} from C{str} to L{ClassDoc} or C{list}"""
1745
1746 self.callers = None
1747 """A dictionary mapping from C{RoutineDoc}s in this index
1748 to lists of C{RoutineDoc}s for the routine's callers.
1749 This dictionary is initialized by calling
1750 L{read_profiling_info()}.
1751 @type: C{list} of L{RoutineDoc}"""
1752
1753 self.callees = None
1754 """A dictionary mapping from C{RoutineDoc}s in this index
1755 to lists of C{RoutineDoc}s for the routine's callees.
1756 This dictionary is initialized by calling
1757 L{read_profiling_info()}.
1758 @type: C{list} of L{RoutineDoc}"""
1759
1760 self._funcid_to_doc = {}
1761 """A mapping from C{profile} function ids to corresponding
1762 C{APIDoc} objects. A function id is a tuple of the form
1763 C{(filename, lineno, funcname)}. This is used to update
1764 the L{callers} and L{callees} variables."""
1765
1766 self._container_cache = {}
1767 """A cache for the L{container()} method, to increase speed."""
1768
1769 self._get_cache = {}
1770 """A cache for the L{get_vardoc()} and L{get_valdoc()} methods,
1771 to increase speed."""
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1784 """
1785 Return the C{VariableDoc} with the given name, or C{None} if this
1786 index does not contain a C{VariableDoc} with the given name.
1787 """
1788 var, val = self._get(name)
1789 return var
1790
1792 """
1793 Return the C{ValueDoc} with the given name, or C{None} if this
1794 index does not contain a C{ValueDoc} with the given name.
1795 """
1796 var, val = self._get(name)
1797 return val
1798
1799 - def _get(self, name):
1800 """
1801 A helper function that's used to implement L{get_vardoc()}
1802 and L{get_valdoc()}.
1803 """
1804
1805 if not isinstance(name, DottedName):
1806 name = DottedName(name)
1807
1808
1809 val = self._get_cache.get(name)
1810 if val is not None: return val
1811
1812
1813
1814 for root_valdoc in self.root:
1815 if root_valdoc.canonical_name.dominates(name):
1816
1817
1818 var_doc = None
1819 val_doc = root_valdoc
1820 for identifier in name[len(root_valdoc.canonical_name):]:
1821 if val_doc is None: break
1822 var_doc, val_doc = self._get_from(val_doc, identifier)
1823 else:
1824
1825 if var_doc is not None or val_doc is not None:
1826 self._get_cache[name] = (var_doc, val_doc)
1827 return var_doc, val_doc
1828
1829
1830 self._get_cache[name] = (None, None)
1831 return None, None
1832
1834 if isinstance(val_doc, NamespaceDoc):
1835 child_var = val_doc.variables.get(identifier)
1836 if child_var is not None:
1837 child_val = child_var.value
1838 if child_val is UNKNOWN: child_val = None
1839 return child_var, child_val
1840
1841
1842 if (isinstance(val_doc, ModuleDoc) and
1843 val_doc.submodules is not UNKNOWN):
1844 for submodule in val_doc.submodules:
1845 if submodule.canonical_name[-1] == identifier:
1846 var_doc = None
1847 val_doc = submodule
1848 if val_doc is UNKNOWN: val_doc = None
1849 return var_doc, val_doc
1850
1851 return None, None
1852
1853 - def find(self, name, context):
1854 """
1855 Look for an C{APIDoc} named C{name}, relative to C{context}.
1856 Return the C{APIDoc} if one is found; otherwise, return
1857 C{None}. C{find} looks in the following places, in order:
1858 - Function parameters (if one matches, return C{None})
1859 - All enclosing namespaces, from closest to furthest.
1860 - If C{name} starts with C{'self'}, then strip it off and
1861 look for the remaining part of the name using C{find}
1862 - Builtins
1863 - Parameter attributes
1864 - Classes at module level (if the name is not ambiguous)
1865
1866 @type name: C{str} or L{DottedName}
1867 @type context: L{APIDoc}
1868 """
1869 if isinstance(name, basestring):
1870 name = re.sub(r'\(.*\)$', '', name.strip())
1871 if re.match('^([a-zA-Z_]\w*)(\.[a-zA-Z_]\w*)*$', name):
1872 name = DottedName(name)
1873 else:
1874 return None
1875 elif not isinstance(name, DottedName):
1876 raise TypeError("'name' should be a string or DottedName")
1877
1878 if context is None or context.canonical_name is None:
1879 container_name = []
1880 else:
1881 container_name = context.canonical_name
1882
1883
1884
1885 for i in range(len(container_name), -1, -1):
1886 relative_name = container_name[:i]+name
1887
1888
1889 val_doc = self.get_valdoc(relative_name)
1890 if (val_doc is not None and
1891 not isinstance(val_doc, GenericValueDoc)):
1892 return val_doc
1893
1894 var_doc = self.get_vardoc(relative_name)
1895 if var_doc is not None: return var_doc
1896
1897
1898
1899 if name[0] == 'self':
1900 doc = self.find('.'.join(name[1:]), context)
1901 if doc is not None: return doc
1902
1903
1904 if len(name)==1 and hasattr(__builtin__, name[0]):
1905 return None
1906
1907
1908 if isinstance(context, RoutineDoc):
1909 all_args = context.all_args()
1910 if all_args is not UNKNOWN and name[0] in all_args:
1911 return None
1912
1913
1914 doc = self.mlclasses.get(name[-1])
1915 if isinstance(doc, APIDoc):
1916 return doc
1917 elif isinstance(doc, list):
1918 log.warning("%s is an ambiguous name: it may be %s" % (
1919 name[-1],
1920 ", ".join([ "'%s'" % d.canonical_name for d in doc ])))
1921
1922
1923
1924 del self.mlclasses[name[-1]]
1925
1927 """
1928 Gather all the classes defined in a list of modules.
1929
1930 Very often people refers to classes only by class name,
1931 even if they are not imported in the namespace. Linking
1932 to such classes will fail if we look for them only in nested
1933 namespaces. Allow them to retrieve only by name.
1934
1935 @param docs: containers of the objects to collect
1936 @type docs: C{list} of C{APIDoc}
1937 @return: mapping from objects name to the object(s) with that name
1938 @rtype: C{dict} from C{str} to L{ClassDoc} or C{list}
1939 """
1940 classes = {}
1941 for doc in docs:
1942 if not isinstance(doc, ModuleDoc):
1943 continue
1944
1945 for var in doc.variables.values():
1946 if not isinstance(var.value, ClassDoc):
1947 continue
1948
1949 val = var.value
1950 if val in (None, UNKNOWN) or val.defining_module is not doc:
1951 continue
1952 if val.canonical_name in (None, UNKNOWN):
1953 continue
1954
1955 name = val.canonical_name[-1]
1956 vals = classes.get(name)
1957 if vals is None:
1958 classes[name] = val
1959 elif not isinstance(vals, list):
1960 classes[name] = [ vals, val ]
1961 else:
1962 vals.append(val)
1963
1964 return classes
1965
1966
1967
1968
1969
1971 """
1972 Return a list of all C{ValueDoc}s that can be reached,
1973 directly or indirectly from this C{DocIndex}'s root set.
1974
1975 @param filters: A set of filters that can be used to prevent
1976 C{reachable_valdocs} from following specific link types
1977 when looking for C{ValueDoc}s that can be reached from the
1978 root set. See C{APIDoc.apidoc_links} for a more complete
1979 description.
1980 """
1981 return reachable_valdocs(self.root, **filters)
1982
1984 """
1985 Return the C{ValueDoc} that contains the given C{APIDoc}, or
1986 C{None} if its container is not in the index.
1987 """
1988
1989 val = self._container_cache.get(api_doc)
1990 if val is not None: return val
1991
1992 if isinstance(api_doc, GenericValueDoc):
1993 self._container_cache[api_doc] = None
1994 return None
1995 if isinstance(api_doc, VariableDoc):
1996 self._container_cache[api_doc] = api_doc.container
1997 return api_doc.container
1998 if len(api_doc.canonical_name) == 1:
1999 self._container_cache[api_doc] = None
2000 return None
2001 elif isinstance(api_doc, ModuleDoc) and api_doc.package is not UNKNOWN:
2002 self._container_cache[api_doc] = api_doc.package
2003 return api_doc.package
2004 else:
2005 parent = self.get_valdoc(api_doc.canonical_name.container())
2006 self._container_cache[api_doc] = parent
2007 return parent
2008
2009
2010
2011
2012
2014 """
2015 Initialize the L{callers} and L{callees} variables, given a
2016 C{Stat} object from the C{pstats} module.
2017
2018 @warning: This method uses undocumented data structures inside
2019 of C{profile_stats}.
2020 """
2021 if self.callers is None: self.callers = {}
2022 if self.callees is None: self.callees = {}
2023
2024
2025
2026
2027 self._update_funcid_to_doc(profile_stats)
2028
2029 for callee, (cc, nc, tt, ct, callers) in profile_stats.stats.items():
2030 callee = self._funcid_to_doc.get(callee)
2031 if callee is None: continue
2032 for caller in callers:
2033 caller = self._funcid_to_doc.get(caller)
2034 if caller is None: continue
2035 self.callers.setdefault(callee, []).append(caller)
2036 self.callees.setdefault(caller, []).append(callee)
2037
2059
2060
2061
2062
2063
2064 -def pp_apidoc(api_doc, doublespace=0, depth=5, exclude=(), include=(),
2065 backpointers=None):
2066 """
2067 @return: A multiline pretty-printed string representation for the
2068 given C{APIDoc}.
2069 @param doublespace: If true, then extra lines will be
2070 inserted to make the output more readable.
2071 @param depth: The maximum depth that pp_apidoc will descend
2072 into descendent VarDocs. To put no limit on
2073 depth, use C{depth=-1}.
2074 @param exclude: A list of names of attributes whose values should
2075 not be shown.
2076 @param backpointers: For internal use.
2077 """
2078 pyid = id(api_doc.__dict__)
2079 if backpointers is None: backpointers = {}
2080 if (hasattr(api_doc, 'canonical_name') and
2081 api_doc.canonical_name not in (None, UNKNOWN)):
2082 name = '%s for %s' % (api_doc.__class__.__name__,
2083 api_doc.canonical_name)
2084 elif getattr(api_doc, 'name', None) not in (UNKNOWN, None):
2085 if (getattr(api_doc, 'container', None) not in (UNKNOWN, None) and
2086 getattr(api_doc.container, 'canonical_name', None)
2087 not in (UNKNOWN, None)):
2088 name ='%s for %s' % (api_doc.__class__.__name__,
2089 api_doc.container.canonical_name+
2090 api_doc.name)
2091 else:
2092 name = '%s for %s' % (api_doc.__class__.__name__, api_doc.name)
2093 else:
2094 name = api_doc.__class__.__name__
2095
2096 if pyid in backpointers:
2097 return '%s [%s] (defined above)' % (name, backpointers[pyid])
2098
2099 if depth == 0:
2100 if hasattr(api_doc, 'name') and api_doc.name is not None:
2101 return '%s...' % api_doc.name
2102 else:
2103 return '...'
2104
2105 backpointers[pyid] = len(backpointers)
2106 s = '%s [%s]' % (name, backpointers[pyid])
2107
2108
2109 fields = [field for field in api_doc.__dict__.keys()
2110 if (field in include or
2111 (getattr(api_doc, field) is not UNKNOWN
2112 and field not in exclude))]
2113 if include:
2114 fields = [field for field in dir(api_doc)
2115 if field in include]
2116 else:
2117 fields = [field for field in api_doc.__dict__.keys()
2118 if (getattr(api_doc, field) is not UNKNOWN
2119 and field not in exclude)]
2120 fields.sort()
2121
2122 for field in fields:
2123 fieldval = getattr(api_doc, field)
2124 if doublespace: s += '\n |'
2125 s += '\n +- %s' % field
2126
2127 if (isinstance(fieldval, types.ListType) and
2128 len(fieldval)>0 and
2129 isinstance(fieldval[0], APIDoc)):
2130 s += _pp_list(api_doc, fieldval, doublespace, depth,
2131 exclude, include, backpointers,
2132 (field is fields[-1]))
2133 elif (isinstance(fieldval, types.DictType) and
2134 len(fieldval)>0 and
2135 isinstance(fieldval.values()[0], APIDoc)):
2136 s += _pp_dict(api_doc, fieldval, doublespace,
2137 depth, exclude, include, backpointers,
2138 (field is fields[-1]))
2139 elif isinstance(fieldval, APIDoc):
2140 s += _pp_apidoc(api_doc, fieldval, doublespace, depth,
2141 exclude, include, backpointers,
2142 (field is fields[-1]))
2143 else:
2144 s += ' = ' + _pp_val(api_doc, fieldval, doublespace,
2145 depth, exclude, include, backpointers)
2146
2147 return s
2148
2149 -def _pp_list(api_doc, items, doublespace, depth, exclude, include,
2150 backpointers, is_last):
2151 line1 = (is_last and ' ') or '|'
2152 s = ''
2153 for item in items:
2154 line2 = ((item is items[-1]) and ' ') or '|'
2155 joiner = '\n %s %s ' % (line1, line2)
2156 if doublespace: s += '\n %s |' % line1
2157 s += '\n %s +- ' % line1
2158 valstr = _pp_val(api_doc, item, doublespace, depth, exclude, include,
2159 backpointers)
2160 s += joiner.join(valstr.split('\n'))
2161 return s
2162
2163 -def _pp_dict(api_doc, dict, doublespace, depth, exclude, include,
2164 backpointers, is_last):
2165 items = dict.items()
2166 items.sort()
2167 line1 = (is_last and ' ') or '|'
2168 s = ''
2169 for item in items:
2170 line2 = ((item is items[-1]) and ' ') or '|'
2171 joiner = '\n %s %s ' % (line1, line2)
2172 if doublespace: s += '\n %s |' % line1
2173 s += '\n %s +- ' % line1
2174 valstr = _pp_val(api_doc, item[1], doublespace, depth, exclude,
2175 include, backpointers)
2176 s += joiner.join(('%s => %s' % (item[0], valstr)).split('\n'))
2177 return s
2178
2179 -def _pp_apidoc(api_doc, val, doublespace, depth, exclude, include,
2180 backpointers, is_last):
2181 line1 = (is_last and ' ') or '|'
2182 s = ''
2183 if doublespace: s += '\n %s | ' % line1
2184 s += '\n %s +- ' % line1
2185 joiner = '\n %s ' % line1
2186 childstr = pp_apidoc(val, doublespace, depth-1, exclude,
2187 include, backpointers)
2188 return s + joiner.join(childstr.split('\n'))
2189
2190 -def _pp_val(api_doc, val, doublespace, depth, exclude, include, backpointers):
2191 from epydoc import markup
2192 if isinstance(val, APIDoc):
2193 return pp_apidoc(val, doublespace, depth-1, exclude,
2194 include, backpointers)
2195 elif isinstance(val, markup.ParsedDocstring):
2196 valrepr = `val.to_plaintext(None)`
2197 if len(valrepr) < 40: return valrepr
2198 else: return valrepr[:37]+'...'
2199 else:
2200 valrepr = repr(val)
2201 if len(valrepr) < 40: return valrepr
2202 else: return valrepr[:37]+'...'
2203