Pyment: how to patch Python docstrings

Pyment is an Open Source software written in Python that aim's to generate patches in order to manipulate Python docstrings.

It can manage several docstrings formats: reST/Sphinx, Numpydoc, Googledoc, Javadoc

So you can use Pyment to harmonize, create, convert docstrings of your Python files or projects.

Pyment will generate docstrings where it doesn't exist. It will complete where it is partial. Or it will simply convert where the format is not the wanted one.

The project is hosted on Github.

How to start

You must retrieve Pyment and install it.

git clone git@github.com:dadadel/pyment.git # or https://github.com/dadadel/pyment.git
cd pyment
python setup.py install

Then you can use it. Type pyment -h to get some help.

You can provide a single file or a directory and by default the output will be formated to reStructuredText:

pyment  example.py

or

pyment  /some/folder

In the second case, all subdirectories will be also explored, and for each found Python file, a patch will be generated.

Once you have used pyment, a patch is generated for a Python file. You can then update the original file using the patch:

patch -p1 < example.py.patch

You can obviously cancel the changes using:

patch -R < example.py.patch

Example

There is an example of what can be done with Pyment:

Before: After: 
def func(prm1=True, prm2='val'):
    '''Description of groups style (Googledoc).

    Params:
        prm1 - descr of prm1 with True default value.
        prm2 - descr of prm2

    Returns:
        some value

    Raises:
        keyError: raises key exception
        TypeError: raises type exception

    '''
    pass

class A:
    def method(self, prm1, prm2=None):
        pass

def func(prm1=True, prm2='val'):
    """Description of groups style (Googledoc).

    :param prm1: descr of prm1 with True default value.
    :param prm2: descr of prm2 (Default value = 'val')
    :returns: some value
    :raises keyError: raises key exception
    :raises TypeError: raises type exception

    """
    pass

class A:
    """ """
    def method(self, prm1, prm2=None):
        """

        :param prm1:
        :param prm2:  (Default value = None)

        """
        pass

In the previous example the Before of Example code is a Python script with both a Google formated docstring and a class and a method without docstrings.

Pyment was used to generate docstrings in reStructuredText format. So considering the file is example.py, the command run:

pyment example.py

Once executed, the example.py.patch is created and contains the following:

# Patch generated by Pyment v0.2.0

--- a/example.py
+++ b/example.py
@@ -1,21 +1,23 @@
 def func(prm1=True, prm2='val'):
-    '''Description of groups style (Googledoc).
+    """Description of groups style (Googledoc).

-    Params:
-        prm1 - descr of prm1 with True default value.
-        prm2 - descr of prm2
+    :param prm1: descr of prm1 with True default value
+    :param prm2: descr of prm2 (Default value = 'val')
+    :returns: some value
+    :raises keyError: raises key exception
+    :raises TypeError: raises type exception

-    Returns:
-        some value
-
-    Raises:
-        keyError: raises key exception
-        TypeError: raises type exception
-
-    '''
+    """
     pass

 class A:
+    """ """
     def method(self, prm1, prm2=None):
+        """
+
+        :param prm1:
+        :param prm2:  (Default value = None)
+
+        """
         pass

The previous patch should be applied to the original file to obtain the After of Example code previously shown:

patch -p1 < example.py.patch

Use options

You can get the list of options using the option -h or --help`:

pyment -h

Delimiters

The docstring starts and ends with delimiters either """ or '''. Pyment uses """ by default, but if you prefer, specify you delimiters, use the -q or --quotes option like:

pyment -q "'''" example.py
Before: After: 
def func():
    """Description

def func():
    '''Description

Note that this option is available starting at version 0.2.1. In the version 0.2.0 the option is available using the configuration file.

Starting line

You can also choose to start the docstring content on the line of the opening delimiter or on the next line.

Use the option -f or --first-line to specify if the content starts on the first line or not. The accepted values are: 'true'/'True' and 'false'/'False'.

In the following example, the content docstring will start on the next line to the one containing delimiters:

pyment -f false example.py
Before: After: 
def func():
    """Description

def func():
    """
    Description

Output format

You can choose the format of output using the option -o or --output followed by the wanted format in "javadoc", "reST" or "numpydoc". So to create a patch to format numpydoc you can run:

pyment -o numpydoc example.py
Before: After: 
def func(prm1=True, prm2='val'):
    """Description of groups style (Googledoc).

    :param prm1: descr of prm1 with True default value.
    :param prm2: descr of prm2 (Default value = 'val')
    :returns: some value
    :raises keyError: raises key exception
    :raises TypeError: raises type exception

    """
    pass

class A:

    def method(self, prm1, prm2=None):
        pass

def func(prm1=True, prm2='val'):
    """Description of groups style (Googledoc).

    Parameters
    ----------
    prm1 :
        descr of prm1 with True default value.
    prm2 :
        descr of prm2 (Default value = 'val')

    Returns
    -------
    type
        some value

    Raises
    ------
    keyError
        raises key exception
    TypeError
        raises type exception

    """
     pass

class A:
    """ """
    def method(self, prm1, prm2=None):
        """

        Parameters
        ----------
        prm1 :
            param prm2:  (Default value = None)
        prm2 :
             (Default value = None)

        Returns
        -------

        """
        pass