Рядки документації

Написання функцій у Python

Shayne Miel

Software Architect @ Duo Security

Складна функція

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):
  """Розділяє стовпці DataFrame навпіл і стекає їх вертикально,
  повертаючи новий DataFrame з `new_names` як назвами стовпців.
  Args:

    df (DataFrame): DataFrame для розділення.
    new_names (iterable of str): Назви стовпців для нового 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
  )

Будова рядка документації

def function_name(arguments):
  """
  Опис того, що робить функція.

  Опис аргументів, якщо вони є.

  Опис значення(ь) що повертається, якщо є.

  Опис винятків, якщо піднімаються.

  Необов'язкові нотатки або приклади використання.
  """

Формати рядків документації

Google Style
Numpydoc
reStructuredText
EpyText

Стиль Google — опис

def function(arg_1, arg_2=42):
  """Опис того, що робить функція.
  """

Стиль Google — аргументи

def function(arg_1, arg_2=42):
  """Опис того, що робить функція.

  Args:
    arg_1 (str): Опис arg_1, який за потреби можна перенести
      на наступний рядок.
    arg_2 (int, optional): Пишіть optional, коли аргумент має
      значення за замовчуванням.
  """

Стиль Google — значення, що повертаються

def function(arg_1, arg_2=42):
  """Опис того, що робить функція.

  Args:
    arg_1 (str): Опис arg_1, який за потреби можна перенести
      на наступний рядок.
    arg_2 (int, optional): Пишіть optional, коли аргумент має
      значення за замовчуванням.

  Returns:
    bool: Необов'язковий опис значення, що повертається
    Додаткові рядки не відступаються.
  """

def function(arg_1, arg_2=42):
  """Опис того, що робить функція.

  Args:
    arg_1 (str): Опис arg_1, який за потреби можна перенести
      на наступний рядок.
    arg_2 (int, optional): Пишіть optional, коли аргумент має
      значення за замовчуванням.

  Returns:
    bool: Необов'язковий опис значення, що повертається
    Додаткові рядки не відступаються.

  Raises:
    ValueError: Укажіть усі типи помилок, які функція навмисно
      піднімає.

  Notes:
    Див. https://www.datacamp.com/community/tutorials/docstrings-python
    для докладнішої інформації.  
  """

Numpydoc

def function(arg_1, arg_2=42):
  """
  Опис того, що робить функція.

  Parameters
  ----------
  arg_1 : expected type of arg_1
    Опис arg_1.
  arg_2 : int, optional
    Пишіть optional, коли аргумент має значення за замовчуванням.
    Default=42.

  Returns
  -------
  Тип значення, що повертається
    Може містити опис значення, що повертається. 
    Замініть "Returns" на "Yields", якщо ця функція є генератором.
  """

Отримання рядків документації

def the_answer():
  """Повертає відповідь на життя, 
  Всесвіт і все інше.

  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

Давайте потренуємось!

Написання функцій у Python