epydoc.docstringparser

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, suppress_warnings=`[``]`) Process the given `APIDoc`'s docstring. | source code call graph
Call Graph
add_metadata_from_var(api_doc, field) | source code call graph
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
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
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
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
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
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
Call Graph
process_deffield_field(api_doc, docindex, tag, arg, descr) Define a new custom field. | source code call graph
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
Call Graph
process_sort_field(api_doc, docindex, tag, arg, descr) | source code call graph
Call Graph
process_type_field(api_doc, docindex, tag, arg, descr) | source code call graph
Call Graph
process_var_field(api_doc, docindex, tag, arg, descr) | source code call graph
Call Graph
process_cvar_field(api_doc, docindex, tag, arg, descr) | source code call graph
Call Graph
process_ivar_field(api_doc, docindex, tag, arg, descr) | source code call graph
Call Graph
process_return_field(api_doc, docindex, tag, arg, descr) | source code call graph
Call Graph
process_rtype_field(api_doc, docindex, tag, arg, descr) | source code call graph
Call Graph
process_arg_field(api_doc, docindex, tag, arg, descr) | source code call graph
Call Graph
process_kwarg_field(api_doc, docindex, tag, arg, descr) | source code call graph
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
Call Graph
set_var_descr(api_doc, ident, descr) | source code call graph
Call Graph
set_var_type(api_doc, ident, descr) | source code call graph
Call Graph
_check(api_doc, tag, arg, context=None, expect_arg=None) | source code call graph
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
Call Graph
unindent_docstring(docstring) | source code call graph
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
Call Graph
_descr_to_docstring_field(arg, descr) | source code call graph
Call Graph
Function Signature Extraction
`None` |
parse_function_signature(func_doc, doc_source, docformat, parse_errors) Construct the signature for a builtin function or method from its docstring. | source code call graph
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, suppress_warnings=`[``]`) | source code call graph
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. `suppress_warnings` - A set of objects for which docstring warnings should be suppressed.

### split_init_fields(fields, warnings) | source code call graph
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
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
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 `NamepaceDoc`s. 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
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, docformat, parse_errors) | source code call graph
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*\]?\s*\*{,2}[\w-\.]+(\s*=.+?)?)
      *\]*)?)\s*\)(\s*(->)\s*(?P<return>\S.*?))?\s*(\n|\s+(--|<=+>)\s+|$|\.\
      s+|\.\n)')