Package epydoc :: Module docintrospecter

Module docintrospecter

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=True, name=True, filename=True, context=True, is_script=True, module_name=True)
Generate the API documentation for a specified object by introspecting Python values, and return it as a ValueDoc.

source code
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

introspect_module(module, module_doc, module_name=True, preliminary=True)
Add API documentation information about the module module to module_doc. source code
call graph

introspect_class(cls, class_doc, module_name=True)
Add API documentation information about the class cls to class_doc. source code
call graph

introspect_routine(routine, routine_doc, module_name=True)
Add API documentation information about the function routine to routine_doc (specializing it to Routine_doc). source code
call graph

introspect_property(prop, prop_doc, module_name=True)
Add API documentation information about the property prop to prop_doc (specializing it to PropertyDoc). source code
call graph

introspect_other(val, val_doc, module_name=True)
Specialize val_doc to a GenericValueDoc and return it. source code
call graph

isclass(object)
Return true if the given object is a class.

source code
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

unicode

get_docstring(value, module_name=True)
Return the docstring for the given value; or None if it does not have a docstring. source code
call graph

DottedName or UNKNOWN

get_canonical_name(value)
Returns: the canonical name for value, or UNKNOWN if no canonical name can be found. source code
call graph

verify_name(value, dotted_name)
Verify the name.

source code
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

module

_find_function_module(func)
Returns: The module that defines the given function.

source code
call graph

register_introspecter(applicability_test, introspecter, priority=10)
Register an introspecter function.

source code

_get_introspecter(value)

source code
call graph

is_classmethod(v)

source code

is_staticmethod(v)

source code

is_property(v)

source code
call graph

is_getset(v)

source code
call graph

is_member(v)

source code
call graph

get_value_from_filename(filename, context=True)

source code
call graph

get_value_from_scriptname(filename)

source code

get_value_from_name(name, globs=True)
Given a name, return the corresponding value.

source code

_lookup(module, name)

source code

_import(name, filename=True)
Run the given callable in a 'sandboxed' environment.

source code
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 = {135484864: <ClassDoc bool>, 135485056: <Gen...
A cache containing the API documentation for values that we've already seen.

_introspected_values = {135484864: True, 135485056: 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=True, name=True, filename=True, context=True, is_script=True, module_name=True)

source code
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

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

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)

source code
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

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

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=True)

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=True)

source code
call graph

Run the given callable in a 'sandboxed' environment. Currently, this includes saving and restoring the contents of sys and __builtins__; and supressing 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:

{135484864: <ClassDoc bool>,
 135485056: <GenericValueDoc None>,
 135485068: <GenericValueDoc None>,
 135485248: <ValueDoc epydoc.docintrospecter.ClassType>,
 135485856: <ValueDoc epydoc.docintrospecter.InstanceType>,
 135486304: <ValueDoc epydoc.docintrospecter.MethodType>,
 135487072: <ClassDoc exceptions.BaseException>,
 135487296: <ClassDoc exceptions.Exception>,
...

_introspected_values

A record which values we've introspected, encoded as a dictionary from pyid to bool.

Value:

{135484864: True,
 135485056: True,
 135485068: True,
 135487072: True,
 135487296: True,
 135487520: True,
 135487744: True,
 135487968: 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__')