What are Docstrings in Python?
Python Docstrings are documentation strings present in functions or methods that summarise the purpose of the function or method and document the function’s or method’s arguments and return values.
We generally write docstring with Triple quotes.
For consistency, always use """triple quotes""" around docstrings.
Use r"""raw triple quotes""" if you use any backslashes in your docstrings.
For Unicode docstrings, use u"""Unicode triple-quoted strings""".
The more descriptive your docstrings are, the better for other people to understand your code. It also helps the author of the functions or methods when they look at the code after some time to understand the function’s purpose, the arguments used and the return object.
How does python find the Docstrings?
def addition(a, b):
"""Function to do addition and return an integer value
Args:
a (int): first parameter to add
b (int): second parameter to add
Returns:
int: The sum of two parameters
"""
sum_total = a+b
return sum_total
If the first line of a function or method is a string, python interprets it as docstrings.
It does not matter whether we have a single or triple quote.
However, for writing multi-line statements, we use triple quotes. Remember, we cannot pass the comments as docstrings, which begin with a hash sign. The reason is that comments get removed in the compilation stage of the code.
From the above example, we will use the python help() method to get the docstring information of our function addition().
>>> print(help(addition))
Output:
Help on function addition in module __main__:
addition(a, b)
Function to do addition and return an integer value
Args:
a (int): first parameter to add
b (int): second parameter to add
Returns:
int: The sum of two parameters
(END)
Where are Docstrings stored?
They are stored in the magic method __doc__. You can use the function.__doc__ to find out the docstring of any function.
>>> print(addition.__doc__)
Output:
Function to do addition and return an integer value
Args:
a (int): first parameter to add
b (int): second parameter to add
Returns:
int: The sum of two parameters
What are Function Annotations in Python?
This is another way of documenting our functions by adding metadata.
Look at the example.
def addition(a:int, b:"integer_value")-> int:
sum_total = a+b
return sum_total
So you have your regular parameters with a full colon followed by an expression. This expression can be any valid Python expression or objects. You can even give functions, literals etc. The return is given by the arrow symbol followed by the expression.
Let’s use the help() method to get the annotations of the above function.
>>> print(help(addition))
Output:
Help on function addition in module __main__:
addition(a: int, b: 'integer_value') -> int
(END)
Where are these Python annotations stored?
These annotations are stored in the magic method __annotations__. This is a dictionary where the keys are the parameters, and the values are the metadata or annotations.
Let’s use the above example and see the __annotations __ method of the addition() function.
>>> print(help(addition))
Output:
{'a': <class 'int'>, 'b': 'integer_value', 'return': <class 'int'>}
Cheatsheet:
If you enjoy reading our short articles, do subscribe to our news letter, for all the updated contents
One Response