Docstrings in Python

B.ZAMANLeave a Comment on Docstrings in Python

Docstrings in Python

Docstring or documentation strings provide a suitable way of associating documentation with Python modules, functions, classes, and methods.

डॉकस्ट्रिंग या डॉक्यूमेंटेशन स्ट्रिंग्स पायथन मॉड्यूल, फंक्शंस, क्लासेज और मेथड के साथ प्रलेखन को जोड़ने का एक उपयुक्त तरीका प्रदान करते हैं।

It’s specified in source code that is used, like a comment, to document a specific segment of code. Unlike conventional source code comments, the docstring should describe what the function does, not how.

यह सोर्स कोड में निर्दिष्ट है, जिसका उपयोग कोड के एक विशिष्ट खंड को डॉक्यूमेंट करने के लिए एक टिप्पणी की तरह किया जाता है। पारंपरिक सोर्स कोड टिप्पणियों के विपरीत, डॉकस्ट्रिंग को यह वर्णन करना चाहिए कि फंक्शन क्या करता है, कैसे नहीं।

All functions should have a docstring, this allows the program to inspect these comments at run time, for instance as an interactive help system, or as metadata.

सभी फंक्शंस में एक डॉकस्ट्रिंग होना चाहिए, इससे प्रोग्राम को रन टाइम पर इन टिप्पणियों का निरीक्षण करने की अनुमति मिलती है, उदाहरण के लिए एक इंटरैक्टिव हेल्प सिस्टम या मेटाडेटा के रूप में।

How should a Docstring look like?
डॉकस्ट्रिंग कैसा दिखना चाहिए?

  • The doc string line should begin with a capital letter and end with a period.

डॉक स्टिंग लाइन को एक बड़े अक्षर से शुरू होना चाहिए और एक अवधि के साथ समाप्त होना चाहिए।

  • The first line should be a short description.

पहली पंक्ति का संक्षिप्त विवरण होना चाहिए।

  • Don’t write the name of the object.

ऑब्जेक्ट का नाम न लिखें।

  • If there are more lines in the documentation string, the second line should be blank, visually separating the summary from the rest of the description.

यदि डाक्यूमेंट स्ट्रिंग में अधिक लाइनें हैं, तो दूसरी पंक्ति रिक्त होनी चाहिए, विजुअली बाकी विवरण से सारांश को अलग करना चाहिए।

  • The following lines should be one or more paragraphs describing the object’s calling conventions, its side effects, etc.

निम्नलिखित लाइनें एक या एक से अधिक पैराग्राफ होनी चाहिए जो ऑब्जेक्ट के कॉलिंग कन्वेंशन, इसके दुष्प्रभाव आदि का वर्णन करती हैं।

Declaring Docstrings – डॉकस्ट्रिंग की घोषणा

The docstrings are declared using “””triple double quotes”‘” just below the class or function declaration. All functions should have a docstring.

क्लास या फंक्शन डिक्लेरेशन के ठीक नीचे “””ट्रिपल डबल कोट्स”” का इस्तेमाल करते हुए डॉकस्ट्रिंग्स घोषित किए जाते हैं। सभी कार्यों में एक डॉकस्ट्रिंग होना चाहिए।

1.One-line Docstrings: As the name suggests, one line docstrings fit in one line. They are used in obvious cases. The closing quotes are on the same line as the opening quotes. This looks better for one-liners.

वन-लाईन डॉकस्ट्रिंग: जैसा कि नाम से पता चलता है, एक लाइन डॉकस्ट्रिंग एक लाइन में फिट होती है। उनका उपयोग स्पष्ट मामलों में किया जाता है। शुरुआती कोट्स उसी पंक्ति पर हैं जो शुरुआती कोट्स हैं। यह वन-लाइनर्स के लिए बेहतर दिखता है।
Example:

def power (a, b):
    """Returns arg1_raised to power arg2 . """
    return a**b

2.Multi-line Docstrings: Multi-line docstrings consist of a summary line just like a one-line docstring, followed by a blank line, followed by a more elaborate description. The summary line may be on the same line as the opening quotes or on the next line.

मल्टी-लाईन डॉकस्ट्रिंग: मल्टी-लाइन डॉकस्ट्रिंग्स में एक-लाइन डॉकस्ट्रिंग की तरह एक सारांश लाइन होती है, उसके बाद एक खाली लाइन, जिसके बाद एक अधिक विस्तृत विवरण होता है। समरी लाईन ओपनिंग लाईन या अगली पंक्ति के समान रेखा पर हो सकती है।
Example: 

def my_function (argl):
    """
    Summary line.
    Extended description of function.
    Parameters: 
    arg1 (int) : Description of arg1
    Returns: 
    int: Description of return value
    """
    return arg1

The following Python file shows the declaration of docstrings within a python source file:
निम्नलिखित पायथन फाइल एक पायथन सोर्स फाइल के भीतर डॉकस्ट्रिंग्स की घोषणा को दर्शाती है:

"""
Assuming this is file myModule.py, then this string, being the
first statement in the file, will become the "myModule" module's
docstring when the file is imported
"""
class MyClass (object):
    """The class's docstring"""
    def my_method (self) :
        """The method's docstring"""
def my_function():
    """The function s docstring"""

Accessing Docstrings 
डॉकस्ट्रिंग्स एक्सेस करना

The docstrings can be accessed using the _doc_method of the object or using the help function.

डॉकस्ट्रिंग्स को ऑब्जेक्ट के _doc_ विधि का उपयोग करके या सहायता फंक्शन का उपयोग करके एक्सेस किया जा सकता है।
Example:

def myFun () :
    """Demonstrate docstrings."""
    return None
print ("Using __doc_: ") 
print (myFun.__doc__ )
print ("Using help : ") 
help (myFun)

Output:
Using __doc_:
Demonstrate docstrings.
Using help :
Help on function myFun in module __main__:
myFun()
    Demonstrate docstrings.

Global Statement – ग्लोबल स्टेटमेंट

The global statement is the only thing that’s anything like a declaration in Python. It tells Python that a function plans to change global names; names that live in the enclosing module’s scope (namespace).

ग्लोबल स्टेटमेंट पायथन में एक declaration की तरह है। यह पायथन को बताता है कि एक फंक्शन ग्लोबल नामों को बदलने की योजना बना रहा है, वे नाम जो संलग्न मॉड्यूल के दायरे में रहते हैं (नेमस्पेस)।

  • Global means “a name at the top-level of a module file.

” वैश्विक का अर्थ है “एक मॉड्यूल फाइल के शीर्ष-स्तर पर एक नाम।”

  • Global names must be declared only if they are assigned in a function.

 वैश्विक नामों को केवल तभी घोषित किया जाना चाहिए जब उन्हें किसी फंक्शन में सौंपा गया हो।

  • Global names may be referenced in a function without being declared. घोषित किए बिना किसी फंक्शन में ग्लोबल नामों को संदर्भित किया जा सकता है।

The global statement is just the keyword global, followed by one or more names separated by commas. All the listed names will be mapped to the enclosing module’s scope when assigned or referenced within the function body.

ग्लोबल स्टेटमेंट सिर्फ कीवर्ड ग्लोबल है, इसके बाद एक या एक से अधिक नाम कॉमा द्वारा अलग किए जाते हैं। सभी सूचीबद्ध नामों को फंक्शन बॉडी के भीतर निर्दिष्ट या संदर्भित किए जाने पर संलग्नक मॉड्यूल के दायरे में मैप किया जाएगा।
For example:

y, z = 1, 2 #global variables in module
def all_global():
    global x # declare globals assigned
    x = y + z # no need to declare y, z: 3-scope rule
    print (x)
all_global() 
print (x)

Output:
3
3
Here, x, y, and z are all global inside function all global. y and z are global because they aren’t assigned in the function; x is global because we said so: we listed it in a global statement to map it to the module’s scope explicitly. Without the global here, x would be considered local by virtue of the assignment. Notice that y and z are not declared global; Python’s LGB lookup rule finds them in the module automatically. Also notice that x might not exist in the enclosing module before the function runs; if not, the assignment in the function creates x in the module.

यहाँ, x, y और z सभी ग्लोबल्स हैं जो फंक्शन all global के अंदर हैं। y और z ग्लोबल हैं क्योंकि वे कार्य में नियत नहीं हैं, x ग्लोबल है क्योंकि हमने ऐसा कहा था, हमने इसे स्पष्ट रूप से मॉड्यूल के दायरे में मैप करने के लिए एक वैश्विक वक्तव्य में सूचीबद्ध किया था। यहां ग्लोबल के बिना, x को असाइनमेंट के आधार पर लोकल माना जाएगा। ध्यान दें कि y और z को वैश्विक घोषित नहीं किया गया है, पायथन का LGB लुकअप नियम उन्हें मॉड्यूल में स्वचालित रूप से ढूंढता है। यह भी ध्यान दें कि x फंक्शन के चलने से पहले संलग्नक मॉड्यूल में मौजूद नहीं हो सकता है, यदि नहीं, तो फंक्शन में असाइनमेंट मॉड्यूल में x बनाता है।

Depth on Defining a function
एक फंक्शन को परिभाषित करना

Functions are common to all programming languages, and it can be defined as a block of re-usable code to perform specific tasks.

फंक्शंस सभी प्रोग्रामिंग भाषाओं के लिए आम हैं, और इसे विशिष्ट कार्यों को करने के लिए पुनः प्रयोज्य कोड के एक ब्लॉक के रूप में परिभाषित किया जा सकता है।

But defining functions in Python in two ways…

लेकिन पायथन में कार्यों को दो तरीकों से परिभाषित करना.

1. Built-in functions or Library functions are usually a part of Python packages and libraries

बिल्ट-इन फंक्शन या लाइब्रेरी फंक्शंस आमतौर पर पायथन पैकेज और लाइब्रेरी का एक हिस्सा होते हैं।

2. User-defined functions are written by the developers to meet certain requirements. In Python, all functions are treated as objects, so it is more flexible compared to other high-level languages.

यूजर-डिफाईन फंक्शन डेवलपर्स द्वारा कुछ आवश्यकताओं को पूरा करने के लिए लिखे गए हैं। पायथन में, सभी कार्यों को वस्तुओं के रूप में माना जाता है, इसलिए यह अन्य उच्च-स्तरीय भाषाओं की तुलना में अधिक लचीला

Already we have a basic understanding of user defined functions, let’s have a look at different function arguments in Python.

पहले से ही हमारे पास उपयोगकर्ता परिभाषित कार्यों की एक बुनियादी समझ है, आइए पायथन में विभिन्न फंक्शन तर्कों पर एक नजर डालें।
Example: 

def fun (a, b):
    print ("first statement")
    print ("end statement")
    return None 
fun (10,20)

Output:
first statement
end statement

In the above example, in fun a, b are formal arguments where as 10, 20 are actual arguments. There are four types of actual arguments.

उपरोक्त उदाहरण में a, b औपचारिक तर्क हैं जहां 10, 20 वास्तविक तर्क हैं। वास्तविक तर्क के चार प्रकार हैं

1. Positional arguments or required arguments
 स्थिति संबंधी तर्क या आवश्यक तर्क
2. Keyword arguments
कीवर्ड तर्क
3. Default arguments
डिफाल्ट तक
4. Variable-length arguments
वैरियेबल लेंथ तर्क

Positional Arguments or Required Arguments
स्थिति संबंधी तर्क या आवश्यक तर्क

Required arguments are the mandatory arguments of a function. These argument values must be passed in correct number and order during function call.

आवश्यक तर्क एक फंक्शन के अनिवार्य तर्क हैं। इन तर्क मानों को फंक्शन कॉल के दौरान सही संख्या और क्रम में पारित किया जाना चाहिए।
Example 1:

def reqArgFun (a, b) :
    print (a, b)
reqArgFun (12, 100) 
reqArgFun (100, 12)

Output:
12 100
100 12

Here, the number of arguments and position of the arguments must be matched. If we change the order then result may be changed.

यहां, तर्कों की संख्या और तर्कों की स्थिति का मिलान किया जाना चाहिए। यदि हम क्रम बदलते हैं तो परिणाम बदल सकता है।

Example 2: In this example argument values passed in incorrect order during function call.
उदाहरण 2: इस उदाहरण में तर्क मान फंक्शन कॉल के दौरान गलत क्रम में पारित हुए।

def reqArgFun (num, str) :
    print (num, str) 
reqArgFun (12, "apple") 
reqArgFun ("apple", 12)

Output:
12 apple
apple 12

Chapter wise Model Paper Link

About Me

B.ZAMAN

Leave a Reply

Your email address will not be published. Required fields are marked *