epydoc.objdoc

Package epydoc :: Module objdoc

[show private | hide private]

Module epydoc.objdoc

Support for ObjDocs, which encode the information about a Python object that is necessary to create its documentation. ObjDocs are created and managed by the DocMap class, which acts like a dictionary from UIDs to ObjDocs.

Textual documentation entries (e.g., module descriptions, method descriptions, variable types, see-also entries) are encoded as ParsedDocstrings.

Each Python object is identified by a globally unique identifier, implemented with the UID class. These identifiers are also used by the Link class to implement crossreferencing between ObjDocs.

Classes
`ClassDoc`	The documentation for a class.
`DocField`	A generic docstring field.
`DocMap`	A dictionary mapping each object to the object's documentation.
`FuncDoc`	The documentation for a function.
`ModuleDoc`	The documentation for a module or package.
`ObjDoc`	A base class for encoding the information about a Python object that is necessary to create its documentation.
`Param`	The documentation for a function parameter.
`PropertyDoc`	The documentation for a property.
`Raise`	The documentation for the raising of an exception.
`Var`	The documentation for a variable.

Function Summary
	`report_param_mismatches(docmap)`
`None`	`set_default_docformat(new_format)` Change the default value for `__docformat__` to the given value.
	`_ast_match(pattern, data, vars, indent)` Match `data` to `pattern`, with variable extraction.
	`_descr_to_docfield(arg, descr)`
`list` of `string`	`_descr_to_identifiers(descr)` Given a `ParsedDocstring` that contains a list of identifiers, return a list of those identifiers.
	`_dfs_bases(cls)`
`list` of `class`	`_find_base_order(cls)` Return a list of the base ancestors of `cls`, in the order that they should be searched for attributes.
`(string, int)` or `(None, None)`	`_find_docstring(uid)` Return the file name and line number of the docstring for the given object; or `None` if the docstring cannot be found.
	`_flatten(tree)` Recursively explore `tree`, and return an in-order list of all leaves.
	`_getdoc(obj)` Get the documentation string for an object.
	`_lookup_class_field(cls, field, base_order)` Find the value for a class's field by looking through its base order list, and using getattr to access the first base that contains the field.

Variable Summary
`str`	`DEFAULT_DOCFORMAT`: The default value for `__docformat__`, if it is not specified by modules.
`tuple`	`KNOWN_DOCFORMATS` = `('plaintext', 'epytext', 'restructure...`
`SRE_Pattern`	`_IDENTIFIER_LIST_REGEXP` = `^[\w\.\]+([\s,:;]\s[\w\.\*]+...`
`tuple`	`_KNOWN_FIELD_TAGS` = `('var', 'variable', 'ivar', 'ivariab...`

Function Details

set_default_docformat(new_format)

Change the default value for __docformat__ to the given value. The current default value for __docformat__ is recorded in DEFAULT_DOCFORMAT.

Parameters:: new_format - The new default value for __docformat__
(type=string)

Returns:: None

See Also: DEFAULT_DOCFORMAT

_ast_match(pattern, data, vars=None, indent=0)

Match data to pattern, with variable extraction.

The pattern value may contain variables of the form ['varname'] which are allowed to match anything. The value that is matched is returned as part of a dictionary which maps 'varname' to the matched value. 'varname' is not required to be a string object, but using strings makes patterns and the code which uses them more readable.

Parameters:: pattern - Pattern to match against, possibly containing variables.; data - Data to be checked and against which variables are extracted.; vars - Dictionary of variables which have already been found. If not provided, an empty dictionary is created.

Returns:: two values -- a boolean indicating whether a match was found and a dictionary mapping variable names to their associated values.

_descr_to_identifiers(descr)

Given a ParsedDocstring that contains a list of identifiers, return a list of those identifiers. This is used by fields such as @group and @sort, which expect lists of identifiers as their values. To extract the identifiers, the docstring is first converted to plaintext, and then split. The plaintext content of the docstring must be a a list of identifiers, separated by spaces, commas, colons, or semicolons.

Parameters:: descr - A ParsedDocstring containing a list of identifiers.
(type=markup.ParsedDocstring)

Returns:: A list of the identifier names contained in descr.
(type=list of string)

Raises:: ValueError - If descr does not contain a valid list of identifiers.

_find_base_order(cls)

Returns:: A list of the base ancestors of cls, in the order that they should be searched for attributes. Each base ancestor should be listed exactly once. The base order list includes the given class as its first element.
(type=list of class)

_find_docstring(uid)

Returns:: The file name and line number of the docstring for the given object; or None if the docstring cannot be found. Line numbers are indexed from zero (i.e., the first line's line number is 0).
(type=(string, int) or (None, None))

_flatten(tree)

Recursively explore tree, and return an in-order list of all leaves.

Parameters:: tree - The tree whose leaves should be returned. The tree structure of tree is represented by tuples and lists. In particular, every tuple or list contained in tree is considered a subtree; and any other element is considered a leaf.
(type=list or tuple)

Returns:: An in-order list of the leaves of tree.

_getdoc(obj)

Get the documentation string for an object. This function is similar to inspect.getdoc. In particular, it finds the minimum indentation fromthe second line onwards, and removes that indentation from each line. But it also checks to make sure that the docstring is actually a string (since some programs put other data in the docstrings).

Parameters:: obj - The object whose documentation string should be returned.
(type=any)

_lookup_class_field(cls, field, base_order=None)

Find the value for a class's field by looking through its base order list, and using getattr to access the first base that contains the field. Note that this is different from just using getattr directly, since for methods it will return a method of the base class, rather than a method of the given class. This is useful for constructing UIDs for class methods.

Returns:: A pair (val, container), where val is the value that was found; and container is the base that contains val.

Variable Details

DEFAULT_DOCFORMAT

The default value for __docformat__, if it is not specified by modules. __docformat__ is a module variable that specifies the markup language for the docstrings in a module. Its value is a string, consisting the name of a markup language, optionally followed by a language code (such as en for English). Some typical values for __docformat__ are:

>>> __docformat__ = 'plaintext'
>>> __docformat__ = 'epytext'
>>> __docformat__ = 'epytext en'

Type:: str
Value:: 'plaintext'

KNOWN_DOCFORMATS

Type:: tuple
Value:: ('plaintext', 'epytext', 'restructuredtext', 'javadoc')

_IDENTIFIER_LIST_REGEXP

Type:: SRE_Pattern
Value:: ^[\w\.\*]+([\s,:;]\s*[\w\.\*]+)*$

_KNOWN_FIELD_TAGS

Type:: tuple
Value:: ('var', 'variable', 'ivar', 'ivariable', 'cvar', 'cvariable', 'type', 'group', ...

Generated by Epydoc 2.1 on Sat Mar 20 17:46:19 2004

http://epydoc.sf.net