psyclone.docstring_parser

This module contains the PSyclone docstring parsing code. This implementation influenced by the docstring_parser package created by Marcin Kurczewski - rr-/docstring_parser.

Functions

• create_docstring_data(): Creates a docstring data object (i.e. ArgumentData, RaisesData or

psyclone.docstring_parser.create_docstring_data(args, desc, function)

Creates a docstring data object (i.e. ArgumentData, RaisesData or ReturnsData) from an argument list and description.

Parameters:

• args (List[str]) – The argument list (e.g. [‘param’, ‘args’]) for the docstring entry.

• desc (str) – The description corresponding to the docstring element.

• function (Callable[..., Any]) – The function that is having its docstring analysed.

Raises:

DocParseError – If an unsupported docstring input is found.

Return type:

Union[ArgumentData, RaisesData, ReturnsData]

Returns:

An object representing the input arg and desc.

Classes

• ArgumentData: Dataclass object to represent a :param…: docstring element.

• RaisesData: Dataclass object to represent a :raises…: docstring element.

• ReturnsData: Dataclass object to represent a :returns: docstring element.

• DocstringData: Dataclass object representing a full docstring.

class psyclone.docstring_parser.ArgumentData(name, datatype, desc, inline_type)

Dataclass object to represent a :param…: docstring element.

Parameters:

• name (str) – The name of the parameter.

• datatype (str) – The string representation of the parameter’s datatype.

• desc (str) – The description of the parameter.

• inline_type (bool) – whether the type of this parameter should be inline or a separate :type param: docstring line.

Inheritance

gen_docstring(function=None)

Parameters:

function (Optional[Callable[..., Any]]) – The function who the generated docstring will be for. Default option is None. If no function is supplied, there can be no type annotation and so the type information is included inline in the :param or in a separate :type entry.

Return type:

str

Returns:

The docstring represented by this ArgumentData.

class psyclone.docstring_parser.RaisesData(desc, exception)

Dataclass object to represent a :raises…: docstring element.

Parameters:

• desc (str) – The description of the raises docstring.

• exception (str) – The exception or error raised.

Inheritance

gen_docstring()

Return type:

str

Returns:

The docstring for the input raisedata.

class psyclone.docstring_parser.ReturnsData(desc, datatype)

Dataclass object to represent a :returns: docstring element.

Parameters:

• desc (str) – The description of the returns docstring.

• datatype (str) – The string representation of the return datatype.

Inheritance

gen_docstring()

Return type:

str

Returns:

The docstring for this ReturnsData object.

class psyclone.docstring_parser.DocstringData(desc, arguments, raises, returns)

Dataclass object representing a full docstring.

Parameters:

• desc (str) – The description of the docstring.

• arguments (OrderedDict[str, ArgumentData]) – An OrderedDict containing the ArgumentData that respresents the parameter section of the docstring, indexed by the parameter name.

• raises (list[RaisesData]) – A list containing the RaisesData that represents the raises section of the docstring.

• returns (Union[ReturnsData, None]) – The ReturnsData that represents the returns section of the docstring. Can be set to None if there is no return docstring.

Inheritance

add_data(docstring_element)

Adds the docstring_element to the DocstringData object. If there is a previous docstring_element in this DocstringData it will be overwritten.

Docstring_element:

The docstring_element object to be added to the DocstringData.

Raises:

DocParseError – If a docstring element not supported by PSyclone is found.

Return type:

None

classmethod create_from_object(obj)

Converts the docstring of obj into a DocstringData object. Only supports docstring used in PSyclone, so some valid docstring may result in failure.

Parameters:

obj (Any) – The object whose docstring will be parsed.

Returns:

A DocstringData object representing the objects docstring or None if obj has no docstring.

Return type:

Union[psyclone.docstring_parser.DocData, None]

Raises:

• DocParseError – if a docstring element cannot be parsed.

• DocParseError – if a type docstring is found with no corresponding parameter docstring.

gen_docstring(indentation='    ', function=None)

Generates the docstring from the input docdata. The indentation of the docstring can be specified and by default is 4 spaces.

Parameters:

• indentation (str) – The indentation to use. Default is “ “.

• function (Optional[Callable[..., Any]]) – The function (e.g. apply or validate function of a Transformation) who the generated docstring will be for. Default option is None. If no function is supplied, there can be no type annotations and so the type information is included inline in the :param or in a separate :type entry.

Return type:

str

Returns:

The docstring representation of this DocData object.

merge(other_data, replace_desc=False, replace_args=False, replace_returns=False)

Merges the other_data DocstringData object into this one. The user can specify if data in other_data overwrites the data in this DocstringData by setting the replace arguments to True.

If any objects in this DocstringData are None they will be overwritten always.

Parameters:

• other_data (psyclone.docstring_parser.DocstringData) – the DocstringData object to merge into this object.

• replace_desc (bool) – whether to replace the desc with that of other_data.

• replace_args (bool) – whether to replace duplicate arguments with that of other_data.

• replace_returns (bool) – whether to overwrite the returns data with that of other_data.