epydoc.docparser

Module docparser

Extract API documentation about python objects by parsing their source code.

The function parse_docs(), which provides the main interface of this module, reads and parses the Python source code for a module, and uses it to create an APIDoc object containing the API documentation for the variables and values defined in that modules.

Currently, parse_docs() extracts documentation from the following source code constructions:

module docstring

import statements

class definition blocks

function definition blocks

assignment statements

simple assignment statements
assignment statements with multiple '='s
assignment statements with unpacked left-hand sides
assignment statements that wrap a function in classmethod or staticmethod.
assignment to special variables __path__, __all__, and __docformat__.

delete statements

parse_docs() does not yet support the following source code constructions:

assignment statements that create properties

By default, parse_docs() will expore the contents of top-level try and if blocks. If desired, parse_docs() can also be configured to explore the contents of while and for blocks. (See the configuration constants, below.)

To Do: Make it possible to extend the functionality of parse_docs(), by replacing process_line with a dispatch table that can be customized (similarly to docintrospector.register_introspector()).

Classes

[hide private]

ParseError
An exception that is used to signify that docparser encountered syntactically invalid Python code while processing a Python source file.

Functions

[hide private]

Module parser

ValueDoc

parse_docs(filename=None, name=None, context=None, is_script=False)
Generate the API documentation for a specified object by parsing Python source files, and return it as a ValueDoc.

source code
call graph

_parse_package(package_dir)
If the given directory is a package directory, then parse its __init__.py file (and the __init__.py files of all ancestor packages); and return its ModuleDoc. source code
call graph

handle_special_module_vars(module_doc)

source code
call graph

_module_var_toktree(module_doc, name)

source code
call graph

Module Lookup

_find(name, package_doc=None)
Return the API documentaiton for the object whose name is name. source code
call graph

_is_submodule_import_var(module_doc, var_name)
Return true if var_name is the name of a variable in module_doc that just contains an imported_from link to a submodule of the same name. source code
call graph

_find_in_namespace(name, namespace_doc)

source code
call graph

_get_filename(identifier, path=None)

source code
call graph

File tokenization loop

process_file(module_doc)
Read the given ModuleDoc's file, and add variables corresponding to any objects defined in that file. source code
call graph

add_to_group(container, api_doc, group_name)

source code
call graph

script_guard(line)
Detect the idiomatic trick if __name__ == "__main__": source code
call graph

Shallow parser

shallow_parse(line_toks)
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).

source code
call graph

Line processing

process_line(line, parent_docs, prev_line_doc, lineno, comments, decorators, encoding)
Returns: new-doc, decorator..? source code
call graph

process_control_flow_line(line, parent_docs, prev_line_doc, lineno, comments, decorators, encoding)

source code
call graph

process_import(line, parent_docs, prev_line_doc, lineno, comments, decorators, encoding)

source code
call graph

process_from_import(line, parent_docs, prev_line_doc, lineno, comments, decorators, encoding)

source code
call graph

_process_fromstar_import(src, parent_docs)
Handle a statement of the form:

source code
call graph

_import_var(name, parent_docs)
Handle a statement of the form:

source code
call graph

_import_var_as(src, name, parent_docs)
Handle a statement of the form:

source code
call graph

_add_import_var(src, name, container)
Add a new imported variable named name to container, with imported_from=src. source code
call graph

_global_name(name, parent_docs)
If the given name is package-local (relative to the current context, as determined by parent_docs), then convert it to a global name. source code
call graph

process_assignment(line, parent_docs, prev_line_doc, lineno, comments, decorators, encoding)

source code
call graph

lhs_is_instvar(lhs_pieces, parent_docs)

source code
call graph

rhs_to_valuedoc(rhs, parent_docs, lineno)

source code
call graph

get_lhs_parent(lhs_name, parent_docs)

source code
call graph

process_one_line_block(line, parent_docs, prev_line_doc, lineno, comments, decorators, encoding)
The line handler for single-line blocks, such as:

source code
call graph

process_multi_stmt(line, parent_docs, prev_line_doc, lineno, comments, decorators, encoding)
The line handler for semicolon-separated statements, such as:

source code
call graph

process_del(line, parent_docs, prev_line_doc, lineno, comments, decorators, encoding)
The line handler for delete statements, such as:

source code
call graph

process_docstring(line, parent_docs, prev_line_doc, lineno, comments, decorators, encoding)
The line handler for bare string literals.

source code
call graph

process_funcdef(line, parent_docs, prev_line_doc, lineno, comments, decorators, encoding)
The line handler for function declaration lines, such as:

source code
call graph

apply_decorator(decorator_name, func_doc, parent_docs, lineno)

source code
call graph

init_arglist(func_doc, arglist)

source code
call graph

process_classdef(line, parent_docs, prev_line_doc, lineno, comments, decorators, encoding)
The line handler for class declaration lines, such as:

source code
call graph

_proxy_base(**attribs)

source code
call graph

find_base(name, parent_docs)

source code
call graph

process_append_to_all(line, parent_docs, prev_line_doc, lineno, comments, decorators, encoding)
The line handler for __all__.append() lines; either of:

source code

append_to_all(name, parent_docs, lineno)

source code

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

source code

Parsing

dotted_names_in(elt_list)
Return a list of all simple dotted names in the given expression.

source code
call graph

parse_name(elt, strip_parens=False)
If the given token tree element is a name token, then return that name as a string.

source code
call graph

parse_dotted_name(elt_list, strip_parens=True, parent_name=None)

source code
call graph

split_on(elt_list, split_tok)

source code
call graph

parse_funcdef_arg(elt)
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.

source code
call graph

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

source code
call graph

parse_dotted_name_list(elt_list)
If the given list of tree token elements contains a comma-separated list of dotted names, then return a corresponding list of DottedName objects.

source code

parse_string(elt_list)

source code
call graph

parse_string_list(elt_list, require_sequence=False)

source code
call graph

Variable Manipulation

set_variable(namespace, var_doc, preserve_docstring=False)
Add var_doc to namespace.

source code
call graph

del_variable(namespace, name)

source code
call graph

Name Lookup

VariableDoc or None

lookup_name(identifier, parent_docs)
Find and return the documentation for the variable named by the given identifier.

source code
call graph

lookup_variable(dotted_name, parent_docs)

source code
call graph

lookup_value(dotted_name, parent_docs)
Find and return the documentation for the value contained in the variable with the given name in the current namespace.

source code
call graph