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