[PYTHON] Mastering type hinting in PyCharm

With PyCharm, type inference is based on the comments in docstring.

def foo(x):
    """
    :rtype: list of str
    """
    return x

def bar(x):
    a = foo(x)
    a[0].  # <-At this point the string method is a candidate

docstring

It seems to accept how to write Sphinx and Epytext, but since Sphinx is more common in Python, let's learn it.

def repeat(x, y):
    """
    :param str x: value to repeat
    :type  y: int
    :param y: number of repeat
    :rtype:   str
    :return:  repeated string
    """
    return x * y

The argument can be written as : param type name: or : type argument name: type. Write the return value as : rtype:.

Type declaration

You can roughly understand how to write it by looking at the file StdlibTypes2.properties. This file is located in the directory /Applications/PyCharm 2.7.2 EAP.app/helpers on Mac.

Here are some excerpts.

__builtin__.locals = \
  :rtype: dict of (string, unknown)

__builtin__.filter = \
  :type function_or_none: collections.Callable or None \n\
  :type sequence: collections.Iterable of T \n\
  :rtype: list of T \n\

__builtin__.enumerate.__init__ = \
  :type iterable: collections.Iterable of T \n\
  :type start: int or long \n\
  :rtype: enumerate of (int, T) \n\

__builtin__.enumerate.next = \
  :rtype: (int, T) \n\

__builtin__.dict.__init__ = \
  :type seq: collections.Iterable of (T, V) \n\
  :rtype: dict of (T, V) \n\

__builtin__.dict.__getitem__ = \
  :type y: T \n\
  :rtype: V \n\

__builtin__.dict.items = \
  :rtype: list of (T, V) \n\

Complex types can be written as (int, str) only for tuples, and are represented using ʻof like dict of (T, V) `otherwise.

It seems that the type argument can use any uppercase letter, not just T.

When returning a general type, it seems good to use ABC in collections in the form of ʻof T`.

If you can receive more than one person, it seems to connect with ʻorforʻint or None``.

Type hinting to other variables

#: :type: int
x = unknown()

You can hinting by adding comments like. But

#: ????
a, b = unknwon()

I still don't know how to hinting in this case. You can receive it as a tuple once, but it's awkward, so it seems better to define: rtype: properly on the function side.