README.md

add-trailing-comma

A tool (and pre-commit hook) to automatically add trailing commas to calls and literals.

Installation

pip install add-trailing-comma

As a pre-commit hook

See pre-commit for instructions

Sample .pre-commit-config.yaml:

-   repo: https://github.com/asottile/add-trailing-comma
    rev: v3.1.0
    hooks:
    -   id: add-trailing-comma

multi-line method invocation style -- why?

# Sample of *ideal* syntax
function_call(
    argument,
    5 ** 5,
    kwarg=foo,
)

• the initial paren is at the end of the line
• each argument is indented one level further than the function name
• the last parameter (unless the call contains an unpacking (*args / **kwargs)) has a trailing comma

This has the following benefits:

• arbitrary indentation is avoided:

  # I hear you like 15 space indents
  # oh your function name changed? guess you get to reindent :)
  very_long_call(arg,
                 arg,
                 arg)

• adding / removing a parameter preserves git blame and is a minimal diff:

   # with no trailing commas
   x(
  -    arg
  +    arg,
  +    arg2
   )

   # with trailing commas
   x(
       arg,
  +    arg2,
   )

Implemented features

trailing commas for function calls

 x(
     arg,
-    arg
+    arg,
 )

trailing commas for tuple / list / dict / set literals

 x = [
-    1, 2, 3
+    1, 2, 3,
 ]

trailing commas for function definitions

 def func(
         arg1,
-        arg2
+        arg2,
 ):

 async def func(
         arg1,
-        arg2
+        arg2,
 ):

trailing commas for from imports

 from os import (
     path,
-    makedirs
+    makedirs,
 )

trailing comma for class definitions

 class C(
     Base1,
-    Base2
+    Base2,
 ):
     pass

trailing comma for with statement

 with (
         open('f1', 'r') as f1,
-        open('f2', 'w') as f2
+        open('f2', 'w') as f2,
 ):
     pass

trailing comma for match statement

 match x:
     case A(
        1,
-       2
+       2,
     ):
        pass
     case (
        1,
-       2
+       2,
     ):
        pass
     case [
        1,
-       2
+       2,
     ]:
        pass
     case {
        'x': 1,
-       'y': 2
+       'y': 2,
     }:
        pass

trailling comma for PEP-695 type aliases

 def f[
-    T
+    T,
 ](x: T) -> T:
     return x

 class A[
-    K
+    K,
 ]:
     def __init__(self, x: T) -> None:
         self.x = x

 type ListOrSet[
-     T
+     T,
] = list[T] | set[T]

unhug trailing paren

 x(
     arg1,
-    arg2)
+    arg2,
+)

unhug leading paren

-function_name(arg1,
-              arg2)
+function_name(
+    arg1,
+    arg2,
+)

match closing brace indentation

 x = [
     1,
     2,
     3,
-    ]
+]

remove unnecessary commas

yes yes, I realize the tool is called add-trailing-comma 😆

-[1, 2, 3,]
-[1, 2, 3, ]
+[1, 2, 3]
+[1, 2, 3]