TODO: optionally (or always?) reformat as per-line arg type comments?

[anentropic]

currently we output a single-line type comment:

def my_func(arg1, arg2, arg3):
    # type: (arg1T, arg2T, arg3T) -> returnT

this can get quite long, but even Black will never wrap this comment line

if not all args have documented types then currently we add a type comment which doesn't match the signature, alternatively we should introspect the signature and raise an error

another alternative is to re-format the def and type comment as:

def my_func(
    arg1,  # type: arg1T
    arg2,  # type: arg2T
    arg3,  # type: arg3T
):
    # type: (...) -> returnT

this is better when the comment gets too long

additionally, say arg2 was not typed in the docstring, we can output:

def my_func(
    arg1,  # type: arg1T
    arg2,
    arg3,  # type: arg3T
):
    # type: (...) -> returnT

if we simply omit the arg from our one-line type comment, mypy would rightly give us:

error: Type signature has too few arguments

but with the multi-line format mypy appears to treat the missing annotation as an implicit Any and will happily type check it as that

Currently if there are missing args we output:

  # type (...) -> returnT

i.e. all args become implicit Any. mypy accepts this, but it's not a good annotation

[anentropic]

OTOH if type comments in Python 2 are just a stepping-stone to Python 3 (as they should be in 2020...) then we shouldn't worry about 'long' type comments

Once converted to Python 3 annotations (eg with https://github.com/ilevkivskyi/com2ann) then they are readily re-formatted by tools like Black (or com2ann itself even)

This would imply to prioritise introspecting the signature and raising an error, or even adding an explicit Any for missing arg types

[anentropic]

possibly achievable via https://github.com/google/yapf#formatting-style

SPLIT_ALL_TOP_LEVEL_COMMA_SEPARATED_VALUES

[anentropic]

If com2ann works well then I will abandon this

re the other concern raised here, I have since made ALLOW_UNTYPED_ARGS default to False so we give a nudge to avoid partially-typed functions (return type given without arg types) and avoid outputting # type: (...) -> whatever type-comments