Python type annotations style for functions with long arguments

Question

What is the canon (based on some PEP) way to style a function definition with long type annotations?

Some alternatives I can conceive:

• Option 1:

def my_long_function_name_super_important(
   first_long_argument_to_my_function: Union[int, str],
   second: Dict[int, str],
   third_arg: int = 0 ) -> (bool, int):
   
   return (True, 1)

• Option 2:

def my_long_function_name_super_important(
   first_long_argument_to_my_function: Union[int, str],
   second: Dict[int, str],
   third_arg: int = 0
) -> (bool, int):
   
   return (True, 1)

• Option 3:

def my_long_function_name_super_important(
   first_long_argument_to_my_function: Union[int, str],
   second: Dict[int, str],  third_arg: int = 0
) -> (bool, int):
   
   return (True, 1)

• Option 4:

def my_long_function_name_super_important(
   first_long_argument_to_my_function: Union[int, str],
   second: Dict[int, str],
   third_arg: int = 0,
   ) -> (bool, int):
   
   return (True, 1)

Note: targeting Python 3.8+ to get an up-to-date answer.

Varioloid

There is none. The black formatter seems to have gained serious adoption, but it's still not official and thus "opinion". – Folkway

Could you turn it into an answer? maybe show what black recommends as formatting? – Varioloid

Why negative vote? at least leave a comment :( I still believe it is a perfectly valid questiion. Otherwise, please comment on its flaws – Varioloid

Asking for coding style can be opinionated. Asking for canon coding style based on approved PEPs should not. – Varioloid

Here are type annotations in the Google style guide - really useful to read: google.github.io/styleguide/pyguide.html#319-type-annotations BTW: I do not really understand the reasoning behind the unindented closing parenthesis (options 2, 3, black). I prefer the idea that every line after a block start (def) till the end of the block should be indented. – Haemostatic

@pabouk-Ukrainestaystrong The unindented closing parenthesis add a clear visual break between the parameters and body. Notably, the parameters are not part of the def block but the head of the def statement itself. – Folkway

Answer 1

As hinted by @MisterMiyagi, there is no official coding style based on a PEP for these type annotations in functions.

That being said, after playing a bit with the different options, I realized options 2 and 3 generate some minor problems in some python code formatters (e.g.: code folding in functions in jupyter notebook) due to the lack of indentation in the closing ). As such, and in search of the highest readability, I ended up using something similar to option 2, but with a small indentation at the last line of the function definition (easier to spot), and with one argument per line (easier to read):

def my_long_function_name_super_important(
   first_long_argument_to_my_function: Union[int, str],
   second: Dict[int, str],
   third_arg: int = 0
  ) -> (bool, int):
   
   return (True, 1)

F.Y.I., the black formatter of @MisterMiyagi seems to be exactly Option 2 (can be tried out here)

edit: from @pabouk 's comment, Google style seems to lean towards options 2-3.

Varioloid

FWIW, while PEP-8 has nothing to say about the lines on which to put the annotations, it does say "closing brace/bracket/parenthesis (…) may either line up under the first non-whitespace character of the last line of list or (…) the first character of the line that starts the multiline construct".. So the "small indentation" would go against that. (Other than that, I feel this is perfectly fine.) – Folkway