Home       Trees       Index       Help   

epydoc 3.0alpha2

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

Module docintrospecter
source code

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

DocIntrospecter is a processing class that examines Python objects via introspection, and uses the information it finds to create APIDoc objects containing the API documentation for those objects.

DocIntrospecter can be subclassed to extend the set of object types that it supports.

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]
  introspect_docs(value=None, name=None, filename=None, context=None, is_script=False)
Generate the API documentation for a specified object by introspecting Python values, and return it as a ValueDoc.
  _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.
  introspect_module(module, module_doc, preliminary=False)
Add API documentation information about the module module to module_doc.
  introspect_class(cls, class_doc)
Add API documentation information about the class cls to class_doc.
  introspect_routine(routine, routine_doc)
Add API documentation information about the function routine to routine_doc (specializing it to Routine_doc).
  introspect_property(prop, prop_doc)
Add API documentation information about the property prop to prop_doc (specializing it to PropertyDoc).
  introspect_other(val, val_doc)
Specialize val_doc to a GenericValueDoc and return it.
unicode get_docstring(value)
Return the docstring for the given value; or None if it does not have a docstring.
DottedName or None get_canonical_name(value)
  verify_name(value, dotted_name)
Verify the name.
  value_repr(value)
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.
module _find_function_module(func)
  register_introspecter(applicability_test, introspecter, priority=10)
Register an introspecter function.
  _get_introspecter(value)
  is_classmethod(v)
  is_staticmethod(v)
  is_property(v)
  get_value_from_filename(filename, context=None)
  get_value_from_scriptname(filename)
  get_value_from_name(name, globs=None)
Given a name, return the corresponding value.
  _lookup(module, name)
  _import(name, filename=None)
Run the given callable in a 'sandboxed' environment.
  introspect_docstring_lineno(api_doc)
Try to determine the line number on which the given item's docstring begins.

Variables [hide private]
_valuedoc_cache A cache containing the API documentation for values that we've already seen.
_introspected_values A record which values we've introspected, encoded as a dictionary from pyid to bool.
UNDOCUMENTED_MODULE_VARS A list of module variables that should not be included in a module's API documentation.
UNDOCUMENTED_CLASS_VARS A list of class variables that should not be included in a class's API documentation.
_introspecter_registry  
_dev_null  

Function Details [hide private]

introspect_docs(value=None, name=None, filename=None, context=None, is_script=False)

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).

_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.

introspect_module(module, module_doc, preliminary=False)

source code 
call graph 
Add API documentation information about the module module to module_doc.

introspect_class(cls, class_doc)

source code 
call graph 
Add API documentation information about the class cls to class_doc.

introspect_routine(routine, routine_doc)

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

introspect_property(prop, prop_doc)

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

introspect_other(val, val_doc)

source code 
call graph 
Specialize val_doc to a GenericValueDoc and return it.

get_docstring(value)

source code 
call graph 
Return the docstring for the given value; or None if it does not have a docstring.
Returns: unicode

get_canonical_name(value)

source code 
call graph 
Returns: DottedName or None
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.

value_repr(value)

source code 

get_containing_module(value)

source code 
call graph 
Return the name of the module containing the given value, or None if the module name can't be determined.
Returns: DottedName

_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_introspecter(value)

source code 
call graph 

is_classmethod(v)

source code 

is_staticmethod(v)

source code 

is_property(v)

source code 
call graph 

get_value_from_filename(filename, context=None)

source code 
call graph 

get_value_from_scriptname(filename)

source code 

get_value_from_name(name, globs=None)

source code 
Given a name, return the corresponding value.
Parameters:
  • globals - A namespace to check for the value, if there is no module containing the named value. Defaults to __builtin__.

_lookup(module, name)

source code 

_import(name, filename=None)

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 
call graph 
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:
{1075604140: <RoutineDoc dict.popitem>,
 1076055932: <RoutineDoc epydoc.markup.Field.arg>,
 1077821472: <GenericValueDoc epydoc.gui.RIDGE>,
 1078997436: <GenericValueDoc xml.dom.minidom.NamedNodeMap.__slots__>,
 1094678428: <RoutineDoc epydoc.markup.epytext.ParsedEpytextDocstring.\
_to_html>,
 1094887380: <RoutineDoc docutils.nodes.Element.replace>,
 1094896748: <ValueDoc docutils.utils.new_document>,
...

_introspected_values

A record which values we've introspected, encoded as a dictionary from pyid to bool.
Value:
{1075437612: True,
 1076055932: True,
 1077821472: True,
 1093798572: True,
 1094678428: True,
 1094887380: True,
 1094920932: True,
 1094926660: 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__')

_introspecter_registry

Value:
[(20,
  <function ismodule at 0x4021d0d4>,
  <function introspect_module at 0x4024f80c>),
 (24,
  <function isclass at 0x4021d10c>,
  <function introspect_class at 0x4024f844>),
 (28,
  <function isroutine at 0x4021d304>,
...

_dev_null

Value:
<epydoc.docintrospecter._DevNull instance at 0x4024634c>

   Home       Trees       Index       Help   

epydoc 3.0alpha2

Generated by Epydoc 3.0alpha2 on Tue Apr 11 17:30:11 2006 http://epydoc.sf.net