Docstrings

Como escrever funções em Python

Shayne Miel

Software Architect @ Duo Security

Uma função complexa

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 as colunas de um DataFrame em duas metades e empilha
  verticalmente, retornando um novo DataFrame com `new_names` como
  nomes das colunas.

  Args:
    df (DataFrame): O DataFrame a dividir.
    new_names (iterable of str): Os nomes das colunas do novo 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
  )

Anatomia de uma docstring

def function_name(arguments):
  """
  Descrição do que a função faz.

  Descrição dos argumentos, se houver.

  Descrição do(s) valor(es) de retorno, se houver.

  Descrição dos erros gerados, se houver.

  Notas extras ou exemplos de uso (opcional).
  """

Formatos de docstring

Estilo Google
Numpydoc
reStructuredText
EpyText

Estilo Google - descrição

def function(arg_1, arg_2=42):
  """Descrição do que a função faz.
  """

Estilo Google - argumentos

def function(arg_1, arg_2=42):
  """Descrição do que a função faz.

  Args:
    arg_1 (str): Descrição de arg_1 que pode quebrar na próxima linha
      se precisar.
    arg_2 (int, optional): Use optional quando o argumento tiver valor
      padrão.
  """

Estilo Google - valor(es) de retorno

def function(arg_1, arg_2=42):
  """Descrição do que a função faz.

  Args:
    arg_1 (str): Descrição de arg_1 que pode quebrar na próxima linha
      se precisar.
    arg_2 (int, optional): Use optional quando o argumento tiver valor
      padrão.

  Returns:
    bool: Descrição opcional do valor de retorno
    Linhas extras não são indentadas.
  """

def function(arg_1, arg_2=42):
  """Descrição do que a função faz.

  Args:
    arg_1 (str): Descrição de arg_1 que pode quebrar na próxima linha
      se precisar.
    arg_2 (int, optional): Use optional quando o argumento tiver valor
      padrão.

  Returns:
    bool: Descrição opcional do valor de retorno
    Linhas extras não são indentadas.

  Raises:
    ValueError: Inclua os tipos de erro que a função gera
      intencionalmente.

  Notes:
    Veja https://www.datacamp.com/community/tutorials/docstrings-python
    para mais informações.  
  """

Numpydoc

def function(arg_1, arg_2=42):
  """
  Descrição do que a função faz.

  Parameters
  ----------
  arg_1 : tipo esperado de arg_1
    Descrição de arg_1.
  arg_2 : int, optional
    Use optional quando o argumento tiver valor padrão.
    Default=42.

  Returns
  -------
  Tipo do valor de retorno
    Pode incluir uma descrição do valor retornado.
    Troque "Returns" por "Yields" se a função for um gerador.
  """

Recuperando docstrings

def the_answer():
  """Retorna a resposta para a vida,
  o universo e tudo mais.

  Returns:
    int
  """
  return 42

print(the_answer.__doc__)

Retorna a resposta para a vida, 
  o universo e tudo mais.

  Returns:
    int

import inspect
print(inspect.getdoc(the_answer))

Retorna a resposta para a vida, 
o universo e tudo mais.

Returns:
  int

Vamos praticar!

Como escrever funções em Python