Docstring'ler

Python'da Fonksiyon Yazımı

Shayne Miel

Software Architect @ Duo Security

Karmaşık bir fonksiyon

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):
  """Bir DataFrame'in sütunlarını ikiye bölüp
  dikey olarak istifler ve sütun adları `new_names` olan yeni bir
  DataFrame döndürür.

  Args:
    df (DataFrame): Bölünecek DataFrame.
    new_names (iterable of str): Yeni DataFrame için sütun adları.

  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
  )

Bir docstring'in yapısı

def function_name(arguments):
  """
  Fonksiyonun ne yaptığının açıklaması.

  Argümanların açıklaması (varsa).

  Döndürme değeri/lerinin açıklaması (varsa).

  Yükseltilen hataların açıklaması (varsa).

  İsteğe bağlı ek notlar veya kullanım örnekleri.
  """

Docstring biçimleri

Google Stili
Numpydoc
reStructuredText
EpyText

Google stili - açıklama

def function(arg_1, arg_2=42):
  """Fonksiyonun ne yaptığının açıklaması.
  """

Google stili - argümanlar

def function(arg_1, arg_2=42):
  """Fonksiyonun ne yaptığının açıklaması.

  Args:
    arg_1 (str): Gerekirse bir sonraki satıra
      taşınabilen arg_1 açıklaması.
    arg_2 (int, optional): Bir argümanın varsayılan değeri varsa
      optional yazın.
  """

Google stili - döndürme değeri/leri

def function(arg_1, arg_2=42):
  """Fonksiyonun ne yaptığının açıklaması.

  Args:
    arg_1 (str): Gerekirse bir sonraki satıra
      taşınabilen arg_1 açıklaması.
    arg_2 (int, optional): Bir argümanın varsayılan değeri varsa
      optional yazın.

  Returns:
    bool: Döndürme değerinin isteğe bağlı açıklaması
    Ek satırlar girintilenmez.
  """

def function(arg_1, arg_2=42):
  """Fonksiyonun ne yaptığının açıklaması.

  Args:
    arg_1 (str): Gerekirse bir sonraki satıra
      taşınabilen arg_1 açıklaması.
    arg_2 (int, optional): Bir argümanın varsayılan değeri varsa
      optional yazın.

  Returns:
    bool: Döndürme değerinin isteğe bağlı açıklaması
    Ek satırlar girintilenmez.

  Raises:
    ValueError: Fonksiyonun bilerek yükselttiği hata
      türlerini ekleyin.

  Notes:
    Daha fazla bilgi için bkz. https://www.datacamp.com/community/tutorials/docstrings-python

  """

Numpydoc

def function(arg_1, arg_2=42):
  """
  Fonksiyonun ne yaptığının açıklaması.

  Parameters
  ----------
  arg_1 : arg_1 için beklenen tür
    arg_1 açıklaması.
  arg_2 : int, optional
    Bir argümanın varsayılan değeri varsa optional yazın.
    Default=42.

  Returns
  -------
  Döndürme değerinin türü
    Döndürme değerinin açıklaması eklenebilir. 
    Bu fonksiyon bir üreteçse "Returns" yerine "Yields" kullanın.
  """

Docstring alma

def the_answer():
  """Hayatın, 
  evrenin ve her şeyin yanıtını döndürür.

  Returns:
    int
  """
  return 42

print(the_answer.__doc__)

Hayatın, 
  evrenin ve her şeyin yanıtını döndürür.

  Returns:
    int

import inspect
print(inspect.getdoc(the_answer))

Hayatın, 
evrenin ve her şeyin yanıtını döndürür.

Returns:
  int

Hadi pratik yapalım!

Python'da Fonksiyon Yazımı