pymend 3.1.0

Generate, fix and convert docstrings.

Create, update or convert docstrings in existing Python files, managing several styles.

Project Status

Test Status

Supported Versions

Description

Command-line program to generate, update or transform docstrings in python source code.

The app will parse the requested source files for docstrings as well as function signatures and class bodies.

This information is combined to build up complete docstrings for every function and class including place holders for types and descriptions where none could be found elsewhere.

The output format of the docstrings can be chosen between google, numpy, reST and epydoc. This means that the tool can also be used to transform docstrings in the file from one format into another.

Note however that not all section types are supported for all docstring styles.

Partially because they have not been added yet, but also because not every style officially supports the sections from all others.

To get further information please refer to the documentation.

The tool offers the choice between generating patch files or directly overwriting the python source files.

Start quickly

• install from PyPi

$ pip install pymend

• install from sources:

$ pip install git+https://github.com/JanEricNitschke/pymend.git
or
$ git clone https://github.com/JanEricNitschke/pymend.git
$ cd pymend
$ pip install .
or with uv (https://docs.astral.sh/uv/).
$ git clone https://github.com/JanEricNitschke/pymend.git
$ cd pymend
$ uv sync --all-groups
$ uv tool install .
in the case of uv you can prefix all commands below with `uv run`.

• run from the command line:

$ pymend  myfile.py         # will generate a patch
$ pymend --write myfile.py  # will overwrite the file

• get help:

$ pymend -h

Example

To see how pymend looks in action lets consider this example file example.py:

"""_summary_."""
 def my_func(param0, param01: int, param1: str = "Some value", param2: List[str] = {}):
     """_summary_.

     Args:
         param0 (_type_): _description_
         param01 (int): _description_
         param1 (str, optional): _description_. Defaults to "Some value".
         param2 (List[str], optional): _description_. Defaults to {}.
     """
     pass


 def my_single_return_func1() -> str:
     """_summary_.

     Returns
     -------
     int
         Wrong
     """
     pass


 def my_multi_return_func() -> Tuple[int, str, bool]:
     """_summary_.

     Returns
     -------
     x :
         Some integer
     y : str
         Some string
     z : bool
         Some bool
     """
     pass

class A:
   def method(self, param1, param2=None) -> int:
         pass

Now let’s use Pymend:

$ pymend example.py

This produces the following patch file example.py.patch:

# Patch generated by Pymend v3.1.0

--- a/example.py
+++ b/example.py
@@ -2,11 +2,16 @@
def my_func(param0, param01: int, param1: str = "Some value", param2: List[str] = {}):
   """_summary_.

-    Args:
-        param0 (_type_): _description_
-        param01 (int): _description_
-        param1 (str, optional): _description_. Defaults to "Some value".
-        param2 (List[str], optional): _description_. Defaults to {}.
+    Parameters
+    ----------
+    param0 : _type_
+        _description_
+    param01 : int
+        _description_
+    param1 : str
+        _description_. Defaults to "Some value".
+    param2 : List[str]
+        _description_. Defaults to {}.
   """
   pass

@@ -16,7 +21,7 @@

   Returns
   -------
-    int
+    str
         Wrong
   """
   pass
@@ -27,7 +32,7 @@

   Returns
   -------
-    x :
+    x : _type_
         Some integer
   y : str
         Some string
@@ -37,5 +42,21 @@
   pass

class A:
+    """_summary_.
+
+    Methods
+    -------
+    method(param1, param2=None)
+        _description_
+    """
   def method(self, param1, param2=None) -> int:
+        """_summary_.
+
+        Parameters
+        ----------
+        param1 : _type_
+            _description_
+        param2 : _type_
+            _description_ (Default value = None)
+        """
         pass

Calling pymend directly with

$ pymend --write example.py

prints out this information about changed files

$ Modified docstrings of elements (my_func, my_single_return_func1, my_multi_return_func, A, method) in file example.py.

and results in the final file (the same we would have gotten when applying the patch):

"""_summary_."""
def my_func(param0, param01: int, param1: str = "Some value", param2: List[str] = {}):
   """_summary_.

   Parameters
   ----------
   param0 : _type_
      _description_
   param01 : int
      _description_
   param1 : str
      _description_. Defaults to "Some value".
   param2 : List[str]
      _description_. Defaults to {}.
   """
   pass


def my_single_return_func1() -> str:
   """_summary_.

   Returns
   -------
   str
      Wrong
   """
   pass


def my_multi_return_func() -> Tuple[int, str, bool]:
   """_summary_.

   Returns
   -------
   x : _type_
      Some integer
   y : str
      Some string
   z : bool
      Some bool
   """
   pass

class A:
   """_summary_.

   Methods
   -------
   method(param1, param2=None)
      _description_
   """
   def method(self, param1, param2=None) -> int:
      """_summary_.

      Parameters
      ----------
      param1 : _type_
            _description_
      param2 : _type_
            _description_ (Default value = None)
      """
      pass

Exit codes

PyMend uses exit codes to indicate the result:

• 0: All files well formatted, no issues

• 1: One or more files had issues (would be reformatted or have problems)

• 2: Usage error (e.g. invalid or conflicting command-line options)

• 123: Internal error occurred

$ pymend src/
All done! ✨ 🍰 ✨
5 files would be left unchanged.
$ echo $?
0

$ pymend src/
would reformat src/main.py
Oh no! 💥 💔 💥
1 file would be reformatted.
$ echo $?
1

$ pymend src/
error: cannot format src/main.py: INTERNAL ERROR
Oh no! 💥 💔 💥
1 file would fail to reformat.
$ echo $?
123

Pre-commit

To use pymend in a pre-commit hook just add the following to your .pre-commit-config.yaml

repos:
-   repo: https://github.com/JanEricNitschke/pymend
    rev: "v3.1.0"
    hooks:
    -   id: pymend
        language: python
        args: ["--write"]

Acknowledgements

This project was inspired by and is originally based upon pyment. The intended functionality as well as the main entry point remain largely unchanged. However additional functionality has been added in the form of ast traversal for extracting function and class information.

The docstring parsing has been replaced completely with code taken from the awesome docstring_parser project, specifically this fork.

So far only minor modifications have been made to the docstring parsing functionality. Mainly the addition of the “Methods” section for numpydoc style docstrings. Additionally the code has been linted as well as type hinted.

The code for configuration and file handling as well as the structure of the documentation is more or less taken directly from black.