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

--- 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, 1 file had issues.
$ echo $?
1

$ pymend src/
error: cannot format src/main.py: INTERNAL ERROR

Oh no! 💥 💔 💥
1 file would fail to reformat.
$ echo $?
123