epydoc.docintrospecter

1 # epydoc -- Introspection 2 # 3 # Copyright (C) 2005 Edward Loper 4 # Author: Edward Loper <edloper@loper.org> 5 # URL: <http://epydoc.sf.net> 6 # 7 # $Id: docintrospecter.py 1678 2008-01-29 17:21:29Z edloper $ 8 9 """ 10 Extract API documentation about python objects by directly introspecting 11 their values. 12 13 The function L{introspect_docs()}, which provides the main interface 14 of this module, examines a Python objects via introspection, and uses 15 the information it finds to create an L{APIDoc} objects containing the 16 API documentation for that objects. 17 18 The L{register_introspecter()} method can be used to extend the 19 functionality of C{docintrospector}, by providing methods that handle 20 special value types. 21 """ 22 __docformat__ = 'epytext en' 23 24 ###################################################################### 25 ## Imports 26 ###################################################################### 27 28 import inspect, re, sys, os.path, imp 29 # API documentation encoding: 30 from epydoc.apidoc import * 31 # Type comparisons: 32 from types import * 33 # Error reporting: 34 from epydoc import log 35 # Helper functions: 36 from epydoc.util import * 37 # For extracting encoding for docstrings: 38 import epydoc.docparser 39 # Builtin values 40 import __builtin__ 41 # Backwards compatibility 42 from epydoc.compat import * 43 44 ###################################################################### 45 ## Caches 46 ###################################################################### 47 48 _valuedoc_cache = {} 49 """A cache containing the API documentation for values that we've 50 already seen. This cache is implemented as a dictionary that maps a 51 value's pyid to its L{ValueDoc}. 52 53 Note that if we encounter a value but decide not to introspect it 54 (because it's imported from another module), then C{_valuedoc_cache} 55 will contain an entry for the value, but the value will not be listed 56 in L{_introspected_values}.""" 57 58 _introspected_values = {} 59 """A record which values we've introspected, encoded as a dictionary from 60 pyid to C{bool}.""" 61

62 -def clear_cache():

63 """ 64 Discard any cached C{APIDoc} values that have been computed for 65 introspected values. 66 """ 67 _valuedoc_cache.clear() 68 _introspected_values.clear()

69 70 ###################################################################### 71 ## Introspection 72 ###################################################################### 73

74 -def introspect_docs(value=None, name=None, filename=None, context=None, 75 is_script=False, module_name=None):

76 """ 77 Generate the API documentation for a specified object by 78 introspecting Python values, and return it as a L{ValueDoc}. The 79 object to generate documentation for may be specified using 80 the C{value} parameter, the C{filename} parameter, I{or} the 81 C{name} parameter. (It is an error to specify more than one 82 of these three parameters, or to not specify any of them.) 83 84 @param value: The python object that should be documented. 85 @param filename: The name of the file that contains the python 86 source code for a package, module, or script. If 87 C{filename} is specified, then C{introspect} will return a 88 C{ModuleDoc} describing its contents. 89 @param name: The fully-qualified python dotted name of any 90 value (including packages, modules, classes, and 91 functions). C{DocParser} will automatically figure out 92 which module(s) it needs to import in order to find the 93 documentation for the specified object. 94 @param context: The API documentation for the class of module 95 that contains C{value} (if available). 96 @param module_name: The name of the module where the value is defined. 97 Useful to retrieve the docstring encoding if there is no way to 98 detect the module by introspection (such as in properties) 99 """ 100 if value is None and name is not None and filename is None: 101 value = get_value_from_name(DottedName(name)) 102 elif value is None and name is None and filename is not None: 103 if is_script: 104 value = get_value_from_scriptname(filename) 105 else: 106 value = get_value_from_filename(filename, context) 107 elif name is None and filename is None: 108 # it's ok if value is None -- that's a value, after all. 109 pass 110 else: 111 raise ValueError("Expected exactly one of the following " 112 "arguments: value, name, filename") 113 114 pyid = id(value) 115 116 # If we've already introspected this value, then simply return 117 # its ValueDoc from our cache. 118 if pyid in _introspected_values: 119 # If the file is a script, then adjust its name. 120 if is_script and filename is not None: 121 _valuedoc_cache[pyid].canonical_name = DottedName( 122 munge_script_name(str(filename))) 123 return _valuedoc_cache[pyid] 124 125 # Create an initial value doc for this value & add it to the cache. 126 val_doc = _get_valuedoc(value) 127 128 # Introspect the value. 129 _introspected_values[pyid] = True 130 introspect_func = _get_introspecter(value) 131 introspect_func(value, val_doc, module_name=module_name) 132 133 # Set canonical name, if it was given 134 if val_doc.canonical_name is UNKNOWN and name is not None: 135 val_doc.canonical_name = DottedName(name) 136 137 # If the file is a script, then adjust its name. 138 if is_script and filename is not None: 139 val_doc.canonical_name = DottedName(munge_script_name(str(filename))) 140 141 if val_doc.canonical_name is UNKNOWN and filename is not None: 142 shadowed_name = DottedName(value.__name__) 143 log.warning("Module %s is shadowed by a variable with " 144 "the same name." % shadowed_name) 145 val_doc.canonical_name = DottedName(str(shadowed_name)+"'") 146 147 return val_doc

148

149 -def _get_valuedoc(value):

150 """ 151 If a C{ValueDoc} for the given value exists in the valuedoc 152 cache, then return it; otherwise, create a new C{ValueDoc}, 153 add it to the cache, and return it. When possible, the new 154 C{ValueDoc}'s C{pyval}, C{repr}, and C{canonical_name} 155 attributes will be set appropriately. 156 """ 157 pyid = id(value) 158 val_doc = _valuedoc_cache.get(pyid) 159 if val_doc is None: 160 try: canonical_name = get_canonical_name(value, strict=True) 161 except DottedName.InvalidDottedName: canonical_name = UNKNOWN 162 val_doc = ValueDoc(pyval=value, canonical_name = canonical_name, 163 docs_extracted_by='introspecter') 164 _valuedoc_cache[pyid] = val_doc 165 166 # If it's a module, then do some preliminary introspection. 167 # Otherwise, check what the containing module is (used e.g. 168 # to decide what markup language should be used for docstrings) 169 if inspect.ismodule(value): 170 introspect_module(value, val_doc, preliminary=True) 171 val_doc.defining_module = val_doc 172 else: 173 module_name = str(get_containing_module(value)) 174 module = sys.modules.get(module_name) 175 if module is not None and inspect.ismodule(module): 176 val_doc.defining_module = _get_valuedoc(module) 177 178 return val_doc

179 180 #//////////////////////////////////////////////////////////// 181 # Module Introspection 182 #//////////////////////////////////////////////////////////// 183 184 #: A list of module variables that should not be included in a 185 #: module's API documentation. 186 UNDOCUMENTED_MODULE_VARS = ( 187 '__builtins__', '__doc__', '__all__', '__file__', '__path__', 188 '__name__', '__extra_epydoc_fields__', '__docformat__') 189

190 -def introspect_module(module, module_doc, module_name=None, preliminary=False):

191 """ 192 Add API documentation information about the module C{module} 193 to C{module_doc}. 194 """ 195 module_doc.specialize_to(ModuleDoc) 196 197 # Record the module's docformat 198 if hasattr(module, '__docformat__'): 199 module_doc.docformat = unicode(module.__docformat__) 200 201 # Record the module's filename 202 if hasattr(module, '__file__'): 203 try: module_doc.filename = unicode(module.__file__) 204 except KeyboardInterrupt: raise 205 except: pass 206 if module_doc.filename is not UNKNOWN: 207 try: module_doc.filename = py_src_filename(module_doc.filename) 208 except ValueError: pass 209 210 # If this is just a preliminary introspection, then don't do 211 # anything else. (Typically this is true if this module was 212 # imported, but is not included in the set of modules we're 213 # documenting.) 214 module_doc.variables = {} 215 if preliminary: return 216 217 # Record the module's docstring 218 if hasattr(module, '__doc__'): 219 module_doc.docstring = get_docstring(module) 220 221 # If the module has a __path__, then it's (probably) a 222 # package; so set is_package=True and record its __path__. 223 if hasattr(module, '__path__'): 224 module_doc.is_package = True 225 try: module_doc.path = [unicode(p) for p in module.__path__] 226 except KeyboardInterrupt: raise 227 except: pass 228 else: 229 module_doc.is_package = False 230 231 # Make sure we have a name for the package. 232 dotted_name = module_doc.canonical_name 233 if dotted_name is UNKNOWN: 234 dotted_name = DottedName(module.__name__) 235 name_without_primes = DottedName(str(dotted_name).replace("'", "")) 236 237 # Record the module's parent package, if it has one. 238 if len(dotted_name) > 1: 239 package_name = str(dotted_name.container()) 240 package = sys.modules.get(package_name) 241 if package is not None: 242 module_doc.package = introspect_docs(package) 243 else: 244 module_doc.package = None 245 246 # Initialize the submodules property 247 module_doc.submodules = [] 248 249 # Add the module to its parent package's submodules list. 250 if module_doc.package not in (None, UNKNOWN): 251 module_doc.package.submodules.append(module_doc) 252 253 # Look up the module's __all__ attribute (public names). 254 public_names = None 255 if hasattr(module, '__all__'): 256 try: 257 public_names = set([str(name) for name in module.__all__]) 258 except KeyboardInterrupt: raise 259 except: pass 260 261 # Record the module's variables. 262 module_doc.variables = {} 263 for child_name in dir(module): 264 if child_name in UNDOCUMENTED_MODULE_VARS: continue 265 child = getattr(module, child_name) 266 267 # Create a VariableDoc for the child, and introspect its 268 # value if it's defined in this module. 269 container = get_containing_module(child) 270 if ((container is not None and 271 container == name_without_primes) or 272 (public_names is not None and 273 child_name in public_names)): 274 # Local variable. 275 child_val_doc = introspect_docs(child, context=module_doc, 276 module_name=dotted_name) 277 child_var_doc = VariableDoc(name=child_name, 278 value=child_val_doc, 279 is_imported=False, 280 container=module_doc, 281 docs_extracted_by='introspecter') 282 elif container is None or module_doc.canonical_name is UNKNOWN: 283 284 # Don't introspect stuff "from __future__" 285 if is_future_feature(child): continue 286 287 # Possibly imported variable. 288 child_val_doc = introspect_docs(child, context=module_doc) 289 child_var_doc = VariableDoc(name=child_name, 290 value=child_val_doc, 291 container=module_doc, 292 docs_extracted_by='introspecter') 293 else: 294 # Imported variable. 295 child_val_doc = _get_valuedoc(child) 296 child_var_doc = VariableDoc(name=child_name, 297 value=child_val_doc, 298 is_imported=True, 299 container=module_doc, 300 docs_extracted_by='introspecter') 301 302 # If the module's __all__ attribute is set, use it to set the 303 # variables public/private status and imported status. 304 if public_names is not None: 305 if child_name in public_names: 306 child_var_doc.is_public = True 307 if not isinstance(child_var_doc, ModuleDoc): 308 child_var_doc.is_imported = False 309 else: 310 child_var_doc.is_public = False 311 312 module_doc.variables[child_name] = child_var_doc 313 314 return module_doc

315 316 #//////////////////////////////////////////////////////////// 317 # Class Introspection 318 #//////////////////////////////////////////////////////////// 319 320 #: A list of class variables that should not be included in a 321 #: class's API documentation. 322 UNDOCUMENTED_CLASS_VARS = ( 323 '__doc__', '__module__', '__dict__', '__weakref__', '__slots__', 324 '__pyx_vtable__') 325

326 -def introspect_class(cls, class_doc, module_name=None):

327 """ 328 Add API documentation information about the class C{cls} 329 to C{class_doc}. 330 """ 331 class_doc.specialize_to(ClassDoc) 332 333 # Record the class's docstring. 334 class_doc.docstring = get_docstring(cls) 335 336 # Record the class's __all__ attribute (public names). 337 public_names = None 338 if hasattr(cls, '__all__'): 339 try: 340 public_names = set([str(name) for name in cls.__all__]) 341 except KeyboardInterrupt: raise 342 except: pass 343 344 # Start a list of subclasses. 345 class_doc.subclasses = [] 346 347 # Sometimes users will define a __metaclass__ that copies all 348 # class attributes from bases directly into the derived class's 349 # __dict__ when the class is created. (This saves the lookup time 350 # needed to search the base tree for an attribute.) But for the 351 # docs, we only want to list these copied attributes in the 352 # parent. So only add an attribute if it is not identical to an 353 # attribute of a base class. (Unfortunately, this can sometimes 354 # cause an attribute to look like it was inherited, even though it 355 # wasn't, if it happens to have the exact same value as the 356 # corresponding base's attribute.) An example of a case where 357 # this helps is PyQt -- subclasses of QWidget get about 300 358 # methods injected into them. 359 base_children = {} 360 361 # Record the class's base classes; and add the class to its 362 # base class's subclass lists. 363 if hasattr(cls, '__bases__'): 364 try: bases = list(cls.__bases__) 365 except: 366 bases = None 367 log.warning("Class '%s' defines __bases__, but it does not " 368 "contain an iterable; ignoring base list." 369 % getattr(cls, '__name__', '??')) 370 if bases is not None: 371 class_doc.bases = [] 372 for base in bases: 373 basedoc = introspect_docs(base) 374 class_doc.bases.append(basedoc) 375 basedoc.subclasses.append(class_doc) 376 377 bases.reverse() 378 for base in bases: 379 if hasattr(base, '__dict__'): 380 base_children.update(base.__dict__) 381 382 # The module name is not defined if the class is being introspected 383 # as another class base. 384 if module_name is None and class_doc.defining_module not in (None, UNKNOWN): 385 module_name = class_doc.defining_module.canonical_name 386 387 # Record the class's local variables. 388 class_doc.variables = {} 389 if hasattr(cls, '__dict__'): 390 private_prefix = '_%s__' % getattr(cls, '__name__', '<none>') 391 for child_name, child in cls.__dict__.items(): 392 if (child_name in base_children 393 and base_children[child_name] == child): 394 continue 395 396 if child_name.startswith(private_prefix): 397 child_name = child_name[len(private_prefix)-2:] 398 if child_name in UNDOCUMENTED_CLASS_VARS: continue 399 val_doc = introspect_docs(child, context=class_doc, 400 module_name=module_name) 401 var_doc = VariableDoc(name=child_name, value=val_doc, 402 container=class_doc, 403 docs_extracted_by='introspecter') 404 if public_names is not None: 405 var_doc.is_public = (child_name in public_names) 406 class_doc.variables[child_name] = var_doc 407 408 return class_doc

409 410 #//////////////////////////////////////////////////////////// 411 # Routine Introspection 412 #//////////////////////////////////////////////////////////// 413

414 -def introspect_routine(routine, routine_doc, module_name=None):

415 """Add API documentation information about the function 416 C{routine} to C{routine_doc} (specializing it to C{Routine_doc}).""" 417 routine_doc.specialize_to(RoutineDoc) 418 419 # Extract the underying function 420 if isinstance(routine, MethodType): 421 func = routine.im_func 422 elif isinstance(routine, staticmethod): 423 func = routine.__get__(0) 424 elif isinstance(routine, classmethod): 425 func = routine.__get__(0).im_func 426 else: 427 func = routine 428 429 # Record the function's docstring. 430 routine_doc.docstring = get_docstring(func) 431 432 # Record the function's signature. 433 if isinstance(func, FunctionType): 434 (args, vararg, kwarg, defaults) = inspect.getargspec(func) 435 436 # Add the arguments. 437 routine_doc.posargs = args 438 routine_doc.vararg = vararg 439 routine_doc.kwarg = kwarg 440 441 # Set default values for positional arguments. 442 routine_doc.posarg_defaults = [None]*len(args) 443 if defaults is not None: 444 offset = len(args)-len(defaults) 445 for i in range(len(defaults)): 446 default_val = introspect_docs(defaults[i]) 447 routine_doc.posarg_defaults[i+offset] = default_val 448 449 # If it's a bound method, then strip off the first argument. 450 if isinstance(routine, MethodType) and routine.im_self is not None: 451 routine_doc.posargs = routine_doc.posargs[1:] 452 routine_doc.posarg_defaults = routine_doc.posarg_defaults[1:] 453 454 # Set the routine's line number. 455 if hasattr(func, 'func_code'): 456 routine_doc.lineno = func.func_code.co_firstlineno 457 458 else: 459 # [XX] I should probably use UNKNOWN here?? 460 # dvarrazzo: if '...' is to be changed, also check that 461 # `docstringparser.process_arg_field()` works correctly. 462 # See SF bug #1556024. 463 routine_doc.posargs = ['...'] 464 routine_doc.posarg_defaults = [None] 465 routine_doc.kwarg = None 466 routine_doc.vararg = None 467 468 # Change type, if appropriate. 469 if isinstance(routine, staticmethod): 470 routine_doc.specialize_to(StaticMethodDoc) 471 if isinstance(routine, classmethod): 472 routine_doc.specialize_to(ClassMethodDoc) 473 474 return routine_doc

475 476 #//////////////////////////////////////////////////////////// 477 # Property Introspection 478 #//////////////////////////////////////////////////////////// 479

480 -def introspect_property(prop, prop_doc, module_name=None):

481 """Add API documentation information about the property 482 C{prop} to C{prop_doc} (specializing it to C{PropertyDoc}).""" 483 prop_doc.specialize_to(PropertyDoc) 484 485 # Record the property's docstring. 486 prop_doc.docstring = get_docstring(prop, module_name=module_name) 487 488 # Record the property's access functions. 489 if hasattr(prop, 'fget'): 490 prop_doc.fget = introspect_docs(prop.fget) 491 prop_doc.fset = introspect_docs(prop.fset) 492 prop_doc.fdel = introspect_docs(prop.fdel) 493 494 return prop_doc

495 496 #//////////////////////////////////////////////////////////// 497 # Generic Value Introspection 498 #//////////////////////////////////////////////////////////// 499

500 -def introspect_other(val, val_doc, module_name=None):

501 """Specialize val_doc to a C{GenericValueDoc} and return it.""" 502 val_doc.specialize_to(GenericValueDoc) 503 return val_doc

504 505 #//////////////////////////////////////////////////////////// 506 # Helper functions 507 #//////////////////////////////////////////////////////////// 508

509 -def isclass(object):

510 """ 511 Return true if the given object is a class. In particular, return 512 true if object is an instance of C{types.TypeType} or of 513 C{types.ClassType}. This is used instead of C{inspect.isclass()}, 514 because the latter returns true for objects that are not classes 515 (in particular, it returns true for any object that has a 516 C{__bases__} attribute, including objects that define 517 C{__getattr__} to always return a value). 518 """ 519 return isinstance(object, tuple(_CLASS_TYPES))

520 521 _CLASS_TYPES = set([TypeType, ClassType]) 522 """A list of types that should be treated as classes.""" 523

524 -def register_class_type(typ):

525 """Add a type to the lists of types that should be treated as 526 classes. By default, this list contains C{TypeType} and 527 C{ClassType}.""" 528 _CLASS_TYPES.add(typ)

529 530 __future_check_works = None 531

532 -def is_future_feature(object):

533 """ 534 Return True if C{object} results from a C{from __future__ import feature} 535 statement. 536 """ 537 # Guard from unexpected implementation changes of the __future__ module. 538 global __future_check_works 539 if __future_check_works is not None: 540 if __future_check_works: 541 import __future__ 542 return isinstance(object, __future__._Feature) 543 else: 544 return False 545 else: 546 __future_check_works = True 547 try: 548 return is_future_feature(object) 549 except: 550 __future_check_works = False 551 log.warning("Troubles inspecting __future__. Python implementation" 552 " may have been changed.") 553 return False

554

555 -def get_docstring(value, module_name=None):

556 """ 557 Return the docstring for the given value; or C{None} if it 558 does not have a docstring. 559 @rtype: C{unicode} 560 """ 561 docstring = getattr(value, '__doc__', None) 562 if docstring is None: 563 return None 564 elif isinstance(docstring, unicode): 565 return docstring 566 elif isinstance(docstring, str): 567 try: return unicode(docstring, 'ascii') 568 except UnicodeDecodeError: 569 if module_name is None: 570 module_name = get_containing_module(value) 571 if module_name is not None: 572 try: 573 module = get_value_from_name(module_name) 574 filename = py_src_filename(module.__file__) 575 encoding = epydoc.docparser.get_module_encoding(filename) 576 return unicode(docstring, encoding) 577 except KeyboardInterrupt: raise 578 except Exception: pass 579 if hasattr(value, '__name__'): name = value.__name__ 580 else: name = repr(value) 581 log.warning("%s's docstring is not a unicode string, but it " 582 "contains non-ascii data -- treating it as " 583 "latin-1." % name) 584 return unicode(docstring, 'latin-1') 585 return None 586 elif value is BuiltinMethodType: 587 # Don't issue a warning for this special case. 588 return None 589 else: 590 if hasattr(value, '__name__'): name = value.__name__ 591 else: name = repr(value) 592 log.warning("%s's docstring is not a string -- ignoring it." % 593 name) 594 return None

595

596 -def get_canonical_name(value, strict=False):

597 """ 598 @return: the canonical name for C{value}, or C{UNKNOWN} if no 599 canonical name can be found. Currently, C{get_canonical_name} 600 can find canonical names for: modules; functions; non-nested 601 classes; methods of non-nested classes; and some class methods 602 of non-nested classes. 603 604 @rtype: L{DottedName} or C{UNKNOWN} 605 """ 606 if not hasattr(value, '__name__'): return UNKNOWN 607 608 # Get the name via introspection. 609 if isinstance(value, ModuleType): 610 try: 611 dotted_name = DottedName(value.__name__, strict=strict) 612 # If the module is shadowed by a variable in its parent 613 # package(s), then add a prime mark to the end, to 614 # differentiate it from the variable that shadows it. 615 if verify_name(value, dotted_name) is UNKNOWN: 616 log.warning("Module %s is shadowed by a variable with " 617 "the same name." % dotted_name) 618 # Note -- this return bypasses verify_name check: 619 return DottedName(value.__name__+"'") 620 except DottedName.InvalidDottedName: 621 # Name is not a valid Python identifier -- treat as script. 622 if hasattr(value, '__file__'): 623 filename = '%s' % value.__str__ 624 dotted_name = DottedName(munge_script_name(filename)) 625 626 elif isclass(value): 627 if value.__module__ == '__builtin__': 628 dotted_name = DottedName(value.__name__, strict=strict) 629 else: 630 dotted_name = DottedName(value.__module__, value.__name__, 631 strict=strict) 632 633 elif (inspect.ismethod(value) and value.im_self is not None and 634 value.im_class is ClassType and 635 not value.__name__.startswith('<')): # class method. 636 class_name = get_canonical_name(value.im_self) 637 if class_name is UNKNOWN: return UNKNOWN 638 dotted_name = DottedName(class_name, value.__name__, strict=strict) 639 elif (inspect.ismethod(value) and 640 not value.__name__.startswith('<')): 641 class_name = get_canonical_name(value.im_class) 642 if class_name is UNKNOWN: return UNKNOWN 643 dotted_name = DottedName(class_name, value.__name__, strict=strict) 644 elif (isinstance(value, FunctionType) and 645 not value.__name__.startswith('<')): 646 module_name = _find_function_module(value) 647 if module_name is None: return UNKNOWN 648 dotted_name = DottedName(module_name, value.__name__, strict=strict) 649 else: 650 return UNKNOWN 651 652 return verify_name(value, dotted_name)

653

654 -def verify_name(value, dotted_name):

655 """ 656 Verify the name. E.g., if it's a nested class, then we won't be 657 able to find it with the name we constructed. 658 """ 659 if dotted_name is UNKNOWN: return UNKNOWN 660 if len(dotted_name) == 1 and hasattr(__builtin__, dotted_name[0]): 661 return dotted_name 662 named_value = sys.modules.get(dotted_name[0]) 663 if named_value is None: return UNKNOWN 664 for identifier in dotted_name[1:]: 665 try: named_value = getattr(named_value, identifier) 666 except: return UNKNOWN 667 if value is named_value: 668 return dotted_name 669 else: 670 return UNKNOWN

671 672 # [xx] not used:

673 -def value_repr(value):

674 try: 675 s = '%r' % value 676 if isinstance(s, str): 677 s = decode_with_backslashreplace(s) 678 return s 679 except: 680 return UNKNOWN

681

682 -def get_containing_module(value):

683 """ 684 Return the name of the module containing the given value, or 685 C{None} if the module name can't be determined. 686 @rtype: L{DottedName} 687 """ 688 if inspect.ismodule(value): 689 return DottedName(value.__name__) 690 elif isclass(value): 691 return DottedName(value.__module__) 692 elif (inspect.ismethod(value) and value.im_self is not None and 693 value.im_class is ClassType): # class method. 694 return DottedName(value.im_self.__module__) 695 elif inspect.ismethod(value): 696 return DottedName(value.im_class.__module__) 697 elif inspect.isroutine(value): 698 module = _find_function_module(value) 699 if module is None: return None 700 return DottedName(module) 701 else: 702 return None

703

704 -def _find_function_module(func):

705 """ 706 @return: The module that defines the given function. 707 @rtype: C{module} 708 @param func: The function whose module should be found. 709 @type func: C{function} 710 """ 711 if hasattr(func, '__module__'): 712 return func.__module__ 713 try: 714 module = inspect.getmodule(func) 715 if module: return module.__name__ 716 except KeyboardInterrupt: raise 717 except: pass 718 719 # This fallback shouldn't usually be needed. But it is needed in 720 # a couple special cases (including using epydoc to document 721 # itself). In particular, if a module gets loaded twice, using 722 # two different names for the same file, then this helps. 723 for module in sys.modules.values(): 724 if (hasattr(module, '__dict__') and 725 hasattr(func, 'func_globals') and 726 func.func_globals is module.__dict__): 727 return module.__name__ 728 return None

729 730 #//////////////////////////////////////////////////////////// 731 # Introspection Dispatch Table 732 #//////////////////////////////////////////////////////////// 733 734 _introspecter_registry = []

735 -def register_introspecter(applicability_test, introspecter, priority=10):

736 """ 737 Register an introspecter function. Introspecter functions take 738 two arguments, a python value and a C{ValueDoc} object, and should 739 add information about the given value to the the C{ValueDoc}. 740 Usually, the first line of an inspecter function will specialize 741 it to a sublass of C{ValueDoc}, using L{ValueDoc.specialize_to()}: 742 743 >>> def typical_introspecter(value, value_doc): 744 ... value_doc.specialize_to(SomeSubclassOfValueDoc) 745 ... <add info to value_doc> 746 747 @param priority: The priority of this introspecter, which determines 748 the order in which introspecters are tried -- introspecters with lower 749 numbers are tried first. The standard introspecters have priorities 750 ranging from 20 to 30. The default priority (10) will place new 751 introspecters before standard introspecters. 752 """ 753 _introspecter_registry.append( (priority, applicability_test, 754 introspecter) ) 755 _introspecter_registry.sort()

756

757 -def _get_introspecter(value):

758 for (priority, applicability_test, introspecter) in _introspecter_registry: 759 if applicability_test(value): 760 return introspecter 761 else: 762 return introspect_other

763 764 # Register the standard introspecter functions.

765 -def is_classmethod(v): return isinstance(v, classmethod)

766 -def is_staticmethod(v): return isinstance(v, staticmethod)

767 -def is_property(v): return isinstance(v, property)

768 register_introspecter(inspect.ismodule, introspect_module, priority=20) 769 register_introspecter(isclass, introspect_class, priority=24) 770 register_introspecter(inspect.isroutine, introspect_routine, priority=28) 771 register_introspecter(is_property, introspect_property, priority=30) 772 773 # Register getset_descriptor as a property 774 try: 775 import array 776 getset_type = type(array.array.typecode) 777 del array

778 - def is_getset(v): return isinstance(v, getset_type)

779 register_introspecter(is_getset, introspect_property, priority=32) 780 except: 781 pass 782 783 # Register member_descriptor as a property 784 try: 785 import datetime 786 member_type = type(datetime.timedelta.days) 787 del datetime

788 - def is_member(v): return isinstance(v, member_type)

789 register_introspecter(is_member, introspect_property, priority=34) 790 except: 791 pass 792 793 #//////////////////////////////////////////////////////////// 794 # Import support 795 #//////////////////////////////////////////////////////////// 796

797 -def get_value_from_filename(filename, context=None):

798 # Normalize the filename. 799 filename = os.path.normpath(os.path.abspath(filename)) 800 801 # Divide the filename into a base directory and a name. (For 802 # packages, use the package's parent directory as the base, and 803 # the directory name as its name). 804 basedir = os.path.split(filename)[0] 805 name = os.path.splitext(os.path.split(filename)[1])[0] 806 if name == '__init__': 807 basedir, name = os.path.split(basedir) 808 name = DottedName(name) 809 810 # If the context wasn't provided, then check if the file is in a 811 # package directory. If so, then update basedir & name to contain 812 # the topmost package's directory and the fully qualified name for 813 # this file. (This update assume the default value of __path__ 814 # for the parent packages; if the parent packages override their 815 # __path__s, then this can cause us not to find the value.) 816 if context is None: 817 while is_package_dir(basedir): 818 basedir, pkg_name = os.path.split(basedir) 819 name = DottedName(pkg_name, name) 820 821 # If a parent package was specified, then find the directory of 822 # the topmost package, and the fully qualified name for this file. 823 if context is not None: 824 # Combine the name. 825 name = DottedName(context.canonical_name, name) 826 # Find the directory of the base package. 827 while context not in (None, UNKNOWN): 828 pkg_dir = os.path.split(context.filename)[0] 829 basedir = os.path.split(pkg_dir)[0] 830 context = context.package 831 832 # Import the module. (basedir is the directory of the module's 833 # topmost package, or its own directory if it's not in a package; 834 # and name is the fully qualified dotted name for the module.) 835 old_sys_path = sys.path[:] 836 try: 837 sys.path.insert(0, basedir) 838 # This will make sure that we get the module itself, even 839 # if it is shadowed by a variable. (E.g., curses.wrapper): 840 _import(str(name)) 841 if str(name) in sys.modules: 842 return sys.modules[str(name)] 843 else: 844 # Use this as a fallback -- it *shouldn't* ever be needed. 845 return get_value_from_name(name) 846 finally: 847 sys.path = old_sys_path

848

849 -def get_value_from_scriptname(filename):

850 name = munge_script_name(filename) 851 return _import(name, filename)

852

853 -def get_value_from_name(name, globs=None):

854 """ 855 Given a name, return the corresponding value. 856 857 @param globs: A namespace to check for the value, if there is no 858 module containing the named value. Defaults to __builtin__. 859 """ 860 name = DottedName(name) 861 862 # Import the topmost module/package. If we fail, then check if 863 # the requested name refers to a builtin. 864 try: 865 module = _import(name[0]) 866 except ImportError, e: 867 if globs is None: globs = __builtin__.__dict__ 868 if name[0] in globs: 869 try: return _lookup(globs[name[0]], name[1:]) 870 except: raise e 871 else: 872 raise 873 874 # Find the requested value in the module/package or its submodules. 875 for i in range(1, len(name)): 876 try: return _lookup(module, name[i:]) 877 except ImportError: pass 878 module = _import('.'.join(name[:i+1])) 879 module = _lookup(module, name[1:i+1]) 880 return module

881

882 -def _lookup(module, name):

883 val = module 884 for i, identifier in enumerate(name): 885 try: val = getattr(val, identifier) 886 except AttributeError: 887 exc_msg = ('no variable named %s in %s' % 888 (identifier, '.'.join(name[:1+i]))) 889 raise ImportError(exc_msg) 890 return val

891

892 -def _import(name, filename=None):

893 """ 894 Run the given callable in a 'sandboxed' environment. 895 Currently, this includes saving and restoring the contents of 896 sys and __builtins__; and suppressing stdin, stdout, and stderr. 897 """ 898 # Note that we just do a shallow copy of sys. In particular, 899 # any changes made to sys.modules will be kept. But we do 900 # explicitly store sys.path. 901 old_sys = sys.__dict__.copy() 902 old_sys_path = sys.path[:] 903 old_builtins = __builtin__.__dict__.copy() 904 905 # Add the current directory to sys.path, in case they're trying to 906 # import a module by name that resides in the current directory. 907 # But add it to the end -- otherwise, the explicit directory added 908 # in get_value_from_filename might get overwritten 909 sys.path.append('') 910 911 # Suppress input and output. (These get restored when we restore 912 # sys to old_sys). 913 sys.stdin = sys.stdout = sys.stderr = _dev_null 914 sys.__stdin__ = sys.__stdout__ = sys.__stderr__ = _dev_null 915 916 # Remove any command-line arguments 917 sys.argv = ['(imported)'] 918 919 try: 920 try: 921 if filename is None: 922 return __import__(name) 923 else: 924 # For importing scripts: 925 return imp.load_source(name, filename) 926 except KeyboardInterrupt: raise 927 except: 928 exc_typ, exc_val, exc_tb = sys.exc_info() 929 if exc_val is None: 930 estr = '%s' % (exc_typ,) 931 else: 932 estr = '%s: %s' % (exc_typ.__name__, exc_val) 933 if exc_tb.tb_next is not None: 934 estr += ' (line %d)' % (exc_tb.tb_next.tb_lineno,) 935 raise ImportError(estr) 936 finally: 937 # Restore the important values that we saved. 938 __builtin__.__dict__.clear() 939 __builtin__.__dict__.update(old_builtins) 940 sys.__dict__.clear() 941 sys.__dict__.update(old_sys) 942 sys.path = old_sys_path

943

944 -def introspect_docstring_lineno(api_doc):

945 """ 946 Try to determine the line number on which the given item's 947 docstring begins. Return the line number, or C{None} if the line 948 number can't be determined. The line number of the first line in 949 the file is 1. 950 """ 951 if api_doc.docstring_lineno is not UNKNOWN: 952 return api_doc.docstring_lineno 953 if isinstance(api_doc, ValueDoc) and api_doc.pyval is not UNKNOWN: 954 try: 955 lines, lineno = inspect.findsource(api_doc.pyval) 956 if not isinstance(api_doc, ModuleDoc): lineno += 1 957 for lineno in range(lineno, len(lines)): 958 if lines[lineno].split('#', 1)[0].strip(): 959 api_doc.docstring_lineno = lineno + 1 960 return lineno + 1 961 except IOError: pass 962 except TypeError: pass 963 except IndexError: 964 log.warning('inspect.findsource(%s) raised IndexError' 965 % api_doc.canonical_name) 966 return None

967

968 -class _DevNull:

969 """ 970 A "file-like" object that discards anything that is written and 971 always reports end-of-file when read. C{_DevNull} is used by 972 L{_import()} to discard output when importing modules; and to 973 ensure that stdin appears closed. 974 """

975 - def __init__(self):

976 self.closed = 1 977 self.mode = 'r+' 978 self.softspace = 0 979 self.name='</dev/null>'

980 - def close(self): pass

981 - def flush(self): pass

982 - def read(self, size=0): return ''

983 - def readline(self, size=0): return ''

984 - def readlines(self, sizehint=0): return []

985 - def seek(self, offset, whence=0): pass

986 - def tell(self): return 0L

987 - def truncate(self, size=0): pass

988 - def write(self, str): pass

989 - def writelines(self, sequence): pass

990 xreadlines = readlines

991 _dev_null = _DevNull() 992 993 ###################################################################### 994 ## Zope InterfaceClass 995 ###################################################################### 996 997 try: 998 from zope.interface.interface import InterfaceClass as _ZopeInterfaceClass 999 register_class_type(_ZopeInterfaceClass) 1000 except: 1001 pass 1002 1003 ###################################################################### 1004 ## Zope Extension classes 1005 ###################################################################### 1006 1007 try: 1008 # Register type(ExtensionClass.ExtensionClass) 1009 from ExtensionClass import ExtensionClass as _ExtensionClass 1010 _ZopeType = type(_ExtensionClass)

1011 - def _is_zope_type(val):

1012 return isinstance(val, _ZopeType)

1013 register_introspecter(_is_zope_type, introspect_class) 1014 1015 # Register ExtensionClass.*MethodType 1016 from ExtensionClass import PythonMethodType as _ZopeMethodType 1017 from ExtensionClass import ExtensionMethodType as _ZopeCMethodType

1018 - def _is_zope_method(val):

1019 return isinstance(val, (_ZopeMethodType, _ZopeCMethodType))

1020 register_introspecter(_is_zope_method, introspect_routine) 1021 except: 1022 pass 1023 1024 1025 1026 1027 # [xx] 1028 0 # hm.. otherwise the following gets treated as a docstring! ouch! 1029 """ 1030 ###################################################################### 1031 ## Zope Extension... 1032 ###################################################################### 1033 class ZopeIntrospecter(Introspecter): 1034 VALUEDOC_CLASSES = Introspecter.VALUEDOC_CLASSES.copy() 1035 VALUEDOC_CLASSES.update({ 1036 'module': ZopeModuleDoc, 1037 'class': ZopeClassDoc, 1038 'interface': ZopeInterfaceDoc, 1039 'attribute': ZopeAttributeDoc, 1040 }) 1041 1042 def add_module_child(self, child, child_name, module_doc): 1043 if isinstance(child, zope.interfaces.Interface): 1044 module_doc.add_zope_interface(child_name) 1045 else: 1046 Introspecter.add_module_child(self, child, child_name, module_doc) 1047 1048 def add_class_child(self, child, child_name, class_doc): 1049 if isinstance(child, zope.interfaces.Interface): 1050 class_doc.add_zope_interface(child_name) 1051 else: 1052 Introspecter.add_class_child(self, child, child_name, class_doc) 1053 1054 def introspect_zope_interface(self, interface, interfacename): 1055 pass # etc... 1056 """ 1057

Source Code for Module epydoc.docintrospecter