What does -> mean in Python function definitions?

In more detail, Python 2.x has docstrings, which allow you to attach a metadata string to various types of object. This is amazingly handy, so Python 3 extends the feature by allowing you to attach metadata to functions describing their parameters and return values.

Theres no preconceived use case, but the PEP suggests several. One very handy one is to allow you to annotate parameters with their expected types; it would then be easy to write a decorator that verifies the annotations or coerces the arguments to the right type. Another is to allow parameter-specific documentation instead of encoding it into the docstring.

These are function annotations covered in PEP 3107. Specifically, the -> marks the return function annotation.

Examples:

def kinetic_energy(m:in KG, v:in M/S)->Joules: 
    return 1/2*m*v**2
 
>>> kinetic_energy.__annotations__
{return: Joules, v: in M/S, m: in KG}

Annotations are dictionaries, so you can do this:

>>> {:,} {}.format(kinetic_energy(12,30),
      kinetic_energy.__annotations__[return])
5,400.0 Joules

You can also have a python data structure rather than just a string:

rd={type:float,units:Joules,
    docstring:Given mass and velocity returns kinetic energy in Joules}
def f()->rd:
    pass

>>> f.__annotations__[return][type]
<class float>
>>> f.__annotations__[return][units]
Joules
>>> f.__annotations__[return][docstring]
Given mass and velocity returns kinetic energy in Joules

Or, you can use function attributes to validate called values:

def validate(func, locals):
    for var, test in func.__annotations__.items():
        value = locals[var]
        try: 
            pr=test.__name__+: +test.__docstring__
        except AttributeError:
            pr=test.__name__   
        msg = {}=={}; Test: {}.format(var, value, pr)
        assert test(value), msg

def between(lo, hi):
    def _between(x):
            return lo <= x <= hi
    _between.__docstring__=must be between {} and {}.format(lo,hi)       
    return _between

def f(x: between(3,10), y:lambda _y: isinstance(_y,int)):
    validate(f, locals())
    print(x,y)

Prints

>>> f(2,2) 
AssertionError: x==2; Test: _between: must be between 3 and 10
>>> f(3,2.1)
AssertionError: y==2.1; Test: <lambda>

What does -> mean in Python function definitions?

In the following code:

def f(x) -> int:
    return int(x)

the -> int just tells that f() returns an integer (but it doesnt force the function to return an integer). It is called a return annotation, and can be accessed as f.__annotations__[return].

Python also supports parameter annotations:

def f(x: float) -> int:
    return int(x)

: float tells people who read the program (and some third-party libraries/programs, e. g. pylint) that x should be a float. It is accessed as f.__annotations__[x], and doesnt have any meaning by itself. See the documentation for more information:

https://docs.python.org/3/reference/compound_stmts.html#function-definitions
https://www.python.org/dev/peps/pep-3107/

What does -> mean in Python function definitions?

What does -> mean in Python function definitions?

Leave a Reply Cancel reply