5

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.

ibarrond
  • 6,617
  • 4
  • 26
  • 45
  • 2
    There is none. The ``black`` formatter seems to have gained serious adoption, but it's still not official and thus "opinion". – MisterMiyagi Feb 26 '21 at 12:07
  • Could you turn it into an answer? maybe show what `black` recommends as formatting? – ibarrond Feb 26 '21 at 13:07
  • Why negative vote? at least leave a comment :( I still believe it is a perfectly valid questiion. Otherwise, please comment on its flaws – ibarrond Jun 11 '21 at 15:16
  • Asking for coding style can be opinionated. Asking for **canon** coding style based on approved PEPs should not. – ibarrond Jun 11 '21 at 15:27
  • 1
    Here are type annotations in the Google style guide - really useful to read: https://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. – pabouk - Ukraine stay strong May 24 '22 at 10:19
  • 2
    @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. – MisterMiyagi May 24 '22 at 10:33

1 Answers1

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.

ibarrond
  • 6,617
  • 4
  • 26
  • 45
  • 3
    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".](https://www.python.org/dev/peps/pep-0008/#indentation). So the "small indentation" would go against that. (Other than that, I feel this is perfectly fine.) – MisterMiyagi Jun 11 '21 at 15:33