Docstrings

Writing Functions in Python

Shayne Miel

Software Architect @ Duo Security

A complex function

def split_and_stack(df, new_names):
  half = int(len(df.columns) / 2)
  left = df.iloc[:, :half]
  right = df.iloc[:, half:]
  return pd.DataFrame(
    data=np.vstack([left.values, right.values]),
    columns=new_names
  )
Writing Functions in Python
def split_and_stack(df, new_names):
  """Split a DataFrame's columns into two halves and then stack
  them vertically, returning a new DataFrame with `new_names` as the
  column names.

  Args:
    df (DataFrame): The DataFrame to split.
    new_names (iterable of str): The column names for the new DataFrame.

  Returns:
    DataFrame
  """
  half = int(len(df.columns) / 2)
  left = df.iloc[:, :half]
  right = df.iloc[:, half:]
  return pd.DataFrame(
    data=np.vstack([left.values, right.values]),
    columns=new_names
  )
Writing Functions in Python

Anatomy of a docstring

def function_name(arguments):
  """
  Description of what the function does.

  Description of the arguments, if any.

  Description of the return value(s), if any.

  Description of errors raised, if any.

  Optional extra notes or examples of usage.
  """
Writing Functions in Python

Docstring formats

  • Google Style
  • Numpydoc
  • reStructuredText
  • EpyText
Writing Functions in Python

Google Style - description

def function(arg_1, arg_2=42):
  """Description of what the function does.
  """
Writing Functions in Python

Google style - arguments

def function(arg_1, arg_2=42):
  """Description of what the function does.

  Args:
    arg_1 (str): Description of arg_1 that can break onto the next line
      if needed.
    arg_2 (int, optional): Write optional when an argument has a default
      value.
  """
Writing Functions in Python

Google style - return value(s)

def function(arg_1, arg_2=42):
  """Description of what the function does.

  Args:
    arg_1 (str): Description of arg_1 that can break onto the next line
      if needed.
    arg_2 (int, optional): Write optional when an argument has a default
      value.

  Returns:
    bool: Optional description of the return value
    Extra lines are not indented.
  """
Writing Functions in Python
def function(arg_1, arg_2=42):
  """Description of what the function does.

  Args:
    arg_1 (str): Description of arg_1 that can break onto the next line
      if needed.
    arg_2 (int, optional): Write optional when an argument has a default
      value.

  Returns:
    bool: Optional description of the return value
    Extra lines are not indented.

  Raises:
    ValueError: Include any error types that the function intentionally
      raises.

  Notes:
    See https://www.datacamp.com/community/tutorials/docstrings-python
    for more info.  
  """
Writing Functions in Python

Numpydoc

def function(arg_1, arg_2=42):
  """
  Description of what the function does.

  Parameters
  ----------
  arg_1 : expected type of arg_1
    Description of arg_1.
  arg_2 : int, optional
    Write optional when an argument has a default value.
    Default=42.

  Returns
  -------
  The type of the return value
    Can include a description of the return value. 
    Replace "Returns" with "Yields" if this function is a generator.
  """
Writing Functions in Python

Retrieving docstrings

def the_answer():
  """Return the answer to life, 
  the universe, and everything.

  Returns:
    int
  """
  return 42

print(the_answer.__doc__)
Return the answer to life, 
  the universe, and everything.

  Returns:
    int
import inspect
print(inspect.getdoc(the_answer))
Return the answer to life, 
the universe, and everything.

Returns:
  int
Writing Functions in Python

Let's practice!

Writing Functions in Python

Preparing Video For Download...