Docstrings

Escribir funciones en Python

Shayne Miel

Software Architect @ Duo Security

Una función compleja

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):
  """Divide las columnas de un DataFrame en dos mitades y luego apílalas
  verticalmente; devuelve un nuevo DataFrame con `new_names` como
  nombres de columna.

  Args:
    df (DataFrame): El DataFrame a dividir.
    new_names (iterable of str): Los nombres de columna del nuevo 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
  )

Anatomía de un docstring

def function_name(arguments):
  """
  Descripción de lo que hace la función.

  Descripción de los argumentos, si los hay.

  Descripción de los valores de retorno, si los hay.

  Descripción de los errores lanzados, si los hay.

  Notas extra u ejemplos de uso opcionales.
  """

Formatos de docstring

Estilo Google
Numpydoc
reStructuredText
EpyText

Estilo Google: descripción

def function(arg_1, arg_2=42):
  """Descripción de lo que hace la función.
  """

Estilo Google: argumentos

def function(arg_1, arg_2=42):
  """Descripción de lo que hace la función.

  Args:
    arg_1 (str): Descripción de arg_1 que puede pasar a la siguiente línea
      si es necesario.
    arg_2 (int, optional): Escribe optional cuando un argumento tiene
      un valor por defecto.
  """

Estilo Google: valor(es) de retorno

def function(arg_1, arg_2=42):
  """Descripción de lo que hace la función.

  Args:
    arg_1 (str): Descripción de arg_1 que puede pasar a la siguiente línea
      si es necesario.
    arg_2 (int, optional): Escribe optional cuando un argumento tiene
      un valor por defecto.

  Returns:
    bool: Descripción opcional del valor de retorno
    Las líneas extra no llevan sangría.
  """

def function(arg_1, arg_2=42):
  """Descripción de lo que hace la función.

  Args:
    arg_1 (str): Descripción de arg_1 que puede pasar a la siguiente línea
      si es necesario.
    arg_2 (int, optional): Escribe optional cuando un argumento tiene
      un valor por defecto.

  Returns:
    bool: Descripción opcional del valor de retorno
    Las líneas extra no llevan sangría.

  Raises:
    ValueError: Incluye los tipos de error que la función lanza
      intencionalmente.

  Notes:
    Ver https://www.datacamp.com/community/tutorials/docstrings-python
    para más información.  
  """

Numpydoc

def function(arg_1, arg_2=42):
  """
  Descripción de lo que hace la función.

  Parameters
  ----------
  arg_1 : tipo esperado de arg_1
    Descripción de arg_1.
  arg_2 : int, optional
    Escribe optional cuando un argumento tiene un valor por defecto.
    Default=42.

  Returns
  -------
  Tipo del valor de retorno
    Puede incluir una descripción del valor de retorno. 
    Sustituye "Returns" por "Yields" si esta función es un generador.
  """

Recuperar docstrings

def the_answer():
  """Devuelve la respuesta a la vida, 
  el universo y todo lo demás.

  Returns:
    int
  """
  return 42

print(the_answer.__doc__)

Devuelve la respuesta a la vida, 
  el universo y todo lo demás.

  Returns:
    int

import inspect
print(inspect.getdoc(the_answer))

Devuelve la respuesta a la vida, 
el universo y todo lo demás.

Returns:
  int

¡Vamos a practicar!

Escribir funciones en Python