{"id":930,"date":"2020-11-03T04:54:32","date_gmt":"2020-11-03T04:54:32","guid":{"rendered":"https:\/\/www.pythontutorial.net\/?page_id=930"},"modified":"2025-03-26T12:45:19","modified_gmt":"2025-03-26T12:45:19","slug":"python-function-docstrings","status":"publish","type":"page","link":"https:\/\/www.pythontutorial.net\/python-basics\/python-function-docstrings\/","title":{"rendered":"Python Function Docstrings"},"content":{"rendered":"\n

Summary<\/strong>: in this tutorial, you’ll learn about how to use docstrings to add documentation to a function.<\/p>\n\n\n\n

Introduction to the help() function #<\/a><\/h2>\n\n\n\n

Python provides a built-in function called help()<\/code> that allows you to show the documentation of a function<\/a>.<\/p>\n\n\n\n

The following example shows the documentation of the print()<\/code> function:<\/p>\n\n\n

help(print<\/span>)<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Output:<\/p>\n\n\n
print(...)\n    print(value, ..., sep=' '<\/span>, end='\\n'<\/span>, file=sys.stdout, flush=False<\/span>)\n\n    Prints the values to a stream, or<\/span> to sys.stdout by default.\n    Optional keyword arguments:\n    file:  a file-like object (stream); defaults to the current sys.stdout.\n    sep:   string inserted between values, default a space.\n    end:   string appended after the last value, default a newline.\n    flush: whether to forcibly flush the stream.\n<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Using docstrings to document functions #<\/a><\/h2>\n\n\n\n
To document your functions, you can use docstrings. The PEP 257<\/a> provides the docstring conventions.<\/p>\n\n\n\n
When the first line in the function body is a string, Python will interpret it as a docstring. For example:<\/p>\n\n\n
def<\/span> add<\/span>(a, b)<\/span>:<\/span>\n    \"Return the sum of two arguments\"<\/span>\n    return<\/span> a + b<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
And you can use the help()<\/code> function to find the documentation of the add()<\/code> function:<\/p>\n\n\n
def<\/span> add<\/span>(a, b)<\/span>:<\/span>\n    \"Return the sum of two arguments\"<\/span>\n    return<\/span> a + b\n\nhelp(add)<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Output:<\/p>\n\n\n
add(a, b)\n    Return the sum of two arguments<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Typically, you use multi-line docstrings:<\/p>\n\n\n
def<\/span> add<\/span>(a, b)<\/span>:<\/span>\n    \"\"\" Add two arguments\n    Arguments:\n        a: an integer\n        b: an integer\n    Returns:\n        The sum of the two arguments\n    \"\"\"<\/span>\n    return<\/span> a + b\n\nhelp(add)<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Output:<\/p>\n\n\n
add(a, b)\n    Add the two arguments\n    Arguments:\n            a: an integer\n            b: an integer\n        Returns:\n            The sum of the two arguments        <\/code><\/span>Code language:<\/span> Shell Session<\/span> (<\/span>shell<\/span>)<\/span><\/small><\/pre>\n\n\n
Python stores the docstrings in the __doc__<\/code> property of the function. <\/p>\n\n\n\n
The following example shows how to access the __doc__<\/code> property of the add()<\/code> function:<\/p>\n\n\n
def<\/span> add<\/span>(a, b)<\/span>:<\/span>\n    \"\"\" Add two arguments\n    Arguments:\n        a: an integer\n        b: an integer\n    Returns:\n        The sum of the two arguments\n    \"\"\"<\/span>\n    return<\/span> a + b\n\nprint(add.__doc__)<\/code><\/span>Code language:<\/span> Python<\/span> (<\/span>python<\/span>)<\/span><\/small><\/pre>\n\n\n
Summary #<\/a><\/h2>\n\n\n\n
Try it<\/a><\/p>\n\n\n\n
Try it<\/a><\/p>\n\n\n\n
Try it<\/a><\/p>\n\n\n\n
Note that you can use the help()<\/code> function to show the documentation of modules<\/a>, classes<\/a>, functions<\/a>, and keywords. This tutorial focuses on function documentation only.<\/p>\n\n\n\n
Try it<\/a><\/p>\n\n\n\n