독스트링

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 열을 반으로 나눈 뒤 세로로 쌓아,
  열 이름을 `new_names`로 하는 새 DataFrame을 반환합니다.
  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 스타일
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 : 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__)


삶, 우주, 모든 것의 정답을 반환합니다.
  Returns:
    int

import inspect
print(inspect.getdoc(the_answer))

삶, 우주, 모든 것의 정답을 반환합니다.
Returns:

  int

연습해 봅시다!

Python으로 함수 작성하기