How do I specify input and output data types in python comments?

Question

I have seen several standards for writing comments about the kind of data a function expects and returns in Python. Is there a consensus on which one is best-practice?

Is the new functionality in http://www.python.org/dev/peps/pep-3107/ something I should start using for this?

Answer 1

Function annotations are not for a specific use, they can be used for anything.

Tools can be written to extract information from the annotations and do anything you want, including checking types or generating documentation. But python itself does not do anything with the information. You could use to a completely different purpose, i.e. to provide a function that will be called on the parameter or to declare a string of possible return values.

Annotations can be any object:

def somefunc(param1: "string annotation", 
             param2: 151631,  
             param3: any_object): -> "some information here":

and you can retrieve the objects using:

print (somefunc.func_annotations)
{'param1': "string annotation", 
 'param2': 151631,  
 'param3': <object any_object>,
 'return': "some information here"}

Use case suggestions provided by the PEP:

• Providing typing information
  • Type checking
  • Let IDEs show what types a function expects and returns
  • Function overloading / generic functions
  • Foreign-language bridges
  • Adaptation
  • Predicate logic functions
  • Database query mapping
  • RPC parameter marshaling
• Other information
  • Documentation for parameters and return values

Since function annotation syntax is too new, it is really not used for any production tools.

I suggest using other methods to document that. I use epydoc to generate my documentation, and it can read parameter typing information from docstrings:

def x_intercept(m, b):
    """
    Return the x intercept of the line M{y=m*x+b}.  The X{x intercept}
    of a line is the point at which it crosses the x axis (M{y=0}).

    This function can be used in conjuction with L{z_transform} to
    find an arbitrary function's zeros.

    @type  m: number
    @param m: The slope of the line.
    @type  b: number
    @param b: The y intercept of the line.  The X{y intercept} of a
              line is the point at which it crosses the y axis (M{x=0}).
    @rtype:   number
    @return:  the x intercept of the line M{y=m*x+b}.
    """
    return -b/m

This example is from epydoc's website. It can generate documentation in a variety of formats, and can generate good graphs from your classes and call profiles.

Answer 2

If you use epydoc to produce API documentation, you have three choices.

• Epytext.

• ReStructuredText, RST.

• JavaDoc notation, which looks a bit like epytext.

I recommend RST because it works well with sphinx for generating overall documentation suite that includes API references. RST markup is defined here. The various epydoc fields you can specify are defined here.

Example.

def someFunction( arg1, arg2 ):
    """Returns the average of *two* (and only two) arguments.

    :param arg1: a numeric value
    :type arg1: **any** numeric type

    :param arg2: another numeric value
    :type arg2: **any** numeric type

    :return: mid-point (or arithmetic mean) between two values 
    :rtype: numeric type compatible with the args.
    """
    return (arg1+arg2)/2