Module docparser

Call Graph

Generate the API documentation for a specified object by parsing Python source files, and return it as a ValueDoc. The object to generate documentation for may be specified using the filename parameter or the name parameter. (It is an error to specify both a filename and a name; or to specify neither a filename nor a name).

Parameters:

• filename - The name of the file that contains the python source code for a package, module, or script. If filename is specified, then parse will return a ModuleDoc describing its contents.
• name - The fully-qualified python dotted name of any value (including packages, modules, classes, and functions). parse_docs() will automatically figure out which module(s) it needs to parse in order to find the documentation for the specified object.
• context - The API documentation for the package that contains filename. If no context is given, then filename is assumed to contain a top-level module or package. It is an error to specify a context if the name argument is used.

Returns: ValueDoc

Call Graph

Read the given ModuleDoc's file, and add variables corresponding to any objects defined in that file. In particular, read and tokenize module_doc.filename, and process each logical line using process_line().

Call Graph

Given a flat list of tokens, return a nested tree structure (called a token tree), whose leaves are identical to the original list, but whose structure reflects the structure implied by the grouping tokens (i.e., parenthases, braces, and brackets). If the parenthases, braces, and brackets do not match, or are not balanced, then raise a ParseError.

Assign some structure to a sequence of structure (group parens).

Call Graph

Returns:

new-doc, decorator..?

Call Graph

The line handler for single-line blocks, such as:

>>> def f(x): return x*2

This handler calls process_line twice: once for the tokens up to and including the colon, and once for the remaining tokens. The comment docstring is applied to the first line only.

Returns:

None

Call Graph

The line handler for semicolon-separated statements, such as:

>>> x=1; y=2; z=3

This handler calls process_line once for each statement. The comment docstring is not passed on to any of the sub-statements.

Returns:

None

Call Graph

The line handler for delete statements, such as:

>>> del x, y.z

This handler calls del_variable for each dotted variable in the variable list. The variable list may be nested. Complex expressions in the variable list (such as x[3]) are ignored.

Returns:

None

Call Graph

The line handler for bare string literals. If prev_line_doc is not None, then the string literal is added to that APIDoc as a docstring. If it already has a docstring (from comment docstrings), then the new docstring will be appended to the old one.

Call Graph

The line handler for function declaration lines, such as:

>>> def f(a, b=22, (c,d)):

This handler creates and initializes a new VariableDoc containing a RoutineDoc, adds the VariableDoc to the containing namespace, and returns the RoutineDoc.

Call Graph

The line handler for class declaration lines, such as:

>>> class Foo(Bar, Baz):

This handler creates and initializes a new VariableDoc containing a ClassDoc, adds the VariableDoc to the containing namespace, and returns the ClassDoc.

The line handler for __all__.append() lines; either of:

>>> __all__.append('name')
>>> __all__ += ['name']

This handler looks up the value of the variable __all__ in parent_docs; and if it is found, and has a list-of-strings value, the handler appends the new name.

Check if a line is an __all__.append line()

Call Graph

If the given token tree element is a name token, then return that name as a string. Otherwise, raise ParseError.

Parameters:

• strip_parens - If true, then if elt is a single name enclosed in parenthases, then return that name.

Call Graph

Parameters:

• parent_name (DottedName) - canonical name of referring module, to resolve relative imports.

Call Graph

If the given tree token element contains a valid function definition argument (i.e., an identifier token or nested list of identifiers), then return a corresponding string identifier or nested list of string identifiers. Otherwise, raise a ParseError.

Call Graph

If the given tree token element contains a valid base list (that contains only dotted names), then return a corresponding list of DottedNames. Otherwise, raise a ParseError.

   - class A( (base.in.parens) ): pass
   - class B( (lambda:calculated.base)() ): pass

If the given list of tree token elements contains a comma-separated list of dotted names, then return a corresponding list of DottedName objects. Otherwise, raise ParseError.

Call Graph

Add var_doc to namespace. If namespace already contains a variable with the same name, then discard the old variable. If preserve_docstring is true, then keep the old variable's docstring when overwriting a variable.

Parameters:

• lst - The nested list that should be flattened.

Returns:

a flat list containing the leaves of the given nested list.

IMPORT_HANDLING

What should docparser do when it encounters an import statement?

• 'link': Create variabledoc objects with imported_from pointers to the source object.
• 'parse': Parse the imported file, to find the actual documentation for the imported object. (This will fall back to the 'link' behavior if the imported file can't be parsed, e.g., if it's a builtin.)

Value:

'link'

IMPORT_STAR_HANDLING

When docparser encounters a 'from m import *' statement, and is unable to parse m (either because IMPORT_HANDLING='link', or because parsing failed), how should it determine the list of identifiers expored by m?

• 'ignore': ignore the import statement, and don't create any new variables.
• 'parse': parse it to find a list of the identifiers that it exports. (This will fall back to the 'ignore' behavior if the imported file can't be parsed, e.g., if it's a builtin.)
• 'introspect': import the module and introspect it (using dir) to find a list of the identifiers that it exports. (This will fall back to the 'ignore' behavior if the imported file can't be parsed, e.g., if it's a builtin.)

Value:

'parse'

DEFAULT_DECORATOR_BEHAVIOR

When DocParse encounters an unknown decorator, what should it do to the documentation of the decorated function?

• 'transparent': leave the function's documentation as-is.
• 'opaque': replace the function's documentation with an empty ValueDoc object, reflecting the fact that we have no knowledge about what value the decorator returns.

Value:

'transparent'

BASE_HANDLING

What should docparser do when it encounters a base class that was imported from another module?

• 'link': Create a valuedoc with a proxy_for pointer to the base class.
• 'parse': Parse the file containing the base class, to find the actual documentation for it. (This will fall back to the 'link' behavior if the imported file can't be parsed, e.g., if it's a builtin.)

Value:

'parse'

START_GROUP_MARKER

The prefix used to mark a comment that starts a group. This marker should be followed (on the same line) by the name of the group. Following a start-group comment, all variables defined at the same indentation level will be assigned to this group name, until the parser reaches the end of the file, a matching end-group comment, or another start-group comment at the same indentation level.

Value:

'#{'

END_GROUP_MARKER

The prefix used to mark a comment that ends a group. See START_GROUP_MARKER.

Value:

'#}'

CONTROL_FLOW_KEYWORDS

A list of the control flow keywords. If a line begins with one of these keywords, then it should be handled by process_control_flow_line.

Value:

['if', 'elif', 'else', 'while', 'for', 'try', 'except', 'finally']