Docstrings

Intermediate Python for Developers

George Boorman

Curriculum Manager, DataCamp

Docstrings

String (block of text) describing a function
Help users understand how to use a function

Docstring highlighted from calling help on the round function

Accessing a docstring

# Access information including the docstring
help(round)

Accessing a docstring

# Access only the docstring
round

Accessing a docstring

# Access only the docstring
round.

Accessing a docstring

# Access only the docstring
round.__

Accessing a docstring

# Access only the docstring
round.__doc

Accessing a docstring

# Access only the docstring
round.__doc__

.__doc__: "dunder-doc" attribute

Accessing a docstring

# Access only the docstring
round.__doc__

'Round a number to a given precision in decimal digits.\n\nThe return value is an 
integer if ndigits is omitted or None.  Otherwise\nthe return value has the same 
type as the number.  ndigits may be negative.'

help(round)

Round a number to a given precision in decimal digits.

    The return value is an integer if ndigits is omitted or None.  Otherwise
    the return value has the same type as the number.  ndigits may be negative.

Creating a docstring

def average(values):

    # One-line docstring
    """Find the mean in a sequence of values and round to two decimal places."""

    average_value = sum(values) / len(values)
    rounded_average = round(average_value, 2)
    return rounded_average

Accessing the docstring

# Access our docstring
average.__doc__

'Find the mean in a sequence of values and round to two decimal places.'

Updating a docstring

# Update a function's docstring
average.__doc__ = "Calculate the mean of values in a data structure, rounding the results to 2 digits."

Multi-line docstring

def average(values):
    """
    Find the mean in a sequence of values and round to two decimal places.






    """

    average_value = sum(values) / len(values)
    rounded_average = round(average_value, 2)
    return rounded_average

Multi-line docstring

def average(values):
    """
    Find the mean in a sequence of values and round to two decimal places.

    Args:




    """

    average_value = sum(values) / len(values)
    rounded_average = round(average_value, 2)
    return rounded_average

Multi-line docstring

def average(values):
    """
    Find the mean in a sequence of values and round to two decimal places.

    Args:
        values (list): A list of numeric values.



    """

    average_value = sum(values) / len(values)
    rounded_average = round(average_value, 2)
    return rounded_average

Multi-line docstring

def average(values):
    """
    Find the mean in a sequence of values and round to two decimal places.

    Args:
        values (list): A list of numeric values.

    Returns:
        rounded_average (float): The mean of values, rounded to two decimal places.
    """

    average_value = sum(values) / len(values)
    rounded_average = round(average_value, 2)
    return rounded_average

Accessing the docstring

# Help
help(average)

Help on function average in module __main__:

average(values)
    Find the mean in a sequence of values and round to two decimal places.

        Args:
            values (list): A list of numeric values.

        Returns:
            rounded_average (float): The mean of values, rounded to two decimal places.

Let's practice!

Intermediate Python for Developers