Function Annotations in Python

Basic Terminology

What are Function annotations?

1. Python supports dynamic typing and hence no module is provided for type checking. Annotations like

   [def foo(a:”int”, b:”float”=5.0)  -> ”int”]

   (syntax described in detail in the next section) can be used to collect information about the type of the parameters and the return type of the function to keep track of the type change occurring in the function. ‘mypy’ is one such library.
2. String based annotations can be used by the libraries to provide better help messages at compile time regarding the functionalities of various methods, classes and modules.

Syntax of function annotations

Note: The word 'expression' mentioned below can be the type of the parameters that should be passed or comment or any arbitrary string that can be made use by external libraries in a meaningful way.
1. Annotations for simple parameters : The argument name is followed by ':' which is then followed by the expression. Annotation syntax is shown below.

   def foobar(a: expression, b: expression = 5):
   

2. Annotations for excess parameters : Excess parameters for e.g. *args and **kwargs, allow arbitrary number of arguments to be passed in a function call. Annotation syntax of such parameters is shown below.

   def foobar(*args: expression, *kwargs: expression):
   

3. Annotations for nested parameters : Nested parameters are useful feature of python 2x where a tuple is passed in a function call and automatic unpacking takes place. This feature is removed in python 3x and manual unpacking should be done. Annotation is done after the variable and not after the tuple as shown below.

   def foobar((a: expression, b: expression), (c: expression, d: expression)):
   

4. Annotations for return type : Annotating return type is slightly different from annotating function arguments. The '->' is followed by expression which is further followed by ':'. Annotation syntax of return type is shown below.

   def foobar(a: expression)->expression:

decorator    :  ‘@’ name_  [‘(’ [arglist] ‘)’] NEWLINE
decorators   :  decorator+
funcdef      :  [decorators] ‘def’ NAME parameters [‘->’] ‘:’ suite
parameters   :  ‘(’ [typedarglist] ‘)’
typedarglist :  (( tfpdef [‘=’ test] ‘, ’)* (‘*’ [tname]
(‘, ’ tname [‘=’ test])* [‘, ’ ‘ **’ tname] | ‘**’ tname)
| tfpdef [‘=’ test (‘, ’ tfpdef [‘=’ test])* [‘, ’]])
tname        :  NAME [‘:’ test]
tfpdef       :  tname | ‘(’ tfplist ‘)’
tfplist      :  tfpdef (‘, ’ tfpdef)* [‘, ’]

# Python program to print Fibonacci series
def fib(n:'int', output:'list'=[])-> 'list':
    if n == 0:
        return output
    else:
        if len(output)< 2:
            output.append(1)
            fib(n-1, output)
        else:
            last = output[-1]
            second_last = output[-2]
            output.append(last + second_last)
            fib(n-1, output)
        return output
print(fib(5))

Output: [1, 1, 2, 3, 5]

Accessing Function Annotations

# Python program to illustrate Function Annotations
def fib(n:'int', output:'list'=[])-> 'list':
    if n == 0:
        return output
    else:
        if len(output)< 2:
            output.append(1)
            fib(n-1, output)
        else:
            last = output[-1]
            second_last = output[-2]
            output.append(last + second_last)
            fib(n-1, output)
        return output
print(fib.__annotations__)

Output: {'return': 'list', 'n': 'int', 'output': 'list'}

# Python program to illustrate Function Annotations
import inspect
def fib(n:'int', output:'list'=[])-> 'list':
    if n == 0:
        return output
    else:
        if len(output)< 2:
            output.append(1)
            fib(n-1, output)
        else:
            last = output[-1]
            second_last = output[-2]
            output.append(last + second_last)
            fib(n-1, output)
        return output
print(inspect.getfullargspec(fib))

Output: FullArgSpec(args=['n', 'output'], varargs=None,
 varkw=None, defaults=([], ), kwonlyargs=[],
kwonlydefaults=None, annotations=
{'output': 'list', 'return': 'list', 'n': 'int'})

Application of Function Annotations

• Use of 'mypy' : 'mypy' is an external library that provides static type checking with the help of function annotations. Download mypy for python 2x

  pip install mypy

  python 3x

  pip install git+git://github.com/JukkaL/mypy.git

  Example 1: Python

  # String slicing function that returns a string from start index to end index.
  def slice(string:str, start: int, end: int) -> str:
      return string[start:end]
  
  slice([1, 2, 3, 4, 5], 2, 4)
  

  Save the above code as example.py and run the following command after installation of mypy. Make sure you are in the directory where you have saved the file.

  mypy example.py

  You will get the following result.
• Things are little different when the decorators are involved. Example 2(part a): Type checking of the parameters of the wrapped up function 'gift_func' and 'wrapped' Python

  def wrapping_paper(func):
      def wrapped(gift:int):
          return 'I got a wrapped up {} for you'.format(str(func(gift)))
      return wrapped
  
  @wrapping_paper
  def gift_func(giftname:int):
      return giftname
      
  print(gift_func('gtx 5000'))
  

  At first, it may seem that passing string as an argument will return an error as the required datatype is an 'int' as annotated in 'gift_func' and 'wrapped'. mypy does not establish typechecking in the wrapped up function parameters however typechecking of the decorator and the return type of the wrapped up functions can be checked. Therefore the following result can be expected from the above code.
• Example 2(part b): Typechecking of the parameters of the decorator 'wrapping_paper'. Python

  def wrapping_paper(func:str):    
      def wrapped(gift:int):
          return 'I got a wrapped up {} for you'.format(str(func(gift)))
      return wrapped
  
  @wrapping_paper
  def gift_func(giftname:int):
      return giftname
      
  print(gift_func('gtx 5000'))
  

  You will now get the following result.
• Example 2(part c): Typechecking of the return type of 'gift_func' and 'wrapped' Python

  # Suppose we want the return type to be int
  from typing import Callable
  def wrapping_paper(func):
      def wrapped(gift) -> int:
          return 'I got a wrapped up {} for you'.format(str(func(gift)))
      return wrapped
  
  @wrapping_paper
  def gift_func(giftname) -> int:
      return giftname
      
  print(gift_func('gtx 5000'))
  

  You will get the following result.
• Example 2(part d) Typechecking of the return type of the wrapper function 'wrapping_paper' Python

  # Suppose we want the return type to be int
  from typing import Callable
  def wrapping_paper(func) -> int:
      def wrapped(gift):
          return 'I got a wrapped up {} for you'.format(str(func(gift)))
      return wrapped
  
  @wrapping_paper
  def gift_func(giftname):
      return giftname
      
  print(gift_func('gtx 5000'))
  

  You will get the following result