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