Package epydoc :: Module docstringparser

Module docstringparser

Parse docstrings and handle any fields it defines, such as @type and @author. Fields are used to describe specific information about an object. There are two classes of fields: simple fields and special fields.

Simple fields are fields that get stored directly in an APIDoc's metadata dictionary, without any special processing. The set of simple fields is defined by the list STANDARD_FIELDS, whose elements are DocstringFields.

Special fields are fields that perform some sort of processing on the APIDoc, or add information to attributes other than the metadata dictionary. Special fields are are handled by field handler functions, which are registered using register_field_handler.

Classes

[hide private]

DocstringField
A simple docstring field, which can be used to describe specific information about an object, such as its author or its version.

Functions

[hide private]

Docstring Parsing

parse_docstring(api_doc, docindex)
Process the given APIDoc's docstring. source code
call graph

add_metadata_from_var(api_doc, field)

source code
call graph

initialize_api_doc(api_doc)
A helper function for parse_docstring() that initializes the attributes that parse_docstring() will write to. source code
call graph

list of markup.Field

split_init_fields(fields, warnings)
Remove the fields related to the constructor from a class docstring fields list.

source code
call graph

report_errors(api_doc, docindex, parse_errors, field_warnings)
A helper function for parse_docstring() that reports any markup warnings and field warnings that we encountered while processing api_doc's docstring. source code
call graph

Field Processing

process_field(api_doc, docindex, tag, arg, descr)
Process a single field, and use it to update api_doc. source code
call graph

user_docfields(api_doc, docindex)
Return a list of user defined fields that can be used for the given object.

source code
call graph

register_field_handler(handler, *field_tags)
Register the given field handler function for processing any of the given field tags.

source code

Field Handler Functions

process_summary_field(api_doc, docindex, tag, arg, descr)
Store descr in api_doc.summary source code

process_include_field(api_doc, docindex, tag, arg, descr)
Copy the docstring contents from the object named in descr source code

process_undocumented_field(api_doc, docindex, tag, arg, descr)
Remove any documentation for the variables named in descr source code

process_group_field(api_doc, docindex, tag, arg, descr)
Define a group named arg containing the variables whose names are listed in descr. source code
call graph

process_deffield_field(api_doc, docindex, tag, arg, descr)
Define a new custom field.

source code
call graph

process_raise_field(api_doc, docindex, tag, arg, descr)
Record the fact that api_doc can raise the exception named tag in api_doc.exception_descrs. source code
call graph

process_sort_field(api_doc, docindex, tag, arg, descr)

source code
call graph

process_type_field(api_doc, docindex, tag, arg, descr)

source code
call graph

process_var_field(api_doc, docindex, tag, arg, descr)

source code
call graph

process_cvar_field(api_doc, docindex, tag, arg, descr)

source code
call graph

process_ivar_field(api_doc, docindex, tag, arg, descr)

source code
call graph

process_return_field(api_doc, docindex, tag, arg, descr)

source code
call graph

process_rtype_field(api_doc, docindex, tag, arg, descr)

source code
call graph

process_arg_field(api_doc, docindex, tag, arg, descr)

source code
call graph

process_kwarg_field(api_doc, docindex, tag, arg, descr)

source code
call graph

Helper Functions

check_type_fields(api_doc, field_warnings)
Check to make sure that all type fields correspond to some documented parameter; if not, append a warning to field_warnings.

source code
call graph

set_var_descr(api_doc, ident, descr)

source code
call graph

set_var_type(api_doc, ident, descr)

source code
call graph

_check(api_doc, tag, arg, context=True, expect_arg=True)

source code
call graph

get_docformat(api_doc, docindex)
Return the name of the markup language that should be used to parse the API documentation for the given object.

source code
call graph

unindent_docstring(docstring)

source code
call graph

list of string

_descr_to_identifiers(descr)
Given a ParsedDocstring that contains a list of identifiers, return a list of those identifiers. source code
call graph

_descr_to_docstring_field(arg, descr)

source code
call graph

Function Signature Extraction

None

parse_function_signature(func_doc, doc_source=True)
Construct the signature for a builtin function or method from its docstring.

source code
call graph

Variables

[hide private]

STANDARD_FIELDS = [<Field: deprecated>, <Field: version>, <Fie...
A list of the standard simple fields accepted by epydoc.

Docstring Parsing

DEFAULT_DOCFORMAT = 'plaintext'
The name of the default markup languge used to process docstrings.

RETURN_PDS = markup.parse('Returns:', markup= 'epytext')
A ParsedDocstring containing the text 'Returns'.

Field Processing Error Messages

UNEXPECTED_ARG = '%r did not expect an argument'

EXPECTED_ARG = '%r expected an argument'

EXPECTED_SINGLE_ARG = '%r expected a single argument'

BAD_CONTEXT = 'Invalid context for %r'

REDEFINED = 'Redefinition of %s'

UNKNOWN_TAG = 'Unknown field tag %r'

BAD_PARAM = '@%s for unknown parameter %s'

Field Processing

_field_dispatch_table = {}

Field Handler Functions

PARAMETER_TAGS = ('arg', 'argument', 'parameter', 'param', 'kw...

VARIABLE_TAGS = ('cvar', 'cvariable', 'ivar', 'ivariable')

EXCEPTION_TAGS = ('raise', 'raises', 'except', 'exception')

Helper Functions

_IDENTIFIER_LIST_REGEXP = re.compile(r'^[\w\.\*]+([\s,:;]\s*[\...

Function Signature Extraction

_SIGNATURE_RE = re.compile(r'^\s*((?P<self>\w+)\.)?(?P<func>\w...
A regular expression that is used to extract signatures from docstrings.

Function Details

[hide private]

parse_docstring(api_doc, docindex)

source code
call graph

Process the given APIDoc's docstring. In particular, populate the APIDoc's descr and summary attributes, and add any information provided by fields in the docstring.

Parameters:

docindex - A DocIndex, used to find the containing module (to look up the docformat); and to find any user docfields defined by containing objects.

split_init_fields(fields, warnings)

source code
call graph

Remove the fields related to the constructor from a class docstring fields list.

Parameters:

fields (list of markup.Field) - The fields to process. The list will be modified in place
warnings (list) - A list to emit processing warnings

Returns: list of markup.Field

The fields items to be applied to the __init__ method

process_field(api_doc, docindex, tag, arg, descr)

source code
call graph

Process a single field, and use it to update api_doc. If tag is the name of a special field, then call its handler function. If tag is the name of a simple field, then use process_simple_field to process it. Otherwise, check if it's a user-defined field, defined in this docstring or the docstring of a containing object; and if so, process it with process_simple_field.

Parameters:

tag - The field's tag, such as 'author'
arg - The field's optional argument
descr - The description following the field tag and argument.

Raises:

ValueError - If a problem was encountered while processing the field. The ValueError's string argument is an explanation of the problem, which should be displayed as a warning message.

user_docfields(api_doc, docindex)

source code
call graph

Return a list of user defined fields that can be used for the given object. This list is taken from the given api_doc, and any of its containing NamepaceDocs.

Note: We assume here that a parent's docstring will always be parsed before its childrens'. This is indeed the case when we are called via docbuilder.build_doc_index(). If a child's docstring is parsed before its parents, then its parent won't yet have had its extra_docstring_fields attribute initialized.

register_field_handler(handler, *field_tags)

source code

Register the given field handler function for processing any of the given field tags. Field handler functions should have the following signature:

>>> def field_handler(api_doc, docindex, tag, arg, descr):
...     '''update api_doc in response to the field.'''

Where api_doc is the documentation object to update; docindex is a DocIndex that can be used to look up the documentation for related objects; tag is the field tag that was used; arg is the optional argument; and descr is the description following the field tag and argument.

_descr_to_identifiers(descr)

source code
call graph

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 (markup.ParsedDocstring) - A ParsedDocstring containing a list of identifiers.

Returns: list of string

A list of the identifier names contained in descr.

Raises:

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

parse_function_signature(func_doc, doc_source=True)

source code
call graph

Construct the signature for a builtin function or method from its docstring. If the docstring uses the standard convention of including a signature in the first line of the docstring (and formats that signature according to standard conventions), then it will be used to extract a signature. Otherwise, the signature will be set to a single varargs variable named "...".

Parameters:

func_doc (RoutineDoc) - The target object where to store parsed signature. Also container of the docstring to parse if doc_source is None
doc_source (APIDoc) - Contains the docstring to parse. If None, parse func_doc docstring instead

Returns: None

Variables Details

[hide private]

STANDARD_FIELDS

A list of the standard simple fields accepted by epydoc. This list can be augmented at run-time by a docstring with the special @deffield field. The order in which fields are listed here determines the order in which they will be displayed in the output.

Value:

[<Field: deprecated>,
 <Field: version>,
 <Field: date>,
 <Field: status>,
 <Field: author>,
 <Field: contact>,
 <Field: organization>,
 <Field: copyright>,
...

RETURN_PDS

A ParsedDocstring containing the text 'Returns'. This is used to construct summary descriptions for routines that have empty descr, but non-empty return_descr.

Value:

markup.parse('Returns:', markup= 'epytext')

PARAMETER_TAGS

Value:

('arg',
 'argument',
 'parameter',
 'param',
 'kwarg',
 'keyword',
 'kwparam')

_IDENTIFIER_LIST_REGEXP

Value:

re.compile(r'^[\w\.\*]+([\s,:;]\s*[\w\.\*]+)*$')

_SIGNATURE_RE

A regular expression that is used to extract signatures from docstrings.

Value:

re.compile(r'^\s*((?P<self>\w+)\.)?(?P<func>\w+)\((?P<params>(\s*\[?\s
*\*{,2}[\w-\.]+(=.+?)?(\s*\[?\s*,\s*\]?\s*\*{,2}[\w-\.]+(=.+?)?)*\]*)?
)\s*\)(\s*(->)\s*(?P<return>\S.*?))?\s*(\n|\s+(--|<=+>)\s+|$|\.\s+|\.\
n)')