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 hash 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 elif elt_name not in set(idents):
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
1261 metaclass = UNKNOWN
1262
1263
1273
1281
1289
1297
1298 - def mro(self, warn_about_bad_bases=False):
1299 if self.is_newstyle_class():
1300 try:
1301 return self._c3_mro(warn_about_bad_bases)
1302 except ValueError, e:
1303 log.error('Error finding mro for %s: %s' %
1304 (self.canonical_name, e))
1305
1306 return self._dfs_bases([], set(), warn_about_bad_bases)
1307 else:
1308 return self._dfs_bases([], set(), warn_about_bad_bases)
1309
1310 - def _dfs_bases(self, mro, seen, warn_about_bad_bases):
1321
1322 - def _c3_mro(self, warn_about_bad_bases):
1323 """
1324 Compute the class precedence list (mro) according to C3.
1325 @seealso: U{http://www.python.org/2.3/mro.html}
1326 """
1327 bases = [base for base in self.bases if isinstance(base, ClassDoc)]
1328 if len(bases) != len(self.bases) and warn_about_bad_bases:
1329 for base in self.bases:
1330 if (not isinstance(base, ClassDoc) or
1331 base.proxy_for is not None):
1332 self._report_bad_base(base)
1333 w = [warn_about_bad_bases]*len(bases)
1334 return self._c3_merge([[self]] + map(ClassDoc._c3_mro, bases, w) +
1335 [list(bases)])
1336
1350
1352 """
1353 Helper function for L{_c3_mro}.
1354 """
1355 res = []
1356 while 1:
1357 nonemptyseqs=[seq for seq in seqs if seq]
1358 if not nonemptyseqs: return res
1359 for seq in nonemptyseqs:
1360 cand = seq[0]
1361 nothead=[s for s in nonemptyseqs if cand in s[1:]]
1362 if nothead: cand=None
1363 else: break
1364 if not cand: raise ValueError("Inconsistent hierarchy")
1365 res.append(cand)
1366 for seq in nonemptyseqs:
1367 if seq[0] == cand: del seq[0]
1368
1369 - def select_variables(self, group=None, value_type=None, inherited=None,
1370 public=None, imported=None, detailed=None):
1371 """
1372 Return a specified subset of this class's L{sorted_variables}
1373 list. If C{value_type} is given, then only return variables
1374 whose values have the specified type. If C{group} is given,
1375 then only return variables that belong to the specified group.
1376 If C{inherited} is True, then only return inherited variables;
1377 if C{inherited} is False, then only return local variables.
1378
1379 @require: The L{sorted_variables} and L{variable_groups}
1380 attributes must be initialized before this method can be
1381 used. See L{init_sorted_variables()} and
1382 L{init_variable_groups()}.
1383
1384 @param value_type: A string specifying the value type for
1385 which variables should be returned. Valid values are:
1386 - 'instancemethod' - variables whose values are
1387 instance methods.
1388 - 'classmethod' - variables whose values are class
1389 methods.
1390 - 'staticmethod' - variables whose values are static
1391 methods.
1392 - 'properties' - variables whose values are properties.
1393 - 'class' - variables whose values are nested classes
1394 (including exceptions and types).
1395 - 'instancevariable' - instance variables. This includes
1396 any variables that are explicitly marked as instance
1397 variables with docstring fields; and variables with
1398 docstrings that are initialized in the constructor.
1399 - 'classvariable' - class variables. This includes any
1400 variables that are not included in any of the above
1401 categories.
1402 @type value_type: C{string}
1403
1404 @param group: The name of the group for which variables should
1405 be returned. A complete list of the groups defined by
1406 this C{ClassDoc} is available in the L{group_names}
1407 instance variable. The first element of this list is
1408 always the special group name C{''}, which is used for
1409 variables that do not belong to any group.
1410 @type group: C{string}
1411
1412 @param inherited: If C{None}, then return both inherited and
1413 local variables; if C{True}, then return only inherited
1414 variables; if C{False}, then return only local variables.
1415
1416 @param detailed: If True (False), return only the variables
1417 deserving (not deserving) a detailed informative box.
1418 If C{None}, don't care.
1419 @type detailed: C{bool}
1420 """
1421 if (self.sorted_variables is UNKNOWN or
1422 self.variable_groups is UNKNOWN):
1423 raise ValueError('sorted_variables and variable_groups '
1424 'must be initialized first.')
1425
1426 if group is None: var_list = self.sorted_variables
1427 else: var_list = self.variable_groups[group]
1428
1429
1430 if public is True:
1431 var_list = [v for v in var_list if v.is_public is not False]
1432 elif public is False:
1433 var_list = [v for v in var_list if v.is_public is False]
1434
1435
1436 if inherited is None: pass
1437 elif inherited:
1438 var_list = [v for v in var_list if v.container != self]
1439 else:
1440 var_list = [v for v in var_list if v.container == self ]
1441
1442
1443 if imported is True:
1444 var_list = [v for v in var_list if v.is_imported is True]
1445 elif imported is False:
1446 var_list = [v for v in var_list if v.is_imported is not True]
1447
1448
1449 if detailed is True:
1450 var_list = [v for v in var_list if v.is_detailed() is True]
1451 elif detailed is False:
1452 var_list = [v for v in var_list if v.is_detailed() is not True]
1453
1454 if value_type is None:
1455 return var_list
1456 elif value_type == 'method':
1457 return [var_doc for var_doc in var_list
1458 if (isinstance(var_doc.value, RoutineDoc) and
1459 var_doc.is_instvar in (False, UNKNOWN))]
1460 elif value_type == 'instancemethod':
1461 return [var_doc for var_doc in var_list
1462 if (isinstance(var_doc.value, RoutineDoc) and
1463 not isinstance(var_doc.value, ClassMethodDoc) and
1464 not isinstance(var_doc.value, StaticMethodDoc) and
1465 var_doc.is_instvar in (False, UNKNOWN))]
1466 elif value_type == 'classmethod':
1467 return [var_doc for var_doc in var_list
1468 if (isinstance(var_doc.value, ClassMethodDoc) and
1469 var_doc.is_instvar in (False, UNKNOWN))]
1470 elif value_type == 'staticmethod':
1471 return [var_doc for var_doc in var_list
1472 if (isinstance(var_doc.value, StaticMethodDoc) and
1473 var_doc.is_instvar in (False, UNKNOWN))]
1474 elif value_type == 'property':
1475 return [var_doc for var_doc in var_list
1476 if (isinstance(var_doc.value, PropertyDoc) and
1477 var_doc.is_instvar in (False, UNKNOWN))]
1478 elif value_type == 'class':
1479 return [var_doc for var_doc in var_list
1480 if (isinstance(var_doc.value, ClassDoc) and
1481 var_doc.is_instvar in (False, UNKNOWN))]
1482 elif value_type == 'instancevariable':
1483 return [var_doc for var_doc in var_list
1484 if var_doc.is_instvar is True]
1485 elif value_type == 'classvariable':
1486 return [var_doc for var_doc in var_list
1487 if (var_doc.is_instvar in (False, UNKNOWN) and
1488 not isinstance(var_doc.value,
1489 (RoutineDoc, ClassDoc, PropertyDoc)))]
1490 else:
1491 raise ValueError('Bad value type %r' % value_type)
1492
1494 """
1495 API documentation information about a single routine.
1496 """
1497
1498 posargs = UNKNOWN
1499 """@ivar: The names of the routine's positional arguments.
1500 If an argument list contains \"unpacking\" arguments, then
1501 their names will be specified using nested lists. E.g., if
1502 a function's argument list is C{((x1,y1), (x2,y2))}, then
1503 posargs will be C{[['x1','y1'], ['x2','y2']]}.
1504 @type: C{list}"""
1505 posarg_defaults = UNKNOWN
1506 """@ivar: API documentation for the positional arguments'
1507 default values. This list has the same length as C{posargs}, and
1508 each element of C{posarg_defaults} describes the corresponding
1509 argument in C{posargs}. For positional arguments with no default,
1510 C{posargs_defaults} will contain None.
1511 @type: C{list} of C{ValueDoc} or C{None}"""
1512 vararg = UNKNOWN
1513 """@ivar: The name of the routine's vararg argument, or C{None} if
1514 it has no vararg argument.
1515 @type: C{string} or C{None}"""
1516 kwarg = UNKNOWN
1517 """@ivar: The name of the routine's keyword argument, or C{None} if
1518 it has no keyword argument.
1519 @type: C{string} or C{None}"""
1520 lineno = UNKNOWN
1521 """@ivar: The line number of the first line of the function's
1522 signature. For Python functions, this is equal to
1523 C{func.func_code.co_firstlineno}. The first line of a file
1524 is considered line 1.
1525 @type: C{int}"""
1526
1527
1528
1529 decorators = UNKNOWN
1530 """@ivar: A list of names of decorators that were applied to this
1531 routine, in the order that they are listed in the source code.
1532 (I.e., in the reverse of the order that they were applied in.)
1533 @type: C{list} of C{string}"""
1534
1535
1536
1537 arg_descrs = UNKNOWN
1538 """@ivar: A list of descriptions of the routine's
1539 arguments. Each element of this list is a tuple C{(args,
1540 descr)}, where C{args} is a list of argument names; and
1541 C{descr} is a L{ParsedDocstring
1542 <epydoc.markup.ParsedDocstring>} describing the argument(s)
1543 specified by C{arg}.
1544 @type: C{list}"""
1545 arg_types = UNKNOWN
1546 """@ivar: Descriptions of the expected types for the
1547 routine's arguments, encoded as a dictionary mapping from
1548 argument names to type descriptions.
1549 @type: C{dict} from C{string} to L{ParsedDocstring
1550 <epydoc.markup.ParsedDocstring>}"""
1551 return_descr = UNKNOWN
1552 """@ivar: A description of the value returned by this routine.
1553 @type: L{ParsedDocstring<epydoc.markup.ParsedDocstring>}"""
1554 return_type = UNKNOWN
1555 """@ivar: A description of expected type for the value
1556 returned by this routine.
1557 @type: L{ParsedDocstring<epydoc.markup.ParsedDocstring>}"""
1558 exception_descrs = UNKNOWN
1559 """@ivar: A list of descriptions of exceptions
1560 that the routine might raise. Each element of this list is a
1561 tuple C{(exc, descr)}, where C{exc} is a string contianing the
1562 exception name; and C{descr} is a L{ParsedDocstring
1563 <epydoc.markup.ParsedDocstring>} describing the circumstances
1564 under which the exception specified by C{exc} is raised.
1565 @type: C{list}"""
1566
1567 callgraph_uid = None
1568 """@ivar: L{DotGraph}.uid of the call graph for the function.
1569 @type: C{str}"""
1570
1593
1610
1612 """
1613 Return a flattened version of C{lst}.
1614 """
1615 if out is None: out = []
1616 for elt in lst:
1617 if isinstance(elt, (list,tuple)):
1618 _flatten(elt, out)
1619 else:
1620 out.append(elt)
1621 return out
1622
1625
1627 """
1628 API documentation information about a single property.
1629 """
1630
1631 fget = UNKNOWN
1632 """@ivar: API documentation for the property's get function.
1633 @type: L{RoutineDoc}"""
1634 fset = UNKNOWN
1635 """@ivar: API documentation for the property's set function.
1636 @type: L{RoutineDoc}"""
1637 fdel = UNKNOWN
1638 """@ivar: API documentation for the property's delete function.
1639 @type: L{RoutineDoc}"""
1640
1641
1642 type_descr = UNKNOWN
1643 """@ivar: A description of the property's expected type, extracted
1644 from its docstring.
1645 @type: L{ParsedDocstring<epydoc.markup.ParsedDocstring>}"""
1646
1647
1649 val_docs = []
1650 if self.fget not in (None, UNKNOWN): val_docs.append(self.fget)
1651 if self.fset not in (None, UNKNOWN): val_docs.append(self.fset)
1652 if self.fdel not in (None, UNKNOWN): val_docs.append(self.fdel)
1653 return val_docs
1654
1667
1668
1669
1670
1671
1673 """
1674 [xx] out of date.
1675
1676 An index that .. hmm... it *can't* be used to access some things,
1677 cuz they're not at the root level. Do I want to add them or what?
1678 And if so, then I have a sort of a new top level. hmm.. so
1679 basically the question is what to do with a name that's not in the
1680 root var's name space. 2 types:
1681 - entirely outside (eg os.path)
1682 - inside but not known (eg a submodule that we didn't look at?)
1683 - container of current thing not examined?
1684
1685 An index of all the C{APIDoc} objects that can be reached from a
1686 root set of C{ValueDoc}s.
1687
1688 The members of this index can be accessed by dotted name. In
1689 particular, C{DocIndex} defines two mappings, accessed via the
1690 L{get_vardoc()} and L{get_valdoc()} methods, which can be used to
1691 access C{VariableDoc}s or C{ValueDoc}s respectively by name. (Two
1692 separate mappings are necessary because a single name can be used
1693 to refer to both a variable and to the value contained by that
1694 variable.)
1695
1696 Additionally, the index defines two sets of C{ValueDoc}s:
1697 \"reachable C{ValueDoc}s\" and \"contained C{ValueDoc}s\". The
1698 X{reachable C{ValueDoc}s} are defined as the set of all
1699 C{ValueDoc}s that can be reached from the root set by following
1700 I{any} sequence of pointers to C{ValueDoc}s or C{VariableDoc}s.
1701 The X{contained C{ValueDoc}s} are defined as the set of all
1702 C{ValueDoc}s that can be reached from the root set by following
1703 only the C{ValueDoc} pointers defined by non-imported
1704 C{VariableDoc}s. For example, if the root set contains a module
1705 C{m}, then the contained C{ValueDoc}s includes the C{ValueDoc}s
1706 for any functions, variables, or classes defined in that module,
1707 as well as methods and variables defined in classes defined in the
1708 module. The reachable C{ValueDoc}s includes all of those
1709 C{ValueDoc}s, as well as C{ValueDoc}s for any values imported into
1710 the module, and base classes for classes defined in the module.
1711 """
1712
1714 """
1715 Create a new documentation index, based on the given root set
1716 of C{ValueDoc}s. If any C{APIDoc}s reachable from the root
1717 set does not have a canonical name, then it will be assigned
1718 one. etc.
1719
1720 @param root: A list of C{ValueDoc}s.
1721 """
1722 for apidoc in root:
1723 if apidoc.canonical_name in (None, UNKNOWN):
1724 raise ValueError("All APIdocs passed to DocIndexer "
1725 "must already have canonical names.")
1726
1727
1728
1729
1730
1731
1732 self.root = sorted(root,
1733 key=lambda d: (len(d.canonical_name), d.canonical_name))
1734 """The list of C{ValueDoc}s to document.
1735 @type: C{list}"""
1736
1737
1738
1739
1740
1741 i = 1
1742 while i < len(self.root):
1743 if self.root[i-1] is self.root[i]:
1744 del self.root[i]
1745 else:
1746 i += 1
1747
1748 self.mlclasses = self._get_module_classes(self.root)
1749 """A mapping from class names to L{ClassDoc}. Contains
1750 classes defined at module level for modules in L{root}
1751 and which can be used as fallback by L{find()} if looking
1752 in containing namespaces fails.
1753 @type: C{dict} from C{str} to L{ClassDoc} or C{list}"""
1754
1755 self.callers = None
1756 """A dictionary mapping from C{RoutineDoc}s in this index
1757 to lists of C{RoutineDoc}s for the routine's callers.
1758 This dictionary is initialized by calling
1759 L{read_profiling_info()}.
1760 @type: C{list} of L{RoutineDoc}"""
1761
1762 self.callees = None
1763 """A dictionary mapping from C{RoutineDoc}s in this index
1764 to lists of C{RoutineDoc}s for the routine's callees.
1765 This dictionary is initialized by calling
1766 L{read_profiling_info()}.
1767 @type: C{list} of L{RoutineDoc}"""
1768
1769 self._funcid_to_doc = {}
1770 """A mapping from C{profile} function ids to corresponding
1771 C{APIDoc} objects. A function id is a tuple of the form
1772 C{(filename, lineno, funcname)}. This is used to update
1773 the L{callers} and L{callees} variables."""
1774
1775 self._container_cache = {}
1776 """A cache for the L{container()} method, to increase speed."""
1777
1778 self._get_cache = {}
1779 """A cache for the L{get_vardoc()} and L{get_valdoc()} methods,
1780 to increase speed."""
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1793 """
1794 Return the C{VariableDoc} with the given name, or C{None} if this
1795 index does not contain a C{VariableDoc} with the given name.
1796 """
1797 var, val = self._get(name)
1798 return var
1799
1801 """
1802 Return the C{ValueDoc} with the given name, or C{None} if this
1803 index does not contain a C{ValueDoc} with the given name.
1804 """
1805 var, val = self._get(name)
1806 return val
1807
1808 - def _get(self, name):
1809 """
1810 A helper function that's used to implement L{get_vardoc()}
1811 and L{get_valdoc()}.
1812 """
1813
1814 if not isinstance(name, DottedName):
1815 name = DottedName(name)
1816
1817
1818 val = self._get_cache.get(name)
1819 if val is not None: return val
1820
1821
1822
1823 for root_valdoc in self.root:
1824 if root_valdoc.canonical_name.dominates(name):
1825
1826
1827 var_doc = None
1828 val_doc = root_valdoc
1829 for identifier in name[len(root_valdoc.canonical_name):]:
1830 if val_doc is None: break
1831 var_doc, val_doc = self._get_from(val_doc, identifier)
1832 else:
1833
1834 if var_doc is not None or val_doc is not None:
1835 self._get_cache[name] = (var_doc, val_doc)
1836 return var_doc, val_doc
1837
1838
1839 self._get_cache[name] = (None, None)
1840 return None, None
1841
1843 if isinstance(val_doc, NamespaceDoc):
1844 child_var = val_doc.variables.get(identifier)
1845 if child_var is not None:
1846 child_val = child_var.value
1847 if child_val is UNKNOWN: child_val = None
1848 return child_var, child_val
1849
1850
1851 if (isinstance(val_doc, ModuleDoc) and
1852 val_doc.submodules is not UNKNOWN):
1853 for submodule in val_doc.submodules:
1854 if submodule.canonical_name[-1] == identifier:
1855 var_doc = None
1856 val_doc = submodule
1857 if val_doc is UNKNOWN: val_doc = None
1858 return var_doc, val_doc
1859
1860 return None, None
1861
1862 - def find(self, name, context):
1863 """
1864 Look for an C{APIDoc} named C{name}, relative to C{context}.
1865 Return the C{APIDoc} if one is found; otherwise, return
1866 C{None}. C{find} looks in the following places, in order:
1867 - Function parameters (if one matches, return C{None})
1868 - All enclosing namespaces, from closest to furthest.
1869 - If C{name} starts with C{'self'}, then strip it off and
1870 look for the remaining part of the name using C{find}
1871 - Builtins
1872 - Parameter attributes
1873 - Classes at module level (if the name is not ambiguous)
1874
1875 @type name: C{str} or L{DottedName}
1876 @type context: L{APIDoc}
1877 """
1878 if isinstance(name, basestring):
1879 name = re.sub(r'\(.*\)$', '', name.strip())
1880 if re.match('^([a-zA-Z_]\w*)(\.[a-zA-Z_]\w*)*$', name):
1881 name = DottedName(name)
1882 else:
1883 return None
1884 elif not isinstance(name, DottedName):
1885 raise TypeError("'name' should be a string or DottedName")
1886
1887 if context is None or context.canonical_name is None:
1888 container_name = []
1889 else:
1890 container_name = context.canonical_name
1891
1892
1893
1894 for i in range(len(container_name), -1, -1):
1895 relative_name = container_name[:i]+name
1896
1897
1898 val_doc = self.get_valdoc(relative_name)
1899 if (val_doc is not None and
1900 not isinstance(val_doc, GenericValueDoc)):
1901 return val_doc
1902
1903 var_doc = self.get_vardoc(relative_name)
1904 if var_doc is not None: return var_doc
1905
1906
1907
1908 if name[0] == 'self':
1909 doc = self.find('.'.join(name[1:]), context)
1910 if doc is not None: return doc
1911
1912
1913 if len(name)==1 and hasattr(__builtin__, name[0]):
1914 return None
1915
1916
1917 if isinstance(context, RoutineDoc):
1918 all_args = context.all_args()
1919 if all_args is not UNKNOWN and name[0] in all_args:
1920 return None
1921
1922
1923 doc = self.mlclasses.get(name[-1])
1924 if isinstance(doc, APIDoc):
1925 return doc
1926 elif isinstance(doc, list):
1927 log.warning("%s is an ambiguous name: it may be %s" % (
1928 name[-1],
1929 ", ".join([ "'%s'" % d.canonical_name for d in doc ])))
1930
1931
1932
1933 del self.mlclasses[name[-1]]
1934
1936 """
1937 Gather all the classes defined in a list of modules.
1938
1939 Very often people refers to classes only by class name,
1940 even if they are not imported in the namespace. Linking
1941 to such classes will fail if we look for them only in nested
1942 namespaces. Allow them to retrieve only by name.
1943
1944 @param docs: containers of the objects to collect
1945 @type docs: C{list} of C{APIDoc}
1946 @return: mapping from objects name to the object(s) with that name
1947 @rtype: C{dict} from C{str} to L{ClassDoc} or C{list}
1948 """
1949 classes = {}
1950 for doc in docs:
1951 if not isinstance(doc, ModuleDoc):
1952 continue
1953
1954 for var in doc.variables.values():
1955 if not isinstance(var.value, ClassDoc):
1956 continue
1957
1958 val = var.value
1959 if val in (None, UNKNOWN) or val.defining_module is not doc:
1960 continue
1961 if val.canonical_name in (None, UNKNOWN):
1962 continue
1963
1964 name = val.canonical_name[-1]
1965 vals = classes.get(name)
1966 if vals is None:
1967 classes[name] = val
1968 elif not isinstance(vals, list):
1969 classes[name] = [ vals, val ]
1970 else:
1971 vals.append(val)
1972
1973 return classes
1974
1975
1976
1977
1978
1980 """
1981 Return a list of all C{ValueDoc}s that can be reached,
1982 directly or indirectly from this C{DocIndex}'s root set.
1983
1984 @param filters: A set of filters that can be used to prevent
1985 C{reachable_valdocs} from following specific link types
1986 when looking for C{ValueDoc}s that can be reached from the
1987 root set. See C{APIDoc.apidoc_links} for a more complete
1988 description.
1989 """
1990 return reachable_valdocs(self.root, **filters)
1991
1993 """
1994 Return the C{ValueDoc} that contains the given C{APIDoc}, or
1995 C{None} if its container is not in the index.
1996 """
1997
1998 val = self._container_cache.get(api_doc)
1999 if val is not None: return val
2000
2001 if isinstance(api_doc, GenericValueDoc):
2002 self._container_cache[api_doc] = None
2003 return None
2004 if isinstance(api_doc, VariableDoc):
2005 self._container_cache[api_doc] = api_doc.container
2006 return api_doc.container
2007 if len(api_doc.canonical_name) == 1:
2008 self._container_cache[api_doc] = None
2009 return None
2010 elif isinstance(api_doc, ModuleDoc) and api_doc.package is not UNKNOWN:
2011 self._container_cache[api_doc] = api_doc.package
2012 return api_doc.package
2013 else:
2014 parent = self.get_valdoc(api_doc.canonical_name.container())
2015 self._container_cache[api_doc] = parent
2016 return parent
2017
2018
2019
2020
2021
2023 """
2024 Initialize the L{callers} and L{callees} variables, given a
2025 C{Stat} object from the C{pstats} module.
2026
2027 @warning: This method uses undocumented data structures inside
2028 of C{profile_stats}.
2029 """
2030 if self.callers is None: self.callers = {}
2031 if self.callees is None: self.callees = {}
2032
2033
2034
2035
2036 self._update_funcid_to_doc(profile_stats)
2037
2038 for callee, (cc, nc, tt, ct, callers) in profile_stats.stats.items():
2039 callee = self._funcid_to_doc.get(callee)
2040 if callee is None: continue
2041 for caller in callers:
2042 caller = self._funcid_to_doc.get(caller)
2043 if caller is None: continue
2044 self.callers.setdefault(callee, []).append(caller)
2045 self.callees.setdefault(caller, []).append(callee)
2046
2068
2069
2070
2071
2072
2073 -def pp_apidoc(api_doc, doublespace=0, depth=5, exclude=(), include=(),
2074 backpointers=None):
2075 """
2076 @return: A multiline pretty-printed string representation for the
2077 given C{APIDoc}.
2078 @param doublespace: If true, then extra lines will be
2079 inserted to make the output more readable.
2080 @param depth: The maximum depth that pp_apidoc will descend
2081 into descendent VarDocs. To put no limit on
2082 depth, use C{depth=-1}.
2083 @param exclude: A list of names of attributes whose values should
2084 not be shown.
2085 @param backpointers: For internal use.
2086 """
2087 pyid = id(api_doc.__dict__)
2088 if backpointers is None: backpointers = {}
2089 if (hasattr(api_doc, 'canonical_name') and
2090 api_doc.canonical_name not in (None, UNKNOWN)):
2091 name = '%s for %s' % (api_doc.__class__.__name__,
2092 api_doc.canonical_name)
2093 elif getattr(api_doc, 'name', None) not in (UNKNOWN, None):
2094 if (getattr(api_doc, 'container', None) not in (UNKNOWN, None) and
2095 getattr(api_doc.container, 'canonical_name', None)
2096 not in (UNKNOWN, None)):
2097 name ='%s for %s' % (api_doc.__class__.__name__,
2098 api_doc.container.canonical_name+
2099 api_doc.name)
2100 else:
2101 name = '%s for %s' % (api_doc.__class__.__name__, api_doc.name)
2102 else:
2103 name = api_doc.__class__.__name__
2104
2105 if pyid in backpointers:
2106 return '%s [%s] (defined above)' % (name, backpointers[pyid])
2107
2108 if depth == 0:
2109 if hasattr(api_doc, 'name') and api_doc.name is not None:
2110 return '%s...' % api_doc.name
2111 else:
2112 return '...'
2113
2114 backpointers[pyid] = len(backpointers)
2115 s = '%s [%s]' % (name, backpointers[pyid])
2116
2117
2118 fields = [field for field in api_doc.__dict__.keys()
2119 if (field in include or
2120 (getattr(api_doc, field) is not UNKNOWN
2121 and field not in exclude))]
2122 if include:
2123 fields = [field for field in dir(api_doc)
2124 if field in include]
2125 else:
2126 fields = [field for field in api_doc.__dict__.keys()
2127 if (getattr(api_doc, field) is not UNKNOWN
2128 and field not in exclude)]
2129 fields.sort()
2130
2131 for field in fields:
2132 fieldval = getattr(api_doc, field)
2133 if doublespace: s += '\n |'
2134 s += '\n +- %s' % field
2135
2136 if (isinstance(fieldval, types.ListType) and
2137 len(fieldval)>0 and
2138 isinstance(fieldval[0], APIDoc)):
2139 s += _pp_list(api_doc, fieldval, doublespace, depth,
2140 exclude, include, backpointers,
2141 (field is fields[-1]))
2142 elif (isinstance(fieldval, types.DictType) and
2143 len(fieldval)>0 and
2144 isinstance(fieldval.values()[0], APIDoc)):
2145 s += _pp_dict(api_doc, fieldval, doublespace,
2146 depth, exclude, include, backpointers,
2147 (field is fields[-1]))
2148 elif isinstance(fieldval, APIDoc):
2149 s += _pp_apidoc(api_doc, fieldval, doublespace, depth,
2150 exclude, include, backpointers,
2151 (field is fields[-1]))
2152 else:
2153 s += ' = ' + _pp_val(api_doc, fieldval, doublespace,
2154 depth, exclude, include, backpointers)
2155
2156 return s
2157
2158 -def _pp_list(api_doc, items, doublespace, depth, exclude, include,
2159 backpointers, is_last):
2160 line1 = (is_last and ' ') or '|'
2161 s = ''
2162 for item in items:
2163 line2 = ((item is items[-1]) and ' ') or '|'
2164 joiner = '\n %s %s ' % (line1, line2)
2165 if doublespace: s += '\n %s |' % line1
2166 s += '\n %s +- ' % line1
2167 valstr = _pp_val(api_doc, item, doublespace, depth, exclude, include,
2168 backpointers)
2169 s += joiner.join(valstr.split('\n'))
2170 return s
2171
2172 -def _pp_dict(api_doc, dict, doublespace, depth, exclude, include,
2173 backpointers, is_last):
2174 items = dict.items()
2175 items.sort()
2176 line1 = (is_last and ' ') or '|'
2177 s = ''
2178 for item in items:
2179 line2 = ((item is items[-1]) and ' ') or '|'
2180 joiner = '\n %s %s ' % (line1, line2)
2181 if doublespace: s += '\n %s |' % line1
2182 s += '\n %s +- ' % line1
2183 valstr = _pp_val(api_doc, item[1], doublespace, depth, exclude,
2184 include, backpointers)
2185 s += joiner.join(('%s => %s' % (item[0], valstr)).split('\n'))
2186 return s
2187
2188 -def _pp_apidoc(api_doc, val, doublespace, depth, exclude, include,
2189 backpointers, is_last):
2190 line1 = (is_last and ' ') or '|'
2191 s = ''
2192 if doublespace: s += '\n %s | ' % line1
2193 s += '\n %s +- ' % line1
2194 joiner = '\n %s ' % line1
2195 childstr = pp_apidoc(val, doublespace, depth-1, exclude,
2196 include, backpointers)
2197 return s + joiner.join(childstr.split('\n'))
2198
2199 -def _pp_val(api_doc, val, doublespace, depth, exclude, include, backpointers):
2200 from epydoc import markup
2201 if isinstance(val, APIDoc):
2202 return pp_apidoc(val, doublespace, depth-1, exclude,
2203 include, backpointers)
2204 elif isinstance(val, markup.ParsedDocstring):
2205 valrepr = `val.to_plaintext(None)`
2206 if len(valrepr) < 40: return valrepr
2207 else: return valrepr[:37]+'...'
2208 else:
2209 valrepr = repr(val)
2210 if len(valrepr) < 40: return valrepr
2211 else: return valrepr[:37]+'...'
2212