Docstrings

Python में Functions लिखना

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
  )

Docstring की संरचना

def function_name(arguments):
  """
  फंक्शन क्या करता है, इसका संक्षिप्त वर्णन।

  आर्ग्यूमेंट्स का विवरण, यदि हों।

  रिटर्न वैल्यू(ज़) का विवरण, यदि हों।

  उठने वाली त्रुटियों का विवरण, यदि हों।

  वैकल्पिक अतिरिक्त नोट्स या उपयोग के उदाहरण।
  """

Docstring फ़ॉर्मैट्स

Google Style
Numpydoc
reStructuredText
EpyText

Google Style - विवरण

def function(arg_1, arg_2=42):
  """फंक्शन क्या करता है, इसका वर्णन।
  """

Google style - आर्ग्यूमेंट्स

def function(arg_1, arg_2=42):
  """फंक्शन क्या करता है, इसका वर्णन।

  Args:
    arg_1 (str): arg_1 का विवरण, ज़रूरत हो तो अगली लाइन पर जा सकता है।
    arg_2 (int, optional): जब आर्ग्यूमेंट की डिफॉल्ट वैल्यू हो तो optional लिखें।
  """

Google style - रिटर्न वैल्यू(ज़)

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:
    See https://www.datacamp.com/community/tutorials/docstrings-python
    for more info.  

  """

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" से बदलें।
  """

Docstrings निकालना

def the_answer():
  """Return the answer to life, 
  the universe, and everything.

  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 में Functions लिखना