Docstrings

Functies schrijven in Python

Shayne Miel

Software Architect @ Duo Security

Een complexe functie

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
  )

def split_and_stack(df, new_names):
  """Splits de kolommen van een DataFrame in twee helften en stapelt ze
  verticaal. Geeft een nieuw DataFrame terug met `new_names` als
  kolomnamen.

  Args:
    df (DataFrame): Het te splitsen DataFrame.
    new_names (iterable of str): De kolomnamen voor het nieuwe 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
  )

Anatomie van een docstring

def function_name(arguments):
  """
  Beschrijving van wat de functie doet.

  Beschrijving van de argumenten, indien aanwezig.

  Beschrijving van de returnwaarde(n), indien aanwezig.

  Beschrijving van opgegooide fouten, indien aanwezig.

  Optionele extra notities of gebruiksvoorbeelden.
  """

Docstring-formaten

Google-stijl
Numpydoc
reStructuredText
EpyText

Google-stijl - beschrijving

def function(arg_1, arg_2=42):
  """Beschrijving van wat de functie doet.
  """

Google-stijl - argumenten

def function(arg_1, arg_2=42):
  """Beschrijving van wat de functie doet.

  Args:
    arg_1 (str): Beschrijving van arg_1 die op de volgende regel kan
      doorgaan indien nodig.
    arg_2 (int, optional): Schrijf optional als een argument een
      standaardwaarde heeft.
  """

Google-stijl - returnwaarde(n)

def function(arg_1, arg_2=42):
  """Beschrijving van wat de functie doet.

  Args:
    arg_1 (str): Beschrijving van arg_1 die op de volgende regel kan
      doorgaan indien nodig.
    arg_2 (int, optional): Schrijf optional als een argument een
      standaardwaarde heeft.

  Returns:
    bool: Optionele beschrijving van de returnwaarde
    Extra regels worden niet ingesprongen.
  """

def function(arg_1, arg_2=42):
  """Beschrijving van wat de functie doet.

  Args:
    arg_1 (str): Beschrijving van arg_1 die op de volgende regel kan
      doorgaan indien nodig.
    arg_2 (int, optional): Schrijf optional als een argument een
      standaardwaarde heeft.

  Returns:
    bool: Optionele beschrijving van de returnwaarde
    Extra regels worden niet ingesprongen.

  Raises:
    ValueError: Neem fouttypen op die de functie bewust
      opwerpt.

  Notes:
    Zie https://www.datacamp.com/community/tutorials/docstrings-python
    voor meer info.  
  """

Numpydoc

def function(arg_1, arg_2=42):
  """
  Beschrijving van wat de functie doet.

  Parameters
  ----------
  arg_1 : verwacht type van arg_1
    Beschrijving van arg_1.
  arg_2 : int, optional
    Schrijf optional als een argument een standaardwaarde heeft.
    Default=42.

  Returns
  -------
  Het type van de returnwaarde
    Kan een beschrijving van de returnwaarde bevatten. 
    Vervang "Returns" door "Yields" als deze functie een generator is.
  """

Docstrings opvragen

def the_answer():
  """Geef het antwoord op het leven, 
  het universum en de rest.

  Returns:
    int
  """
  return 42

print(the_answer.__doc__)

Geef het antwoord op het leven, 
  het universum en de rest.

  Returns:
    int

import inspect
print(inspect.getdoc(the_answer))

Geef het antwoord op het leven, 
het universum en de rest.

Returns:
  int

Laten we oefenen!

Functies schrijven in Python