Python Docstring: How to Write and Access It

When you add a function to a Python file, its purpose may not be clear to someone who calls it later. A Python docstring is a string at the start of a definition that Python makes available as documentation.

This article shows how to add a summary after a function definition and inspect it with help().

TL;DR

A Python docstring is a string literal placed first in a definition body, and Python exposes it through the object’s __doc__ attribute.

• Put the docstring immediately below the function or class definition.
• Use triple double quotes and start with a short summary.
• Read the text with area.__doc__ or view it with help(area).

What is a Python docstring?

A docstring is a string literal Python recognizes when it is the first statement in a definition body. Python stores that text on the object as __doc__, where code and documentation tools can read it.

Functions and classes can have docstrings. A module can have one too. A comment that starts with # is for people reading source code, but it does not become the object’s __doc__ value.

Classes and methods follow the same first-statement rule. Put each docstring at the top of its body, and place a module docstring before the file’s other statements. Each object exposes its text through __doc__.

PEP 257 describes docstring conventions rather than syntax rules. It recommends triple double quotes, a concise summary line, and a blank line before longer details.

How to write and access a Python docstring step by step

This example documents a rectangle-area function, reads the stored text, and opens Python’s help display. Save the code as docstring_example.py and run it with Python 3.

Step 1: Put the summary after the function definition

Python assigns the first string in the function body to area.__doc__.

def area(width, height):
    """Return the area of a rectangle.

    Args:
        width: Rectangle width.
        height: Rectangle height.

    Returns:
        The rectangle area.
    """
    return width * height

print(area.__doc__)
print(area(4, 3))
help(area)

python -m venv .venv && .venv/bin/python --version && .venv/bin/python docstring_example.py

Step 2: Inspect the function with help()

help(area) prints the function signature with its docstring beneath it, as shown after the raw __doc__ text in the screenshot. Python documents help() as intended for interactive use.

Common errors with Python docstrings

Placement decides whether Python records a string as the docstring. A later string expression and a source comment do not replace the first statement.

PEP 257 conventions are not required syntax. Google-style docstrings offer one way to group parameter details under Args and return details under Returns. The Sphinx Napoleon guide shows how that layout can be used when generating documentation.

Keep the summary useful to its caller

Use a short summary for the caller, then add details that explain how to use the function. Keep parameter names aligned with the definition and follow one format throughout a project.

Frequently asked questions

These answers cover the first placement and access questions that come up when you add a docstring.