Package epydoc :: Module docstringparser
[hide private]
[frames] | no frames]

Module docstringparser

source code

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