Python: how to know the type of function return and the types of arguments?


While I am aware of the duck-typing concept of Python, I sometimes struggle with the type of arguments of functions, or the type of the return value of the function.

Now, if I wrote the function myself, I DO know the types. But what if somebody wants to use and call my functions, how is he/she expected to know the types? I usually put type information in the function's docstring (like: "...the id argument should be an integer..." and "... the function will return a (string, [integer]) tuple.")

But is looking up the information in the docstring (and putting it there, as a coder) really the way it is supposed to be done?

Edit: While the majority of answers seem to direct towards "yes, document!" I feel this is not always very easy for 'complex' types.
For example: how to describe concisely in a docstring that a function returns a list of tuples, with each tuple of the form (node_id, node_name, uptime_minutes) and that the elements are respectively a string, string and integer?
The docstring PEP documentation doesn't give any guidelines on that.
I guess the counterargument will be that in that case classes should be used, but I find python very flexible because it allows passing around these things using lists and tuples, i.e. without classes.

Well things have changed a little bit since 2011! Now there's type hints in Python 3.5 which you can use to annotate arguments and return type of your function. For example this:

def greeting(name):
  return 'Hello, {}'.format(name)

can now be written as this:

def greeting(name: str) -> str:
  return 'Hello, {}'.format(name)

As you an see types there's some sort of optional static type checking which will help you and type checker to investigate your code.

for more explanation I suggest to take a look at blog post on type hints in PyCharm blog.