# Source code documentation

Table of content

- Source code documentation

  - Module pyment

    - PyComment class

  - Module docstring

    - NumpydocTools class

    - GoogledocTools class

    - DocsTools class

    - Docstring class

## 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

## 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.

  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, header_lines=2)

    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_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 (list(str)) – a list of strings containing the docstring’s lines

    Returns

      the index of next section else -1

  get_raw_not_managed(data)

    Get elements not managed. They can be used as is.

    Parameters

      data – the data to proceed

### 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.

  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_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_section_key_line(data, key, opt_extension=':')

    Get the next section line for a given key.

    Parameters

      - data – the data to proceed

      - key – the key

      - opt_extension – an optional extension to delimit the opt value

### 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, type_stub=False, before_lim='', **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, type_stub=False, before_lim='', **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

      - type_stub (boolean) – if set, an empty stub will be created for a parameter type

      - before_lim – specify raw or unicode or format docstring type (ie. “r” for r’’’… or “fu” for fu’’’…)

  __repr__()

    Return repr(self).

  __str__()

    Return str(self).

  __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, before_lim='')

    Parses the docstring

    Parameters

      - raw – the data to parse if not internally provided (Default value = None)

      - before_lim – specify raw or unicode or format docstring type (ie. “r” for r’’’… or “fu” for fu’’’…)

  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