epydoc.docbuilder

1 # epydoc -- Documentation Builder 2 # 3 # Copyright (C) 2005 Edward Loper 4 # Author: Edward Loper <edloper@loper.org> 5 # URL: <http://epydoc.sf.net> 6 # 7 # $Id: docbuilder.py 1683 2008-01-29 22:17:39Z edloper $ 8 9 """ 10 Construct data structures that encode the API documentation for Python 11 objects. These data structures are created using a series of steps: 12 13 1. B{Building docs}: Extract basic information about the objects, 14 and objects that are related to them. This can be done by 15 introspecting the objects' values (with L{epydoc.docintrospecter}; or 16 by parsing their source code (with L{epydoc.docparser}. 17 18 2. B{Merging}: Combine the information obtained from introspection & 19 parsing each object into a single structure. 20 21 3. B{Linking}: Replace any 'pointers' that were created for imported 22 variables by their target (if it's available). 23 24 4. B{Naming}: Chose a unique 'canonical name' for each 25 object. 26 27 5. B{Docstring Parsing}: Parse the docstring of each object, and 28 extract any pertinant information. 29 30 6. B{Inheritance}: Add information about variables that classes 31 inherit from their base classes. 32 33 The documentation information for each individual object is 34 represented using an L{APIDoc}; and the documentation for a collection 35 of objects is represented using a L{DocIndex}. 36 37 The main interface to C{epydoc.docbuilder} consists of two functions: 38 39 - L{build_doc()} -- Builds documentation for a single item, and 40 returns it as an L{APIDoc} object. 41 - L{build_doc_index()} -- Builds documentation for a collection of 42 items, and returns it as a L{DocIndex} object. 43 44 The remaining functions are used by these two main functions to 45 perform individual steps in the creation of the documentation. 46 47 @group Documentation Construction: build_doc, build_doc_index, 48 _get_docs_from_*, _report_valdoc_progress 49 @group Merging: *MERGE*, *merge* 50 @group Linking: link_imports 51 @group Naming: _name_scores, _unreachable_names, assign_canonical_names, 52 _var_shadows_self, _fix_self_shadowing_var, _unreachable_name_for 53 @group Inheritance: inherit_docs, _inherit_info 54 """ 55 __docformat__ = 'epytext en' 56 57 ###################################################################### 58 ## Contents 59 ###################################################################### 60 ## 1. build_doc() & build_doc_index() -- the main interface. 61 ## 2. merge_docs() -- helper, used to merge parse & introspect info 62 ## 3. link_imports() -- helper, used to connect imported vars w/ values 63 ## 4. assign_canonical_names() -- helper, used to set canonical names 64 ## 5. inherit_docs() -- helper, used to inherit docs from base classes 65 66 ###################################################################### 67 ## Imports 68 ###################################################################### 69 70 import sys, os, os.path, __builtin__, imp, re, inspect 71 from epydoc.apidoc import * 72 from epydoc.docintrospecter import introspect_docs 73 from epydoc.docparser import parse_docs, ParseError 74 from epydoc.docstringparser import parse_docstring 75 from epydoc import log 76 from epydoc.util import * 77 from epydoc.compat import * # Backwards compatibility 78 79 ###################################################################### 80 ## 1. build_doc() 81 ###################################################################### 82

83 -class BuildOptions:

84 """ 85 Holds the parameters for a documentation building process. 86 """

87 - def __init__(self, introspect=True, parse=True, 88 exclude_introspect=None, exclude_parse=None, 89 add_submodules=True):

90 self.introspect = introspect 91 self.parse = parse 92 self.exclude_introspect = exclude_introspect 93 self.exclude_parse = exclude_parse 94 self.add_submodules = add_submodules 95 96 # Test for pattern syntax and compile them into pattern objects. 97 try: 98 self._introspect_regexp = (exclude_introspect 99 and re.compile(exclude_introspect) or None) 100 self._parse_regexp = (exclude_parse 101 and re.compile(exclude_parse) or None) 102 except Exception, exc: 103 log.error('Error in regular expression pattern: %s' % exc) 104 raise

105

106 - def must_introspect(self, name):

107 """ 108 Return C{True} if a module is to be introsepcted with the current 109 settings. 110 111 @param name: The name of the module to test 112 @type name: L{DottedName} or C{str} 113 """ 114 return self.introspect \ 115 and not self._matches_filter(name, self._introspect_regexp)

116

117 - def must_parse(self, name):

118 """ 119 Return C{True} if a module is to be parsed with the current settings. 120 121 @param name: The name of the module to test 122 @type name: L{DottedName} or C{str} 123 """ 124 return self.parse \ 125 and not self._matches_filter(name, self._parse_regexp)

126

127 - def _matches_filter(self, name, regexp):

128 """ 129 Test if a module name matches a pattern. 130 131 @param name: The name of the module to test 132 @type name: L{DottedName} or C{str} 133 @param regexp: The pattern object to match C{name} against. 134 If C{None}, return C{False} 135 @type regexp: C{pattern} 136 @return: C{True} if C{name} in dotted format matches C{regexp}, 137 else C{False} 138 @rtype: C{bool} 139 """ 140 if regexp is None: return False 141 142 if isinstance(name, DottedName): 143 name = str(name) 144 145 return bool(regexp.search(name))

146 147

148 -def build_doc(item, introspect=True, parse=True, add_submodules=True, 149 exclude_introspect=None, exclude_parse=None):

150 """ 151 Build API documentation for a given item, and return it as 152 an L{APIDoc} object. 153 154 @rtype: L{APIDoc} 155 @param item: The item to document, specified using any of the 156 following: 157 - A string, naming a python package directory 158 (e.g., C{'epydoc/markup'}) 159 - A string, naming a python file 160 (e.g., C{'epydoc/docparser.py'}) 161 - A string, naming a python object 162 (e.g., C{'epydoc.docparser.DocParser'}) 163 - Any (non-string) python object 164 (e.g., C{list.append}) 165 @param introspect: If true, then use introspection to examine the 166 specified items. Otherwise, just use parsing. 167 @param parse: If true, then use parsing to examine the specified 168 items. Otherwise, just use introspection. 169 """ 170 docindex = build_doc_index([item], introspect, parse, add_submodules, 171 exclude_introspect=exclude_introspect, 172 exclude_parse=exclude_parse) 173 return docindex.root[0]

174

175 -def build_doc_index(items, introspect=True, parse=True, add_submodules=True, 176 exclude_introspect=None, exclude_parse=None):

177 """ 178 Build API documentation for the given list of items, and 179 return it in the form of a L{DocIndex}. 180 181 @rtype: L{DocIndex} 182 @param items: The items to document, specified using any of the 183 following: 184 - A string, naming a python package directory 185 (e.g., C{'epydoc/markup'}) 186 - A string, naming a python file 187 (e.g., C{'epydoc/docparser.py'}) 188 - A string, naming a python object 189 (e.g., C{'epydoc.docparser.DocParser'}) 190 - Any (non-string) python object 191 (e.g., C{list.append}) 192 @param introspect: If true, then use introspection to examine the 193 specified items. Otherwise, just use parsing. 194 @param parse: If true, then use parsing to examine the specified 195 items. Otherwise, just use introspection. 196 """ 197 try: 198 options = BuildOptions(parse=parse, introspect=introspect, 199 exclude_introspect=exclude_introspect, exclude_parse=exclude_parse, 200 add_submodules=add_submodules) 201 except Exception, e: 202 # log.error already reported by constructor. 203 return None 204 205 # Get the basic docs for each item. 206 doc_pairs = _get_docs_from_items(items, options) 207 208 # Merge the introspection & parse docs. 209 if options.parse and options.introspect: 210 log.start_progress('Merging parsed & introspected information') 211 docs = [] 212 for i, (introspect_doc, parse_doc) in enumerate(doc_pairs): 213 if introspect_doc is not None and parse_doc is not None: 214 if introspect_doc.canonical_name not in (None, UNKNOWN): 215 name = introspect_doc.canonical_name 216 else: 217 name = parse_doc.canonical_name 218 log.progress(float(i)/len(doc_pairs), name) 219 docs.append(merge_docs(introspect_doc, parse_doc)) 220 elif introspect_doc is not None: 221 docs.append(introspect_doc) 222 elif parse_doc is not None: 223 docs.append(parse_doc) 224 log.end_progress() 225 elif options.introspect: 226 docs = [doc_pair[0] for doc_pair in doc_pairs if doc_pair[0]] 227 else: 228 docs = [doc_pair[1] for doc_pair in doc_pairs if doc_pair[1]] 229 230 if len(docs) == 0: 231 log.error('Nothing left to document!') 232 return None 233 234 # Collect the docs into a single index. 235 docindex = DocIndex(docs) 236 237 # Replace any proxy valuedocs that we got from importing with 238 # their targets. 239 if options.parse: 240 log.start_progress('Linking imported variables') 241 valdocs = sorted(docindex.reachable_valdocs( 242 imports=False, submodules=False, packages=False, subclasses=False)) 243 for i, val_doc in enumerate(valdocs): 244 _report_valdoc_progress(i, val_doc, valdocs) 245 link_imports(val_doc, docindex) 246 log.end_progress() 247 248 # Assign canonical names. 249 log.start_progress('Indexing documentation') 250 for i, val_doc in enumerate(docindex.root): 251 log.progress(float(i)/len(docindex.root), val_doc.canonical_name) 252 assign_canonical_names(val_doc, val_doc.canonical_name, docindex) 253 log.end_progress() 254 255 # Set overrides pointers 256 log.start_progress('Checking for overridden methods') 257 valdocs = sorted(docindex.reachable_valdocs( 258 imports=False, submodules=False, packages=False, subclasses=False)) 259 for i, val_doc in enumerate(valdocs): 260 if isinstance(val_doc, ClassDoc): 261 percent = float(i)/len(valdocs) 262 log.progress(percent, val_doc.canonical_name) 263 find_overrides(val_doc) 264 log.end_progress() 265 266 # Parse the docstrings for each object. 267 log.start_progress('Parsing docstrings') 268 suppress_warnings = set(valdocs).difference( 269 docindex.reachable_valdocs( 270 imports=False, submodules=False, packages=False, subclasses=False, 271 bases=False, overrides=True)) 272 for i, val_doc in enumerate(valdocs): 273 _report_valdoc_progress(i, val_doc, valdocs) 274 # the value's docstring 275 parse_docstring(val_doc, docindex, suppress_warnings) 276 # the value's variables' docstrings 277 if (isinstance(val_doc, NamespaceDoc) and 278 val_doc.variables not in (None, UNKNOWN)): 279 for var_doc in val_doc.variables.values(): 280 # Now we have a chance to propagate the defining module 281 # to objects for which introspection is not possible, 282 # such as properties. 283 if (isinstance(var_doc.value, ValueDoc) 284 and var_doc.value.defining_module is UNKNOWN): 285 var_doc.value.defining_module = val_doc.defining_module 286 parse_docstring(var_doc, docindex, suppress_warnings) 287 log.end_progress() 288 289 # Take care of inheritance. 290 log.start_progress('Inheriting documentation') 291 for i, val_doc in enumerate(valdocs): 292 if isinstance(val_doc, ClassDoc): 293 percent = float(i)/len(valdocs) 294 log.progress(percent, val_doc.canonical_name) 295 inherit_docs(val_doc) 296 log.end_progress() 297 298 # Initialize the groups & sortedvars attributes. 299 log.start_progress('Sorting & Grouping') 300 for i, val_doc in enumerate(valdocs): 301 if isinstance(val_doc, NamespaceDoc): 302 percent = float(i)/len(valdocs) 303 log.progress(percent, val_doc.canonical_name) 304 val_doc.init_sorted_variables() 305 val_doc.init_variable_groups() 306 if isinstance(val_doc, ModuleDoc): 307 val_doc.init_submodule_groups() 308 val_doc.report_unused_groups() 309 log.end_progress() 310 311 return docindex

312

313 -def _report_valdoc_progress(i, val_doc, val_docs):

314 if (isinstance(val_doc, (ModuleDoc, ClassDoc)) and 315 val_doc.canonical_name is not UNKNOWN and 316 not val_doc.canonical_name[0].startswith('??')): 317 log.progress(float(i)/len(val_docs), val_doc.canonical_name)

318 319 #///////////////////////////////////////////////////////////////// 320 # Documentation Generation 321 #///////////////////////////////////////////////////////////////// 322

323 -def _get_docs_from_items(items, options):

324 325 # Start the progress bar. 326 log.start_progress('Building documentation') 327 progress_estimator = _ProgressEstimator(items) 328 329 # Check for duplicate item names. 330 item_set = set() 331 for item in items[:]: 332 if item in item_set: 333 log.warning("Name %r given multiple times" % item) 334 items.remove(item) 335 item_set.add(item) 336 337 # Keep track of what top-level canonical names we've assigned, to 338 # make sure there are no naming conflicts. This dict maps 339 # canonical names to the item names they came from (so we can print 340 # useful error messages). 341 canonical_names = {} 342 343 # Collect (introspectdoc, parsedoc) pairs for each item. 344 doc_pairs = [] 345 for item in items: 346 if isinstance(item, basestring): 347 if is_module_file(item): 348 doc_pairs.append(_get_docs_from_module_file( 349 item, options, progress_estimator)) 350 elif is_package_dir(item): 351 pkgfile = os.path.abspath(os.path.join(item, '__init__')) 352 doc_pairs.append(_get_docs_from_module_file( 353 pkgfile, options, progress_estimator)) 354 elif os.path.isfile(item): 355 doc_pairs.append(_get_docs_from_pyscript( 356 item, options, progress_estimator)) 357 elif hasattr(__builtin__, item): 358 val = getattr(__builtin__, item) 359 doc_pairs.append(_get_docs_from_pyobject( 360 val, options, progress_estimator)) 361 elif is_pyname(item): 362 doc_pairs.append(_get_docs_from_pyname( 363 item, options, progress_estimator)) 364 elif os.path.isdir(item): 365 log.error("Directory %r is not a package" % item) 366 continue 367 elif os.path.isfile(item): 368 log.error("File %s is not a Python module" % item) 369 continue 370 else: 371 log.error("Could not find a file or object named %s" % 372 item) 373 continue 374 else: 375 doc_pairs.append(_get_docs_from_pyobject( 376 item, options, progress_estimator)) 377 378 # Make sure there are no naming conflicts. 379 name = (getattr(doc_pairs[-1][0], 'canonical_name', None) or 380 getattr(doc_pairs[-1][1], 'canonical_name', None)) 381 if name in canonical_names: 382 log.error( 383 'Two of the specified items, %r and %r, have the same ' 384 'canonical name ("%s"). This may mean that you specified ' 385 'two different files that both use the same module name. ' 386 'Ignoring the second item (%r)' % 387 (canonical_names[name], item, name, canonical_names[name])) 388 doc_pairs.pop() 389 else: 390 canonical_names[name] = item 391 392 # This will only have an effect if doc_pairs[-1] contains a 393 # package's docs. The 'not is_module_file(item)' prevents 394 # us from adding subdirectories if they explicitly specify 395 # a package's __init__.py file. 396 if options.add_submodules and not is_module_file(item): 397 doc_pairs += _get_docs_from_submodules( 398 item, doc_pairs[-1], options, progress_estimator) 399 400 log.end_progress() 401 return doc_pairs

402

403 -def _get_docs_from_pyobject(obj, options, progress_estimator):

404 progress_estimator.complete += 1 405 log.progress(progress_estimator.progress(), repr(obj)) 406 407 if not options.introspect: 408 log.error("Cannot get docs for Python objects without " 409 "introspecting them.") 410 411 introspect_doc = parse_doc = None 412 introspect_error = parse_error = None 413 try: 414 introspect_doc = introspect_docs(value=obj) 415 except ImportError, e: 416 log.error(e) 417 return (None, None) 418 if options.parse: 419 if introspect_doc.canonical_name is not None: 420 prev_introspect = options.introspect 421 options.introspect = False 422 try: 423 _, parse_docs = _get_docs_from_pyname( 424 str(introspect_doc.canonical_name), options, 425 progress_estimator, suppress_warnings=True) 426 finally: 427 options.introspect = prev_introspect 428 429 # We need a name: 430 if introspect_doc.canonical_name in (None, UNKNOWN): 431 if hasattr(obj, '__name__'): 432 introspect_doc.canonical_name = DottedName( 433 DottedName.UNREACHABLE, obj.__name__) 434 else: 435 introspect_doc.canonical_name = DottedName( 436 DottedName.UNREACHABLE) 437 return (introspect_doc, parse_doc)

438

439 -def _get_docs_from_pyname(name, options, progress_estimator, 440 suppress_warnings=False):

441 progress_estimator.complete += 1 442 if options.must_introspect(name) or options.must_parse(name): 443 log.progress(progress_estimator.progress(), name) 444 445 introspect_doc = parse_doc = None 446 introspect_error = parse_error = None 447 if options.must_introspect(name): 448 try: 449 introspect_doc = introspect_docs(name=name) 450 except ImportError, e: 451 introspect_error = str(e) 452 if options.must_parse(name): 453 try: 454 parse_doc = parse_docs(name=name) 455 except ParseError, e: 456 parse_error = str(e) 457 except ImportError, e: 458 # If we get here, then there' probably no python source 459 # available; don't bother to generate a warnining. 460 pass 461 462 # Report any errors we encountered. 463 if not suppress_warnings: 464 _report_errors(name, introspect_doc, parse_doc, 465 introspect_error, parse_error) 466 467 # Return the docs we found. 468 return (introspect_doc, parse_doc)

469

470 -def _get_docs_from_pyscript(filename, options, progress_estimator):

471 # [xx] I should be careful about what names I allow as filenames, 472 # and maybe do some munging to prevent problems. 473 474 introspect_doc = parse_doc = None 475 introspect_error = parse_error = None 476 if options.introspect: 477 try: 478 introspect_doc = introspect_docs(filename=filename, is_script=True) 479 if introspect_doc.canonical_name is UNKNOWN: 480 introspect_doc.canonical_name = munge_script_name(filename) 481 except ImportError, e: 482 introspect_error = str(e) 483 if options.parse: 484 try: 485 parse_doc = parse_docs(filename=filename, is_script=True) 486 except ParseError, e: 487 parse_error = str(e) 488 except ImportError, e: 489 parse_error = str(e) 490 491 # Report any errors we encountered. 492 _report_errors(filename, introspect_doc, parse_doc, 493 introspect_error, parse_error) 494 495 # Return the docs we found. 496 return (introspect_doc, parse_doc)

497

498 -def _get_docs_from_module_file(filename, options, progress_estimator, 499 parent_docs=(None,None)):

500 """ 501 Construct and return the API documentation for the python 502 module with the given filename. 503 504 @param parent_docs: The C{ModuleDoc} of the containing package. 505 If C{parent_docs} is not provided, then this method will 506 check if the given filename is contained in a package; and 507 if so, it will construct a stub C{ModuleDoc} for the 508 containing package(s). C{parent_docs} is a tuple, where 509 the first element is the parent from introspection, and 510 the second element is the parent from parsing. 511 """ 512 # Record our progress. 513 modulename = os.path.splitext(os.path.split(filename)[1])[0] 514 if modulename == '__init__': 515 modulename = os.path.split(os.path.split(filename)[0])[1] 516 if parent_docs[0]: 517 modulename = DottedName(parent_docs[0].canonical_name, modulename) 518 elif parent_docs[1]: 519 modulename = DottedName(parent_docs[1].canonical_name, modulename) 520 if options.must_introspect(modulename) or options.must_parse(modulename): 521 log.progress(progress_estimator.progress(), 522 '%s (%s)' % (modulename, filename)) 523 progress_estimator.complete += 1 524 525 # Normalize the filename. 526 filename = os.path.normpath(os.path.abspath(filename)) 527 528 # When possible, use the source version of the file. 529 try: 530 filename = py_src_filename(filename) 531 src_file_available = True 532 except ValueError: 533 src_file_available = False 534 535 # Get the introspected & parsed docs (as appropriate) 536 introspect_doc = parse_doc = None 537 introspect_error = parse_error = None 538 if options.must_introspect(modulename): 539 try: 540 introspect_doc = introspect_docs( 541 filename=filename, context=parent_docs[0]) 542 if introspect_doc.canonical_name is UNKNOWN: 543 introspect_doc.canonical_name = modulename 544 except ImportError, e: 545 introspect_error = str(e) 546 if src_file_available and options.must_parse(modulename): 547 try: 548 parse_doc = parse_docs( 549 filename=filename, context=parent_docs[1]) 550 except ParseError, e: 551 parse_error = str(e) 552 except ImportError, e: 553 parse_error = str(e) 554 555 # Report any errors we encountered. 556 _report_errors(filename, introspect_doc, parse_doc, 557 introspect_error, parse_error) 558 559 # Return the docs we found. 560 return (introspect_doc, parse_doc)

561

562 -def _get_docs_from_submodules(item, pkg_docs, options, progress_estimator):

563 # Extract the package's __path__. 564 if isinstance(pkg_docs[0], ModuleDoc) and pkg_docs[0].is_package: 565 pkg_path = pkg_docs[0].path 566 package_dir = os.path.split(pkg_docs[0].filename)[0] 567 elif isinstance(pkg_docs[1], ModuleDoc) and pkg_docs[1].is_package: 568 pkg_path = pkg_docs[1].path 569 package_dir = os.path.split(pkg_docs[1].filename)[0] 570 else: 571 return [] 572 573 module_filenames = {} 574 subpackage_dirs = set() 575 for subdir in pkg_path: 576 if os.path.isdir(subdir): 577 for name in os.listdir(subdir): 578 filename = os.path.join(subdir, name) 579 # Is it a valid module filename? 580 if is_module_file(filename): 581 basename = os.path.splitext(filename)[0] 582 if os.path.split(basename)[1] != '__init__': 583 module_filenames[basename] = filename 584 # Is it a valid package filename? 585 if is_package_dir(filename): 586 subpackage_dirs.add(filename) 587 588 # Update our estimate of the number of modules in this package. 589 progress_estimator.revise_estimate(item, module_filenames.items(), 590 subpackage_dirs) 591 592 docs = [pkg_docs] 593 for module_filename in module_filenames.values(): 594 d = _get_docs_from_module_file( 595 module_filename, options, progress_estimator, pkg_docs) 596 docs.append(d) 597 for subpackage_dir in subpackage_dirs: 598 subpackage_file = os.path.join(subpackage_dir, '__init__') 599 docs.append(_get_docs_from_module_file( 600 subpackage_file, options, progress_estimator, pkg_docs)) 601 docs += _get_docs_from_submodules( 602 subpackage_dir, docs[-1], options, progress_estimator) 603 return docs

604

605 -def _report_errors(name, introspect_doc, parse_doc, 606 introspect_error, parse_error):

607 hdr = 'In %s:\n' % name 608 if introspect_doc == parse_doc == None: 609 log.start_block('%sNo documentation available!' % hdr) 610 if introspect_error: 611 log.error('Import failed:\n%s' % introspect_error) 612 if parse_error: 613 log.error('Source code parsing failed:\n%s' % parse_error) 614 log.end_block() 615 elif introspect_error: 616 log.start_block('%sImport failed (but source code parsing ' 617 'was successful).' % hdr) 618 log.error(introspect_error) 619 log.end_block() 620 elif parse_error: 621 log.start_block('%sSource code parsing failed (but ' 622 'introspection was successful).' % hdr) 623 log.error(parse_error) 624 log.end_block()

625 626 627 #///////////////////////////////////////////////////////////////// 628 # Progress Estimation (for Documentation Generation) 629 #///////////////////////////////////////////////////////////////// 630

631 -class _ProgressEstimator:

632 """ 633 Used to keep track of progress when generating the initial docs 634 for the given items. (It is not known in advance how many items a 635 package directory will contain, since it might depend on those 636 packages' __path__ values.) 637 """

638 - def __init__(self, items):

639 self.est_totals = {} 640 self.complete = 0 641 642 for item in items: 643 if is_package_dir(item): 644 self.est_totals[item] = self._est_pkg_modules(item) 645 else: 646 self.est_totals[item] = 1

647

648 - def progress(self):

649 total = sum(self.est_totals.values()) 650 return float(self.complete) / total

651

652 - def revise_estimate(self, pkg_item, modules, subpackages):

653 del self.est_totals[pkg_item] 654 for item in modules: 655 self.est_totals[item] = 1 656 for item in subpackages: 657 self.est_totals[item] = self._est_pkg_modules(item)

658

659 - def _est_pkg_modules(self, package_dir):

660 num_items = 0 661 662 if is_package_dir(package_dir): 663 for name in os.listdir(package_dir): 664 filename = os.path.join(package_dir, name) 665 if is_module_file(filename): 666 num_items += 1 667 elif is_package_dir(filename): 668 num_items += self._est_pkg_modules(filename) 669 670 return num_items

671 672 ###################################################################### 673 ## Doc Merger 674 ###################################################################### 675 676 MERGE_PRECEDENCE = { 677 'repr': 'parse', 678 679 # The names we get from introspection match the names that users 680 # can actually use -- i.e., they take magic into account. 681 'canonical_name': 'introspect', 682 683 # Only fall-back on the parser for is_imported if the introspecter 684 # isn't sure. Otherwise, we can end up thinking that vars 685 # containing modules are not imported, which can cause external 686 # modules to show up in the docs (sf bug #1653486) 687 'is_imported': 'introspect', 688 689 # The parser can tell if an assignment creates an alias or not. 690 'is_alias': 'parse', 691 692 # The parser is better able to determine what text file something 693 # came from; e.g., it can't be fooled by 'covert' imports. 694 'docformat': 'parse', 695 696 # The parse should be able to tell definitively whether a module 697 # is a package or not. 698 'is_package': 'parse', 699 700 # Extract the sort spec from the order in which values are defined 701 # in the source file. 702 'sort_spec': 'parse', 703 704 'submodules': 'introspect', 705 706 # The filename used by 'parse' is the source file. 707 'filename': 'parse', 708 709 # 'parse' is more likely to get the encoding right, but 710 # 'introspect' will handle programatically generated docstrings. 711 # Which is better? 712 'docstring': 'introspect', 713 } 714 """Indicates whether information from introspection or parsing should be 715 given precedence, for specific attributes. This dictionary maps from 716 attribute names to either C{'introspect'} or C{'parse'}.""" 717 718 DEFAULT_MERGE_PRECEDENCE = 'introspect' 719 """Indicates whether information from introspection or parsing should be 720 given precedence. Should be either C{'introspect'} or C{'parse'}""" 721 722 _attribute_mergefunc_registry = {}

723 -def register_attribute_mergefunc(attrib, mergefunc):

724 """ 725 Register an attribute merge function. This function will be 726 called by L{merge_docs()} when it needs to merge the attribute 727 values of two C{APIDoc}s. 728 729 @param attrib: The name of the attribute whose values are merged 730 by C{mergefunc}. 731 732 @param mergefunc: The merge function, whose sinature is: 733 734 >>> def mergefunc(introspect_val, parse_val, precedence, cyclecheck, path): 735 ... return calculate_merged_value(introspect_val, parse_val) 736 737 Where C{introspect_val} and C{parse_val} are the two values to 738 combine; C{precedence} is a string indicating which value takes 739 precedence for this attribute (C{'introspect'} or C{'parse'}); 740 C{cyclecheck} is a value used by C{merge_docs()} to make sure that 741 it only visits each pair of docs once; and C{path} is a string 742 describing the path that was taken from the root to this 743 attribute (used to generate log messages). 744 745 If the merge function needs to call C{merge_docs}, then it should 746 pass C{cyclecheck} and C{path} back in. (When appropriate, a 747 suffix should be added to C{path} to describe the path taken to 748 the merged values.) 749 """ 750 _attribute_mergefunc_registry[attrib] = mergefunc

751

752 -def merge_docs(introspect_doc, parse_doc, cyclecheck=None, path=None):

753 """ 754 Merge the API documentation information that was obtained from 755 introspection with information that was obtained from parsing. 756 C{introspect_doc} and C{parse_doc} should be two C{APIDoc} instances 757 that describe the same object. C{merge_docs} combines the 758 information from these two instances, and returns the merged 759 C{APIDoc}. 760 761 If C{introspect_doc} and C{parse_doc} are compatible, then they will 762 be I{merged} -- i.e., they will be coerced to a common class, and 763 their state will be stored in a shared dictionary. Once they have 764 been merged, any change made to the attributes of one will affect 765 the other. The value for the each of the merged C{APIDoc}'s 766 attributes is formed by combining the values of the source 767 C{APIDoc}s' attributes, as follows: 768 769 - If either of the source attributes' value is C{UNKNOWN}, then 770 use the other source attribute's value. 771 - Otherwise, if an attribute merge function has been registered 772 for the attribute, then use that function to calculate the 773 merged value from the two source attribute values. 774 - Otherwise, if L{MERGE_PRECEDENCE} is defined for the 775 attribute, then use the attribute value from the source that 776 it indicates. 777 - Otherwise, use the attribute value from the source indicated 778 by L{DEFAULT_MERGE_PRECEDENCE}. 779 780 If C{introspect_doc} and C{parse_doc} are I{not} compatible (e.g., if 781 their values have incompatible types), then C{merge_docs()} will 782 simply return either C{introspect_doc} or C{parse_doc}, depending on 783 the value of L{DEFAULT_MERGE_PRECEDENCE}. The two input 784 C{APIDoc}s will not be merged or modified in any way. 785 786 @param cyclecheck, path: These arguments should only be provided 787 when C{merge_docs()} is called by an attribute merge 788 function. See L{register_attribute_mergefunc()} for more 789 details. 790 """ 791 assert isinstance(introspect_doc, APIDoc) 792 assert isinstance(parse_doc, APIDoc) 793 794 if cyclecheck is None: 795 cyclecheck = set() 796 if introspect_doc.canonical_name not in (None, UNKNOWN): 797 path = '%s' % introspect_doc.canonical_name 798 elif parse_doc.canonical_name not in (None, UNKNOWN): 799 path = '%s' % parse_doc.canonical_name 800 else: 801 path = '??' 802 803 # If we've already examined this pair, then there's nothing 804 # more to do. The reason that we check id's here is that we 805 # want to avoid hashing the APIDoc objects for now, so we can 806 # use APIDoc.merge_and_overwrite() later. 807 if (id(introspect_doc), id(parse_doc)) in cyclecheck: 808 return introspect_doc 809 cyclecheck.add( (id(introspect_doc), id(parse_doc)) ) 810 811 # If these two are already merged, then we're done. (Two 812 # APIDoc's compare equal iff they are identical or have been 813 # merged.) 814 if introspect_doc == parse_doc: 815 return introspect_doc 816 817 # If both values are GenericValueDoc, then we don't want to merge 818 # them. E.g., we don't want to merge 2+2 with 4. So just copy 819 # the parse_doc's parse_repr to introspect_doc, & return it. 820 # (In particular, do *not* call merge_and_overwrite.) 821 if type(introspect_doc) == type(parse_doc) == GenericValueDoc: 822 if parse_doc.parse_repr is not UNKNOWN: 823 introspect_doc.parse_repr = parse_doc.parse_repr 824 introspect_doc.docs_extracted_by = 'both' 825 return introspect_doc 826 827 # Perform several sanity checks here -- if we accidentally 828 # merge values that shouldn't get merged, then bad things can 829 # happen. 830 mismatch = None 831 if (introspect_doc.__class__ != parse_doc.__class__ and 832 not (issubclass(introspect_doc.__class__, parse_doc.__class__) or 833 issubclass(parse_doc.__class__, introspect_doc.__class__))): 834 mismatch = ("value types don't match -- i=%r, p=%r." % 835 (introspect_doc.__class__, parse_doc.__class__)) 836 if (isinstance(introspect_doc, ValueDoc) and 837 isinstance(parse_doc, ValueDoc)): 838 if (introspect_doc.pyval is not UNKNOWN and 839 parse_doc.pyval is not UNKNOWN and 840 introspect_doc.pyval is not parse_doc.pyval): 841 mismatch = "values don't match." 842 elif (introspect_doc.canonical_name not in (None, UNKNOWN) and 843 parse_doc.canonical_name not in (None, UNKNOWN) and 844 introspect_doc.canonical_name != parse_doc.canonical_name): 845 mismatch = "canonical names don't match." 846 if mismatch is not None: 847 log.info("Not merging the parsed & introspected values of %s, " 848 "since their %s" % (path, mismatch)) 849 if DEFAULT_MERGE_PRECEDENCE == 'introspect': 850 return introspect_doc 851 else: 852 return parse_doc 853 854 # If one apidoc's class is a superclass of the other's, then 855 # specialize it to the more specific class. 856 if introspect_doc.__class__ is not parse_doc.__class__: 857 if issubclass(introspect_doc.__class__, parse_doc.__class__): 858 parse_doc.specialize_to(introspect_doc.__class__) 859 if issubclass(parse_doc.__class__, introspect_doc.__class__): 860 introspect_doc.specialize_to(parse_doc.__class__) 861 assert introspect_doc.__class__ is parse_doc.__class__ 862 863 # The posargs and defaults are tied together -- if we merge 864 # the posargs one way, then we need to merge the defaults the 865 # same way. So check them first. (This is a minor hack) 866 if (isinstance(introspect_doc, RoutineDoc) and 867 isinstance(parse_doc, RoutineDoc)): 868 _merge_posargs_and_defaults(introspect_doc, parse_doc, path) 869 870 # Merge the two api_doc's attributes. 871 for attrib in set(introspect_doc.__dict__.keys() + 872 parse_doc.__dict__.keys()): 873 # Be sure not to merge any private attributes (especially 874 # __mergeset or __has_been_hashed!) 875 if attrib.startswith('_'): continue 876 merge_attribute(attrib, introspect_doc, parse_doc, 877 cyclecheck, path) 878 879 # Set the dictionaries to be shared. 880 return introspect_doc.merge_and_overwrite(parse_doc)

881

882 -def _merge_posargs_and_defaults(introspect_doc, parse_doc, path):

883 # If either is unknown, then let merge_attrib handle it. 884 if introspect_doc.posargs is UNKNOWN or parse_doc.posargs is UNKNOWN: 885 return 886 887 # If the introspected doc just has '...', then trust the parsed doc. 888 if introspect_doc.posargs == ['...'] and parse_doc.posargs != ['...']: 889 introspect_doc.posargs = parse_doc.posargs 890 introspect_doc.posarg_defaults = parse_doc.posarg_defaults 891 892 # If they are incompatible, then check the precedence. 893 elif introspect_doc.posargs != parse_doc.posargs: 894 log.info("Not merging the parsed & introspected arg " 895 "lists for %s, since they don't match (%s vs %s)" 896 % (path, introspect_doc.posargs, parse_doc.posargs)) 897 if (MERGE_PRECEDENCE.get('posargs', DEFAULT_MERGE_PRECEDENCE) == 898 'introspect'): 899 parse_doc.posargs = introspect_doc.posargs 900 parse_doc.posarg_defaults = introspect_doc.posarg_defaults 901 else: 902 introspect_doc.posargs = parse_doc.posargs 903 introspect_doc.posarg_defaults = parse_doc.posarg_defaults

904

905 -def merge_attribute(attrib, introspect_doc, parse_doc, cyclecheck, path):

906 precedence = MERGE_PRECEDENCE.get(attrib, DEFAULT_MERGE_PRECEDENCE) 907 if precedence not in ('parse', 'introspect'): 908 raise ValueError('Bad precedence value %r' % precedence) 909 910 if (getattr(introspect_doc, attrib) is UNKNOWN and 911 getattr(parse_doc, attrib) is not UNKNOWN): 912 setattr(introspect_doc, attrib, getattr(parse_doc, attrib)) 913 elif (getattr(introspect_doc, attrib) is not UNKNOWN and 914 getattr(parse_doc, attrib) is UNKNOWN): 915 setattr(parse_doc, attrib, getattr(introspect_doc, attrib)) 916 elif (getattr(introspect_doc, attrib) is UNKNOWN and 917 getattr(parse_doc, attrib) is UNKNOWN): 918 pass 919 else: 920 # Both APIDoc objects have values; we need to merge them. 921 introspect_val = getattr(introspect_doc, attrib) 922 parse_val = getattr(parse_doc, attrib) 923 if attrib in _attribute_mergefunc_registry: 924 handler = _attribute_mergefunc_registry[attrib] 925 merged_val = handler(introspect_val, parse_val, precedence, 926 cyclecheck, path) 927 elif precedence == 'introspect': 928 merged_val = introspect_val 929 elif precedence == 'parse': 930 merged_val = parse_val 931 932 setattr(introspect_doc, attrib, merged_val) 933 setattr(parse_doc, attrib, merged_val)

934

935 -def merge_variables(varlist1, varlist2, precedence, cyclecheck, path):

936 # Merge all variables that are in both sets. 937 for varname, var1 in varlist1.items(): 938 var2 = varlist2.get(varname) 939 if var2 is not None: 940 var = merge_docs(var1, var2, cyclecheck, path+'.'+varname) 941 varlist1[varname] = var 942 varlist2[varname] = var 943 944 # Copy any variables that are not in varlist1 over. 945 for varname, var in varlist2.items(): 946 varlist1.setdefault(varname, var) 947 948 return varlist1

949

950 -def merge_value(value1, value2, precedence, cyclecheck, path):

951 assert value1 is not None and value2 is not None 952 return merge_docs(value1, value2, cyclecheck, path)

953

954 -def merge_overrides(v1, v2, precedence, cyclecheck, path):

955 return merge_value(v1, v2, precedence, cyclecheck, path+'.<overrides>')

956 -def merge_fget(v1, v2, precedence, cyclecheck, path):

957 return merge_value(v1, v2, precedence, cyclecheck, path+'.fget')

958 -def merge_fset(v1, v2, precedence, cyclecheck, path):

959 return merge_value(v1, v2, precedence, cyclecheck, path+'.fset')

960 -def merge_fdel(v1, v2, precedence, cyclecheck, path):

961 return merge_value(v1, v2, precedence, cyclecheck, path+'.fdel')

962

963 -def merge_proxy_for(v1, v2, precedence, cyclecheck, path):

964 # Anything we got from introspection shouldn't have a proxy_for 965 # attribute -- it should be the actual object's documentation. 966 return v1

967

968 -def merge_bases(baselist1, baselist2, precedence, cyclecheck, path):

969 # Be careful here -- if we get it wrong, then we could end up 970 # merging two unrelated classes, which could lead to bad 971 # things (e.g., a class that's its own subclass). So only 972 # merge two bases if we're quite sure they're the same class. 973 # (In particular, if they have the same canonical name.) 974 975 # If the lengths don't match up, then give up. This is most 976 # often caused by __metaclass__. 977 if len(baselist1) != len(baselist2): 978 log.info("Not merging the introspected & parsed base lists " 979 "for %s, since their lengths don't match (%s vs %s)" % 980 (path, len(baselist1), len(baselist2))) 981 if precedence == 'introspect': return baselist1 982 else: return baselist2 983 984 # If any names disagree, then give up. 985 for base1, base2 in zip(baselist1, baselist2): 986 if ((base1.canonical_name not in (None, UNKNOWN) and 987 base2.canonical_name not in (None, UNKNOWN)) and 988 base1.canonical_name != base2.canonical_name): 989 log.info("Not merging the parsed & introspected base " 990 "lists for %s, since the bases' names don't match " 991 "(%s vs %s)" % (path, base1.canonical_name, 992 base2.canonical_name)) 993 if precedence == 'introspect': return baselist1 994 else: return baselist2 995 996 for i, (base1, base2) in enumerate(zip(baselist1, baselist2)): 997 base = merge_docs(base1, base2, cyclecheck, 998 '%s.__bases__[%d]' % (path, i)) 999 baselist1[i] = baselist2[i] = base 1000 1001 return baselist1

1002

1003 -def merge_posarg_defaults(defaults1, defaults2, precedence, cyclecheck, path):

1004 if len(defaults1) != len(defaults2): 1005 if precedence == 'introspect': return defaults1 1006 else: return defaults2 1007 defaults = [] 1008 for i, (d1, d2) in enumerate(zip(defaults1, defaults2)): 1009 if d1 is not None and d2 is not None: 1010 d_path = '%s.<default-arg-val>[%d]' % (path, i) 1011 defaults.append(merge_docs(d1, d2, cyclecheck, d_path)) 1012 elif precedence == 'introspect': 1013 defaults.append(d1) 1014 else: 1015 defaults.append(d2) 1016 return defaults

1017

1018 -def merge_docstring(docstring1, docstring2, precedence, cyclecheck, path):

1019 if docstring1 is None or docstring1 is UNKNOWN or precedence=='parse': 1020 return docstring2 1021 else: 1022 return docstring1

1023

1024 -def merge_docs_extracted_by(v1, v2, precedence, cyclecheck, path):

1025 return 'both'

1026

1027 -def merge_submodules(v1, v2, precedence, cyclecheck, path):

1028 n1 = sorted([m.canonical_name for m in v1]) 1029 n2 = sorted([m.canonical_name for m in v2]) 1030 if (n1 != n2) and (n2 != []): 1031 log.info('Introspector & parser disagree about submodules ' 1032 'for %s: (%s) vs (%s)' % (path, 1033 ', '.join([str(n) for n in n1]), 1034 ', '.join([str(n) for n in n2]))) 1035 return v1 + [m for m in v2 if m.canonical_name not in n1] 1036 1037 return v1

1038 1039 register_attribute_mergefunc('variables', merge_variables) 1040 register_attribute_mergefunc('value', merge_value) 1041 register_attribute_mergefunc('overrides', merge_overrides) 1042 register_attribute_mergefunc('fget', merge_fget) 1043 register_attribute_mergefunc('fset', merge_fset) 1044 register_attribute_mergefunc('fdel', merge_fdel) 1045 register_attribute_mergefunc('proxy_for', merge_proxy_for) 1046 register_attribute_mergefunc('bases', merge_bases) 1047 register_attribute_mergefunc('posarg_defaults', merge_posarg_defaults) 1048 register_attribute_mergefunc('docstring', merge_docstring) 1049 register_attribute_mergefunc('docs_extracted_by', merge_docs_extracted_by) 1050 register_attribute_mergefunc('submodules', merge_submodules) 1051 1052 ###################################################################### 1053 ## Import Linking 1054 ###################################################################### 1055

1056 -def link_imports(val_doc, docindex):

1057 # Check if the ValueDoc has an unresolved proxy_for link. 1058 # If so, then resolve it. 1059 while val_doc.proxy_for not in (UNKNOWN, None): 1060 # Find the valuedoc that the proxy_for name points to. 1061 src_doc = docindex.get_valdoc(val_doc.proxy_for) 1062 1063 # If we don't have any valuedoc at that address, then 1064 # set that address as its canonical name. 1065 # [XXX] Do I really want to do this? 1066 if src_doc is None: 1067 val_doc.canonical_name = val_doc.proxy_for 1068 return 1069 1070 # If we *do* have something at that address, then 1071 # merge the proxy `val_doc` with it. 1072 elif src_doc != val_doc: 1073 # Copy any subclass information from val_doc->src_doc. 1074 if (isinstance(val_doc, ClassDoc) and 1075 isinstance(src_doc, ClassDoc)): 1076 for subclass in val_doc.subclasses: 1077 if subclass not in src_doc.subclasses: 1078 src_doc.subclasses.append(subclass) 1079 # Then overwrite val_doc with the contents of src_doc. 1080 src_doc.merge_and_overwrite(val_doc, ignore_hash_conflict=True) 1081 1082 # If the proxy_for link points back at src_doc 1083 # itself, then we most likely have a variable that's 1084 # shadowing a submodule that it should be equal to. 1085 # So just get rid of the variable. 1086 elif src_doc == val_doc: 1087 parent_name = val_doc.proxy_for[:-1] 1088 var_name = val_doc.proxy_for[-1] 1089 parent = docindex.get_valdoc(parent_name) 1090 if parent is not None and var_name in parent.variables: 1091 del parent.variables[var_name] 1092 src_doc.proxy_for = None

1093 1094 ###################################################################### 1095 ## Canonical Name Assignment 1096 ###################################################################### 1097 1098 _name_scores = {} 1099 """A dictionary mapping from each C{ValueDoc} to the score that has 1100 been assigned to its current cannonical name. If 1101 L{assign_canonical_names()} finds a canonical name with a better 1102 score, then it will replace the old name.""" 1103 1104 _unreachable_names = {DottedName(DottedName.UNREACHABLE):1} 1105 """The set of names that have been used for unreachable objects. This 1106 is used to ensure there are no duplicate cannonical names assigned. 1107 C{_unreachable_names} is a dictionary mapping from dotted names to 1108 integer ids, where the next unused unreachable name derived from 1109 dotted name C{n} is 1110 C{DottedName('%s-%s' % (n, str(_unreachable_names[n]+1))}""" 1111

1112 -def assign_canonical_names(val_doc, name, docindex, score=0):

1113 """ 1114 Assign a canonical name to C{val_doc} (if it doesn't have one 1115 already), and (recursively) to each variable in C{val_doc}. 1116 In particular, C{val_doc} will be assigned the canonical name 1117 C{name} iff either: 1118 - C{val_doc}'s canonical name is C{UNKNOWN}; or 1119 - C{val_doc}'s current canonical name was assigned by this 1120 method; but the score of the new name (C{score}) is higher 1121 than the score of the current name (C{score_dict[val_doc]}). 1122 1123 Note that canonical names will even be assigned to values 1124 like integers and C{None}; but these should be harmless. 1125 """ 1126 # If we've already visited this node, and our new score 1127 # doesn't beat our old score, then there's nothing more to do. 1128 # Note that since score increases strictly monotonically, this 1129 # also prevents us from going in cycles. 1130 if val_doc in _name_scores and score <= _name_scores[val_doc]: 1131 return 1132 1133 # Update val_doc's canonical name, if appropriate. 1134 if (val_doc not in _name_scores and 1135 val_doc.canonical_name is not UNKNOWN): 1136 # If this is the first time we've seen val_doc, and it 1137 # already has a name, then don't change that name. 1138 _name_scores[val_doc] = sys.maxint 1139 name = val_doc.canonical_name 1140 score = 0 1141 else: 1142 # Otherwise, update the name iff the new score is better 1143 # than the old one. 1144 if (val_doc not in _name_scores or 1145 score > _name_scores[val_doc]): 1146 val_doc.canonical_name = name 1147 _name_scores[val_doc] = score 1148 1149 # Recurse to any contained values. 1150 if isinstance(val_doc, NamespaceDoc): 1151 for var_doc in val_doc.variables.values(): 1152 # Set the variable's canonical name. 1153 varname = DottedName(name, var_doc.name) 1154 var_doc.canonical_name = varname 1155 1156 # If the value is unknown, or is a generic value doc, then 1157 # the valuedoc doesn't get assigned a name; move on. 1158 if (var_doc.value is UNKNOWN 1159 or isinstance(var_doc.value, GenericValueDoc)): 1160 continue 1161 1162 # [XX] After svn commit 1644-1647, I'm not sure if this 1163 # ever gets used: This check is for cases like 1164 # curses.wrapper, where an imported variable shadows its 1165 # value's "real" location. 1166 if _var_shadows_self(var_doc, varname): 1167 _fix_self_shadowing_var(var_doc, varname, docindex) 1168 1169 # Find the score for this new name. 1170 vardoc_score = score-1 1171 if var_doc.is_imported is UNKNOWN: vardoc_score -= 10 1172 elif var_doc.is_imported: vardoc_score -= 100 1173 if var_doc.is_alias is UNKNOWN: vardoc_score -= 10 1174 elif var_doc.is_alias: vardoc_score -= 1000 1175 1176 assign_canonical_names(var_doc.value, varname, 1177 docindex, vardoc_score) 1178 1179 # Recurse to any directly reachable values. 1180 for val_doc_2 in val_doc.apidoc_links(variables=False): 1181 val_name, val_score = _unreachable_name_for(val_doc_2, docindex) 1182 assign_canonical_names(val_doc_2, val_name, docindex, val_score)

1183

1184 -def _var_shadows_self(var_doc, varname):

1185 return (var_doc.value not in (None, UNKNOWN) and 1186 var_doc.value.canonical_name not in (None, UNKNOWN) and 1187 var_doc.value.canonical_name != varname and 1188 varname.dominates(var_doc.value.canonical_name))

1189

1190 -def _fix_self_shadowing_var(var_doc, varname, docindex):

1191 # If possible, find another name for the shadowed value. 1192 cname = var_doc.value.canonical_name 1193 for i in range(1, len(cname)-1): 1194 new_name = cname[:i] + (cname[i]+"'") + cname[i+1:] 1195 val_doc = docindex.get_valdoc(new_name) 1196 if val_doc is not None: 1197 log.warning("%s shadows its own value -- using %s instead" % 1198 (varname, new_name)) 1199 var_doc.value = val_doc 1200 return 1201 1202 # If we couldn't find the actual value, use an unreachable name. 1203 name, score = _unreachable_name_for(var_doc.value, docindex) 1204 log.warning('%s shadows itself -- using %s instead' % (varname, name)) 1205 var_doc.value.canonical_name = name

1206

1207 -def _unreachable_name_for(val_doc, docindex):

1208 assert isinstance(val_doc, ValueDoc) 1209 1210 # [xx] (when) does this help? 1211 if (isinstance(val_doc, ModuleDoc) and 1212 len(val_doc.canonical_name)==1 and val_doc.package is None): 1213 for root_val in docindex.root: 1214 if root_val.canonical_name == val_doc.canonical_name: 1215 if root_val != val_doc: 1216 log.error("Name conflict: %r vs %r" % 1217 (val_doc, root_val)) 1218 break 1219 else: 1220 return val_doc.canonical_name, -1000 1221 1222 # Assign it an 'unreachable' name: 1223 if (val_doc.pyval is not UNKNOWN and 1224 hasattr(val_doc.pyval, '__name__')): 1225 try: 1226 name = DottedName(DottedName.UNREACHABLE, 1227 val_doc.pyval.__name__, strict=True) 1228 except DottedName.InvalidDottedName: 1229 name = DottedName(DottedName.UNREACHABLE) 1230 else: 1231 name = DottedName(DottedName.UNREACHABLE) 1232 1233 # Uniquify the name. 1234 if name in _unreachable_names: 1235 _unreachable_names[name] += 1 1236 name = DottedName('%s-%s' % (name, _unreachable_names[name]-1)) 1237 else: 1238 _unreachable_names[name] = 1 1239 1240 return name, -10000

1241 1242 ###################################################################### 1243 ## Documentation Inheritance 1244 ###################################################################### 1245

1246 -def find_overrides(class_doc):

1247 """ 1248 Set the C{overrides} attribute for all variables in C{class_doc}. 1249 This needs to be done early (before docstring parsing), so we can 1250 know which docstrings to suppress warnings for. 1251 """ 1252 for base_class in list(class_doc.mro(warn_about_bad_bases=True)): 1253 if base_class == class_doc: continue 1254 if base_class.variables is UNKNOWN: continue 1255 for name, var_doc in base_class.variables.items(): 1256 if ( not (name.startswith('__') and not name.endswith('__')) and 1257 base_class == var_doc.container and 1258 name in class_doc.variables and 1259 class_doc.variables[name].container==class_doc and 1260 class_doc.variables[name].overrides is UNKNOWN ): 1261 class_doc.variables[name].overrides = var_doc

1262 1263

1264 -def inherit_docs(class_doc):

1265 for base_class in list(class_doc.mro(warn_about_bad_bases=True)): 1266 if base_class == class_doc: continue 1267 1268 # Inherit any groups. Place them *after* this class's groups, 1269 # so that any groups that are important to this class come 1270 # first. 1271 if base_class.group_specs not in (None, UNKNOWN): 1272 class_doc.group_specs += [gs for gs in base_class.group_specs 1273 if gs not in class_doc.group_specs] 1274 1275 # Inherit any variables. 1276 if base_class.variables is UNKNOWN: continue 1277 for name, var_doc in base_class.variables.items(): 1278 # If it's a __private variable, then don't inherit it. 1279 if name.startswith('__') and not name.endswith('__'): 1280 continue 1281 1282 # Inhetit only from the defining class. Or else, in case of 1283 # multiple inheritance, we may import from a grand-ancestor 1284 # variables overridden by a class that follows in mro. 1285 if base_class != var_doc.container: 1286 continue 1287 1288 # If class_doc doesn't have a variable with this name, 1289 # then inherit it. 1290 if name not in class_doc.variables: 1291 class_doc.variables[name] = var_doc 1292 1293 # Otherwise, class_doc already contains a variable 1294 # that shadows var_doc. But if class_doc's var is 1295 # local, then record the fact that it overrides 1296 # var_doc. 1297 elif class_doc.variables[name].container==class_doc: 1298 class_doc.variables[name].overrides = var_doc 1299 _inherit_info(class_doc.variables[name])

1300 1301 _INHERITED_ATTRIBS = [ 1302 'descr', 'summary', 'metadata', 'extra_docstring_fields', 1303 'type_descr', 'arg_descrs', 'arg_types', 'return_descr', 1304 'return_type', 'exception_descrs'] 1305 1306 _method_descriptor = type(list.append) 1307

1308 -def _inherit_info(var_doc):

1309 """ 1310 Copy any relevant documentation information from the variable that 1311 C{var_doc} overrides into C{var_doc} itself. 1312 """ 1313 src_var = var_doc.overrides 1314 src_val = var_doc.overrides.value 1315 val_doc = var_doc.value 1316 1317 # Special case: if the source value and target values are both c 1318 # extension methods, and the target value's signature is not 1319 # specified, then inherit the source value's signature. 1320 if (isinstance(val_doc, RoutineDoc) and 1321 isinstance(src_val, RoutineDoc) and 1322 (inspect.isbuiltin(val_doc.pyval) or 1323 isinstance(val_doc.pyval, _method_descriptor)) and 1324 (inspect.isbuiltin(src_val.pyval) or 1325 isinstance(src_val.pyval, _method_descriptor)) and 1326 val_doc.all_args() in (['...'], UNKNOWN) and 1327 src_val.all_args() not in (['...'], UNKNOWN)): 1328 for attrib in ['posargs', 'posarg_defaults', 'vararg', 1329 'kwarg', 'return_type']: 1330 setattr(val_doc, attrib, getattr(src_val, attrib)) 1331 1332 # If the new variable has a docstring, then don't inherit 1333 # anything, even if the docstring is blank. 1334 if var_doc.docstring not in (None, UNKNOWN): 1335 return 1336 # [xx] Do I want a check like this:? 1337 # # If it's a method and the signature doesn't match well enough, 1338 # # then give up. 1339 # if (isinstance(src_val, RoutineDoc) and 1340 # isinstance(val_doc, RoutineDoc)): 1341 # if (src_val.posargs != val_doc.posargs[:len(src_val.posargs)] or 1342 # src_val.vararg != None and src_val.vararg != val_doc.vararg): 1343 # log.docstring_warning( 1344 # "The signature of %s does not match the signature of the " 1345 # "method it overrides (%s); not inheriting documentation." % 1346 # (var_doc.canonical_name, src_var.canonical_name)) 1347 # return 1348 1349 # Inherit attributes! 1350 for attrib in _INHERITED_ATTRIBS: 1351 if (hasattr(var_doc, attrib) and hasattr(src_var, attrib) and 1352 getattr(src_var, attrib) not in (None, UNKNOWN)): 1353 setattr(var_doc, attrib, getattr(src_var, attrib)) 1354 elif (src_val is not None and 1355 hasattr(val_doc, attrib) and hasattr(src_val, attrib) and 1356 getattr(src_val, attrib) not in (None, UNKNOWN) and 1357 getattr(val_doc, attrib) in (None, UNKNOWN, [])): 1358 setattr(val_doc, attrib, getattr(src_val, attrib))

1359

Source Code for Module epydoc.docbuilder