dark

Python Docstrings

How to Use Python Docstrings

One of the features that makes Python a popular choice among developers is its support for docstrings. Docstrings are short, descriptive strings that are used to document a function, module, or class. In this article, we’ll take a closer look at what docstrings are, why they’re important, and how to use them effectively in your Python code.

What are Docstrings?

A docstring is a string literal that appears as the first statement in a module, function, class, or method definition. Its purpose is to provide a concise, human-readable description of what the code does, how it works, and how to use it. Docstrings are not comments, although they look similar. Comments are ignored by the interpreter, while docstrings are stored as an attribute of the object to which they are attached.

Why are Docstrings Important?

Docstrings are important for several reasons. First, they provide documentation for your code that can be easily accessed by other developers. This is especially useful when working on large projects with many collaborators. Second, docstrings can be used to generate documentation automatically using tools like Sphinx. Finally, docstrings can be used to provide help information to users of your code.

How to Use Docstrings

There are several conventions for writing docstrings in Python. The most common convention is called the “Google style”, which uses triple quotes to enclose the docstring. Here’s an example of a docstring for a function:

def square(x):
    """
    Returns the square of a number.

    Args:
        x: A numeric value.

    Returns:
        The square of x.
    """
    return x ** 2

In this example, the docstring describes what the function does, what arguments it takes, and what it returns. The docstring is enclosed in triple quotes, which allows it to span multiple lines.

Docstring Conventions

There are several conventions for writing docstrings in Python, including the Google style, the NumPy style, and the reStructuredText style. Each convention has its own guidelines for formatting and content. Here’s an example of a docstring using the NumPy style:

def square(x):
    """
    Return the square of input.

    Parameters
    ----------
    x : int or float
        Input value.

    Returns
    -------
    int or float
        Square of input.

    Examples
    --------
    >>> square(2)
    4
    >>> square(2.0)
    4.0
    """
    return x ** 2

In this example, the docstring uses the NumPy style, which includes a section for parameters, returns, and examples.

Docstring Sections

Docstrings can include several sections, each describing a different aspect of the code. The most common sections are:

  • Args or Parameters: A description of the function arguments, including their names and types.
  • Returns: A description of what the function returns, including its type.
  • Raises: A description of the exceptions that the function may raise.
  • Examples: Examples of how to use the function.
  • Notes: Any additional information about the function.

Here’s an example of a docstring that includes several sections:

def divide(x, y):
    """
    Divide two numbers.

    Args:
        x (int): The dividend.
        y (int): The divisor.

    Returns:
        float: The quotient of x and y.

    Raises:
        ZeroDivisionError: If y is zero.

    Examples:
        >>> divide(10, 2)
        5.0
        >>> divide(10, 0)
        Traceback (most recent call last):
            ...
        ZeroDivisionError: division by zero

    Notes:
        This function performs floating-point division, which may not be what you expect if you're used to integer division.
    """
    if y == 0:
        raise ZeroDivisionError("division by zero")
    return float(x) / float(y)

In this example, the docstring includes sections for Args, Returns, Raises, Examples, and Notes.

Accessing Docstrings

You can access the docstring of a Python object using the `__doc__` attribute. Here’s an example:

def square(x):
    """
    Returns the square of a number.

    Args:
        x: A numeric value.

    Returns:
        The square of x.
    """
    return x ** 2

print(square.__doc__)

This will output the docstring for the square function:

Returns the square of a number.

    Args:
        x: A numeric value.

    Returns:
        The square of x.

You can also use the built-in help() function to access the docstring and display it in a more formatted manner:

help(square)

This will output the following:

Help on function square in module __main__:

square(x)
    Returns the square of a number.

    Args:
        x: A numeric value.

    Returns:
        The square of x.

Conclusion

In conclusion, docstrings are an essential part of writing clean, maintainable Python code. They provide documentation for your code that can be easily accessed by other developers, generate documentation automatically, and provide help information to users of your code. By following the conventions for writing docstrings and including the appropriate sections, you can make your code more readable and easier to understand.

Related tutorials