Package epydoc :: Module docintrospecter |
[hide private]
[frames] | no frames]

# Module docintrospecter

source code

Extract API documentation about python objects by directly introspecting their values.

The function introspect_docs(), which provides the main interface of this module, examines a Python objects via introspection, and uses the information it finds to create an APIDoc objects containing the API documentation for that objects.

The register_introspecter() method can be used to extend the functionality of `docintrospector`, by providing methods that handle special value types.

Classes | [hide private]
| _DevNull A "file-like" object that discards anything that is written and always reports end-of-file when read.

Functions | [hide private]
clear_cache() Discard any cached `APIDoc` values that have been computed for introspected values. | source code
introspect_docs(value=None, name=None, filename=None, context=None, is_script=False, module_name=None) Generate the API documentation for a specified object by introspecting Python values, and return it as a ValueDoc. | source code call graph
Call Graph
_get_valuedoc(value) If a `ValueDoc` for the given value exists in the valuedoc cache, then return it; otherwise, create a new `ValueDoc`, add it to the cache, and return it. | source code call graph
Call Graph
introspect_module(module, module_doc, module_name=None, preliminary=False) Add API documentation information about the module `module` to `module_doc`. | source code call graph
Call Graph
introspect_class(cls, class_doc, module_name=None) Add API documentation information about the class `cls` to `class_doc`. | source code call graph
Call Graph
introspect_routine(routine, routine_doc, module_name=None) Add API documentation information about the function `routine` to `routine_doc` (specializing it to `Routine_doc`). | source code call graph
Call Graph
introspect_property(prop, prop_doc, module_name=None) Add API documentation information about the property `prop` to `prop_doc` (specializing it to `PropertyDoc`). | source code call graph
Call Graph
introspect_other(val, val_doc, module_name=None) Specialize val_doc to a `GenericValueDoc` and return it. | source code call graph
Call Graph
isclass(object) Return true if the given object is a class. | source code call graph
Call Graph
register_class_type(typ) Add a type to the lists of types that should be treated as classes. | source code
is_future_feature(object) Return True if `object` results from a `from __future__ import feature` statement. | source code call graph
Call Graph
`unicode` |
get_docstring(value, module_name=None) Return the docstring for the given value; or `None` if it does not have a docstring. | source code call graph
Call Graph
DottedName or `UNKNOWN` |
get_canonical_name(value, strict=False) Returns: the canonical name for `value`, or `UNKNOWN` if no canonical name can be found. | source code call graph
Call Graph
verify_name(value, dotted_name) Verify the name. | source code call graph
Call Graph
value_repr(value) | source code
DottedName |
get_containing_module(value) Return the name of the module containing the given value, or `None` if the module name can't be determined. | source code call graph
Call Graph
`module` |
_find_function_module(func) Returns: The module that defines the given function. | source code call graph
Call Graph
register_introspecter(applicability_test, introspecter, priority=10) Register an introspecter function. | source code
_get_introspecter(value) | source code call graph
Call Graph
is_classmethod(v) | source code
is_staticmethod(v) | source code
is_property(v) | source code call graph
Call Graph
is_getset(v) | source code call graph
Call Graph
is_member(v) | source code call graph
Call Graph
get_value_from_filename(filename, context=None) | source code call graph
Call Graph
get_value_from_scriptname(filename) | source code
get_value_from_name(name, globs=None) Given a name, return the corresponding value. | source code
_lookup(module, name) | source code
_import(name, filename=None) Run the given callable in a 'sandboxed' environment. | source code call graph
Call Graph
introspect_docstring_lineno(api_doc) Try to determine the line number on which the given item's docstring begins. | source code
_is_zope_type(val) | source code
_is_zope_method(val) | source code

Variables | [hide private]
| _valuedoc_cache = ``{`135394656`:` <ValueDoc epydoc.docintrospecter`...`` A cache containing the API documentation for values that we've already seen.
| _introspected_values = ``{`135396096`:` True`,` 135400544`:` True`,` 1354`...`` A record which values we've introspected, encoded as a dictionary from pyid to `bool`.
| UNDOCUMENTED_MODULE_VARS = ``(``'``__builtins__``'``,` `'``__doc__``'``,` `'``__all_``...`` A list of module variables that should not be included in a module's API documentation.
| UNDOCUMENTED_CLASS_VARS = ``(``'``__doc__``'``,` `'``__module__``'``,` `'``__dict__``'``...`` A list of class variables that should not be included in a class's API documentation.
| _CLASS_TYPES = ``set([`<type 'classobj'>`,` <type 'type'>`])`` A list of types that should be treated as classes.
| __future_check_works = `True`
| _introspecter_registry = `[]`
| _dev_null = `sys.stdout`
| _ZopeType = `type(_ExtensionClass)`

Function Details | [hide private]

### introspect_docs(value=None, name=None, filename=None, context=None, is_script=False, module_name=None) | source code call graph
Call Graph
Generate the API documentation for a specified object by introspecting Python values, and return it as a ValueDoc. The object to generate documentation for may be specified using the `value` parameter, the `filename` parameter, or the `name` parameter. (It is an error to specify more than one of these three parameters, or to not specify any of them.) Parameters: `value` - The python object that should be documented. `filename` - The name of the file that contains the python source code for a package, module, or script. If `filename` is specified, then `introspect` will return a `ModuleDoc` describing its contents. `name` - The fully-qualified python dotted name of any value (including packages, modules, classes, and functions). `DocParser` will automatically figure out which module(s) it needs to import in order to find the documentation for the specified object. `context` - The API documentation for the class of module that contains `value` (if available). `module_name` - The name of the module where the value is defined. Useful to retrieve the docstring encoding if there is no way to detect the module by introspection (such as in properties)

### _get_valuedoc(value) | source code call graph
Call Graph
If a `ValueDoc` for the given value exists in the valuedoc cache, then return it; otherwise, create a new `ValueDoc`, add it to the cache, and return it. When possible, the new `ValueDoc`'s `pyval`, `repr`, and `canonical_name` attributes will be set appropriately.

### isclass(object) | source code call graph
Call Graph
Return true if the given object is a class. In particular, return true if object is an instance of `types.TypeType` or of `types.ClassType`. This is used instead of `inspect.isclass()`, because the latter returns true for objects that are not classes (in particular, it returns true for any object that has a `__bases__` attribute, including objects that define `__getattr__` to always return a value).

### register_class_type(typ) | source code
Add a type to the lists of types that should be treated as classes. By default, this list contains `TypeType` and `ClassType`.

### get_canonical_name(value, strict=False) | source code call graph
Call Graph
Returns: DottedName or `UNKNOWN` the canonical name for `value`, or `UNKNOWN` if no canonical name can be found. Currently, `get_canonical_name` can find canonical names for: modules; functions; non-nested classes; methods of non-nested classes; and some class methods of non-nested classes.

### verify_name(value, dotted_name) | source code call graph
Call Graph
Verify the name. E.g., if it's a nested class, then we won't be able to find it with the name we constructed.

### _find_function_module(func) | source code call graph
Call Graph
Parameters: `func` (`function`) - The function whose module should be found. Returns: `module` The module that defines the given function.

### register_introspecter(applicability_test, introspecter, priority=10) | source code
Register an introspecter function. Introspecter functions take two arguments, a python value and a `ValueDoc` object, and should add information about the given value to the the `ValueDoc`. Usually, the first line of an inspecter function will specialize it to a sublass of `ValueDoc`, using ValueDoc.specialize_to():
    >>> def typical_introspecter(value, value_doc):
    ...     value_doc.specialize_to(SomeSubclassOfValueDoc)
    ...     <add info to value_doc>
Parameters: `priority` - The priority of this introspecter, which determines the order in which introspecters are tried -- introspecters with lower numbers are tried first. The standard introspecters have priorities ranging from 20 to 30. The default priority (10) will place new introspecters before standard introspecters.

### get_value_from_name(name, globs=None) | source code
Given a name, return the corresponding value. Parameters: `globs` - A namespace to check for the value, if there is no module containing the named value. Defaults to __builtin__.

### _import(name, filename=None) | source code call graph
Call Graph
Run the given callable in a 'sandboxed' environment. Currently, this includes saving and restoring the contents of sys and __builtins__; and suppressing stdin, stdout, and stderr.

### introspect_docstring_lineno(api_doc) | source code
Try to determine the line number on which the given item's docstring begins. Return the line number, or `None` if the line number can't be determined. The line number of the first line in the file is 1.

Variables Details | [hide private]

  ### _valuedoc_cache A cache containing the API documentation for values that we've already seen. This cache is implemented as a dictionary that maps a value's pyid to its ValueDoc. Note that if we encounter a value but decide not to introspect it (because it's imported from another module), then `_valuedoc_cache` will contain an entry for the value, but the value will not be listed in _introspected_values. Value:
      {135394656: <ValueDoc epydoc.docintrospecter.ClassType>,
       135394848: <ValueDoc epydoc.docintrospecter.InstanceType>,
       135395040: <ValueDoc epydoc.docintrospecter.MethodType>,
       135396096: <ClassDoc file>,
       135400544: <ClassDoc float>,
       135401088: <ClassDoc int>,
       135402368: <ClassDoc list>,
       135404832: <ClassDoc long>,
      ...

  ### _introspected_values A record which values we've introspected, encoded as a dictionary from pyid to `bool`. Value:
      {135396096: True,
       135400544: True,
       135401088: True,
       135402368: True,
       135404832: True,
       135405600: True,
       135408504: True,
       135408512: True,
      ...

  ### UNDOCUMENTED_MODULE_VARS A list of module variables that should not be included in a module's API documentation. Value:
      ('__builtins__',
       '__doc__',
       '__all__',
       '__file__',
       '__path__',
       '__name__',
       '__extra_epydoc_fields__',
       '__docformat__')

  ### UNDOCUMENTED_CLASS_VARS A list of class variables that should not be included in a class's API documentation. Value:
      ('__doc__',
       '__module__',
       '__dict__',
       '__weakref__',
       '__slots__',
       '__pyx_vtable__')