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=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__')