Source code documentation¶
Table of content
Module pyment¶
This is the module that can be imported in a Python program in order to use Pyment with the class PyComment.
PyComment class¶
-
class
pyment.PyComment(input_file, input_style=None, output_style='reST', quotes='"""', first_line=True, convert_only=False, config_file=None, ignore_private=False, **kwargs)¶ This class allow to manage several python scripts docstrings. It is used to parse and rewrite in a Pythonic way all the functions’, methods’ and classes’ docstrings. The changes are then provided in a patch file.
-
__init__(input_file, input_style=None, output_style='reST', quotes='"""', first_line=True, convert_only=False, config_file=None, ignore_private=False, **kwargs)¶ Sets the configuration including the source to proceed and options.
Parameters: - input_file – path name (file or folder)
- input_style – the type of doctrings format of the output. By default, it will autodetect the format for each docstring.
- output_style – the docstring docstyle to generate (‘javadoc’, ‘reST’, ‘groups’, ‘numpydoc’, ‘google’).
- quotes – the type of quotes to use for output: ‘ ‘ ‘ or ” ” ” (default ” ” “)
- first_line (boolean) – indicate if description should start on first or second line. By default it is True
- convert_only – if set only existing docstring will be converted. No missing docstring will be created.
- config_file – if given configuration file for Pyment
- ignore_private – don’t proceed the private methods/functions starting with __ (two underscores)
-
__weakref__¶ list of weak references to the object (if defined)
-
compute_before_after()¶ Compute the list of lines before and after the proposed docstring changes.
Returns: tuple of before,after where each is a list of lines of python code.
-
diff(source_path='', target_path='', which=-1)¶ Build the diff between original docstring and proposed docstring.
Parameters: - source_path – (Default value = ‘’)
- target_path – (Default value = ‘’)
Returns: the resulted diff
Return type: string
-
diff_to_file(patch_file, source_path='', target_path='')¶ Do a diff and save it to file as a patch
Parameters: - patch_file – file name of the patch to generate
- source_path – name of the original file (Default value = ‘’)
- target_path – name of the final file (Default value = ‘’)
-
docs_init_to_class()¶ If found a __init__ method’s docstring and the class without any docstring, so set the class docstring with __init__one, and let __init__ without docstring.
Returns: True if done Return type: boolean
-
get_output_docs()¶ Return the output docstrings once formatted
Returns: the formatted docstrings Return type: list
-
proceed()¶ Parses the input file and generates/converts the docstrings.
Returns: the list of docstrings Return type: list of dictionaries
-
write_to_file()¶ Do the changes and write back to the file.
Returns: None
-
Module docstring¶
This module is used by pyment module and is not intended to be used out of Pyment. To use Pyment in your project, you may want to use pyment.PyComment (see above).
NumpydocTools class¶
-
class
docstring.NumpydocTools(first_line=None, optional_sections=['raise', 'also', 'ref', 'note', 'other', 'example', 'method', 'attr'], excluded_sections=[])¶ -
__init__(first_line=None, optional_sections=['raise', 'also', 'ref', 'note', 'other', 'example', 'method', 'attr'], excluded_sections=[])¶ Parameters: - first_line (boolean) – indicate if description should start on first or second line. By default it will follow global config.
- optional_sections (list) – list of sections that are not mandatory if empty. The accepted sections are: -param -return -raise -also -ref -note -other -example -method -attr
- excluded_sections (list) – list of sections that are excluded, even if mandatory. The list is the same than for optional sections.
-
__weakref__¶ list of weak references to the object (if defined)
-
get_attr_list(data)¶ Get the list of attributes. The list contains tuples (name, desc, type=None)
Parameters: data – the data to proceed
-
get_key_section_header(key, spaces)¶ Get the key of the header section
Parameters: - key – the key name
- spaces – spaces to set at the beginning of the header
-
get_list_key(data, key)¶ Get the list of a key elements. Each element is a tuple (key=None, description, type=None). Note that the tuple’s element can differ depending on the key.
Parameters: - data – the data to proceed
- key – the key
-
get_next_section_lines(data)¶ Get the starting line number and the ending line number of next section. It will return (-1, -1) if no section was found. The section is a section key (e.g. ‘Parameters’) followed by underline (made by -), then the content The ending line number is the line after the end of the section or -1 if the section is at the end.
Parameters: data – the data to proceed
-
get_next_section_start_line(data)¶ Get the starting line number of next section. It will return -1 if no section was found. The section is a section key (e.g. ‘Parameters’) followed by underline (made by -), then the content
Parameters: data (str) – the data to proceed
-
get_param_list(data)¶ Get the list of parameters. The list contains tuples (name, desc, type=None)
Parameters: data – the data to proceed
-
get_raise_list(data)¶ Get the list of exceptions. The list contains tuples (name, desc)
Parameters: data – the data to proceed
-
get_raw_not_managed(data)¶ Get elements not managed. They can be used as is.
Parameters: data – the data to proceed
-
get_return_list(data)¶ Get the list of return elements/values. The list contains tuples (name=None, desc, type)
Parameters: data – the data to proceed
-
get_section_key_line(data, key)¶ Get the next section line for a given key.
Parameters: - data – the data to proceed
- key – the key
-
GoogledocTools class¶
-
class
docstring.GoogledocTools(first_line=None, optional_sections=['raise'], excluded_sections=[])¶ -
__init__(first_line=None, optional_sections=['raise'], excluded_sections=[])¶ Parameters: - first_line (boolean) – indicate if description should start on first or second line. By default it will follow global config.
- optional_sections (list) – list of sections that are not mandatory if empty. The accepted sections are: -param -return -raise
- excluded_sections (list) – list of sections that are excluded, even if mandatory. The list is the same than for optional sections.
-
__weakref__¶ list of weak references to the object (if defined)
-
get_excluded_sections()¶ Get excluded sections
-
get_key_section_header(key, spaces)¶ Get the key of the section header
Parameters: - key – the key name
- spaces – spaces to set at the beginning of the header
-
get_list_key(data, key)¶ Get the list of a key elements. Each element is a tuple (key=None, description, type=None). Note that the tuple’s element can differ depending on the key.
Parameters: - data – the data to proceed
- key – the key
-
get_mandatory_sections()¶ Get mandatory sections
-
get_next_section_lines(data)¶ Get the starting line number and the ending line number of next section. It will return (-1, -1) if no section was found. The section is a section key (e.g. ‘Parameters’) then the content The ending line number is the line after the end of the section or -1 if the section is at the end.
Parameters: data – the data to proceed
-
get_next_section_start_line(data)¶ Get the starting line number of next section. It will return -1 if no section was found. The section is a section key (e.g. ‘Parameters:’) then the content
Parameters: data – a list of strings containing the docstring’s lines Returns: the index of next section else -1
-
get_optional_sections()¶ Get optional sections
-
get_param_list(data)¶ Get the list of parameters. The list contains tuples (name, desc, type=None)
Parameters: data – the data to proceed
-
get_raise_list(data)¶ Get the list of exceptions. The list contains tuples (name, desc)
Parameters: data – the data to proceed
-
get_return_list(data)¶ Get the list of returned values. The list contains tuples (name=None, desc, type=None)
Parameters: data – the data to proceed
-
get_section_key_line(data, key)¶ Get the next section line for a given key.
Parameters: - data – the data to proceed
- key – the key
-
DocsTools class¶
-
class
docstring.DocsTools(style_in='javadoc', style_out='reST', params=None)¶ This class provides the tools to manage several types of docstring. Currently the following are managed: - ‘javadoc’: javadoc style - ‘reST’: restructured text style compatible with Sphinx - ‘groups’: parameters on beginning of lines (like Google Docs) - ‘google’: the numpy format for docstrings (using an external module) - ‘numpydoc’: the numpy format for docstrings (using an external module)
-
__init__(style_in='javadoc', style_out='reST', params=None)¶ Choose the kind of docstring type.
Parameters: - style_in (string) – docstring input style (‘javadoc’, ‘reST’, ‘groups’, ‘numpydoc’, ‘google’)
- style_out (string) – docstring output style (‘javadoc’, ‘reST’, ‘groups’, ‘numpydoc’, ‘google’)
- params (list) – if known the parameters names that should be found in the docstring.
-
__weakref__¶ list of weak references to the object (if defined)
-
autodetect_style(data)¶ Determine the style of a docstring, and sets it as the default input one for the instance.
Parameters: data (str) – the docstring’s data to recognize. Returns: the style detected else ‘unknown’ Return type: str
-
get_doctests_indexes(data)¶ Extract Doctests if found and return it
Parameters: data – string to parse Returns: index of start and index of end of the doctest, else (-1, -1) Return type: tuple
-
get_elem_desc(data, key)¶ TODO
-
get_elem_index(data, starting=True)¶ Get from a docstring the next option. In javadoc style it could be @param, @return, @type,…
Parameters: - data – string to parse
- starting (boolean) – does the key element must start the line (Default value = True)
Returns: index of found element else -1
Return type: integer
-
get_elem_param()¶ TODO
-
get_group_index(data)¶ Get the next groups style’s starting line index
Parameters: data – string to parse Returns: the index if found else -1
-
get_group_key_index(data, key)¶ Get the next groups style’s starting line index for a key
Parameters: - data – string to parse
- key – the key category
Returns: the index if found else -1
-
get_group_key_line(data, key)¶ Get the next group-style key’s line number.
Parameters: - data – string to parse
- key – the key category
Returns: the found line number else -1
-
get_group_line(data)¶ Get the next group-style key’s line.
Parameters: data – the data to proceed Returns: the line number
-
get_key(key, target='in')¶ Get the name of a key in current style. e.g.: in javadoc style, the returned key for ‘param’ is ‘@param’
Parameters: - key – the key wanted (param, type, return, rtype,..)
- target – the target docstring is ‘in’ for the input or ‘out’ for the output to generate. (Default value = ‘in’)
-
get_key_index(data, key, starting=True)¶ Get from a docstring the next option with a given key.
Parameters: - data – string to parse
- starting (boolean) – does the key element must start the line (Default value = True)
- key – the key category. Can be ‘param’, ‘type’, ‘return’, …
Returns: index of found element else -1
Return type: integer
-
get_param_description_indexes(data, prev=None)¶ Get from a docstring the next parameter’s description. In javadoc style it is after @param.
Parameters: - data – string to parse
- prev – index after the param element name (Default value = None)
Returns: start and end indexes of found element else (-1, -1)
Return type: tuple
-
get_param_indexes(data)¶ Get from a docstring the next parameter name indexes. In javadoc style it is after @param.
Parameters: data – string to parse Returns: start and end indexes of found element else (-1, -1) or else (-2, -2) if try to use params style but no parameters were provided. Note: the end index is the index after the last name character Return type: tuple
-
get_param_type_indexes(data, name=None, prev=None)¶ Get from a docstring a parameter type indexes. In javadoc style it is after @type.
Parameters: - data – string to parse
- name – the name of the parameter (Default value = None)
- prev – index after the previous element (param or param’s description) (Default value = None)
Returns: start and end indexes of found element else (-1, -1) Note: the end index is the index after the last included character or -1 if reached the end
Return type: tuple
-
get_raise_description_indexes(data, prev=None)¶ Get from a docstring the next raise’s description. In javadoc style it is after @param.
Parameters: - data – string to parse
- prev – index after the param element name (Default value = None)
Returns: start and end indexes of found element else (-1, -1)
Return type: tuple
-
get_raise_indexes(data)¶ Get from a docstring the next raise name indexes. In javadoc style it is after @raise.
Parameters: data – string to parse Returns: start and end indexes of found element else (-1, -1) or else (-2, -2) if try to use params style but no parameters were provided. Note: the end index is the index after the last name character Return type: tuple
-
get_return_description_indexes(data)¶ Get from a docstring the return parameter description indexes. In javadoc style it is after @return.
Parameters: data – string to parse Returns: start and end indexes of found element else (-1, -1) Note: the end index is the index after the last included character or -1 if reached the end Return type: tuple
-
get_return_type_indexes(data)¶ Get from a docstring the return parameter type indexes. In javadoc style it is after @rtype.
Parameters: data – string to parse Returns: start and end indexes of found element else (-1, -1) Note: the end index is the index after the last included character or -1 if reached the end Return type: tuple
-
get_sep(key='param', target='in')¶ Get the separator of current style. e.g.: in reST and javadoc style, it is “:”
Parameters: - key – the key which separator is wanted (param, type, return, rtype,..) (Default value = ‘param’)
- target – the target docstring is ‘in’ for the input or ‘out’ for the output to generate. (Default value = ‘in’)
-
set_input_style(style)¶ Set the input docstring style
Parameters: style (str) – style to set for input docstring
-
set_known_parameters(params)¶ Set known parameters names.
Parameters: params (list) – the docstring parameters names
-
set_output_style(style)¶ Set the output docstring style
Parameters: style (str) – style to set for output docstring
-
Docstring class¶
-
class
docstring.DocString(elem_raw, spaces='', docs_raw=None, quotes="'''", input_style=None, output_style=None, first_line=False, trailing_space=True, **kwargs)¶ This class represents the docstring
-
__init__(elem_raw, spaces='', docs_raw=None, quotes="'''", input_style=None, output_style=None, first_line=False, trailing_space=True, **kwargs)¶ Parameters: - elem_raw – raw data of the element (def or class).
- spaces – the leading whitespaces before the element
- docs_raw – the raw data of the docstring part if any.
- quotes – the type of quotes to use for output: ‘ ‘ ‘ or ” ” “
- style_in (string) – docstring input style (‘javadoc’, ‘reST’, ‘groups’, ‘numpydoc’, ‘google’, None). If None will be autodetected
- style_out (string) – docstring output style (‘javadoc’, ‘reST’, ‘groups’, ‘numpydoc’, ‘google’)
- first_line (boolean) – indicate if description should start on first or second line
- trailing_space (boolean) – if set, a trailing space will be inserted in places where the user should write a description
-
__weakref__¶ list of weak references to the object (if defined)
-
generate_docs()¶ Generates the output docstring
-
get_input_docstring()¶ Get the input raw docstring.
Returns: the input docstring if any. Return type: str or None
-
get_input_style()¶ Get the input docstring style
Returns: the style for input docstring Return type: style: str
-
get_output_style()¶ Sets the output docstring style
Returns: the style for output docstring Return type: style: str
-
get_raw_docs()¶ Generates raw docstring
Returns: the raw docstring
-
get_spaces()¶ Get the output docstring initial spaces.
Returns: the spaces
-
parse_docs(raw=None)¶ Parses the docstring
Parameters: raw – the data to parse if not internally provided (Default value = None)
-
parse_element(raw=None)¶ Parses the element’s elements (type, name and parameters) :) e.g.: def methode(param1, param2=’default’) def -> type methode -> name param1, param2=’default’ -> parameters
Parameters: raw – raw data of the element (def or class). (Default value = None)
-
set_input_style(style)¶ Sets the input docstring style
Parameters: style (str) – style to set for input docstring
-
set_output_style(style)¶ Sets the output docstring style
Parameters: style (str) – style to set for output docstring
-
set_spaces(spaces)¶ Set for output docstring the initial spaces.
Parameters: spaces – the spaces to set
-