سیستم راهنمای پایتون

هنگام نوشتن و اجرای برنامه های پایتون، ممکن است گیر کرده و نیاز به کمک داشته باشید. ممکن است لازم باشد معنی ماژول‌ها، کلاس‌ها، توابع، کلمات کلیدی و غیره را بدانید. خبر خوب این است که پایتون با یک سیستم کمک داخلی ارائه می‌شود. این بدان معناست که شما مجبور نیستید خارج از پایتون به دنبال کمک باشید.

در این مقاله روش استفاده از سیستم راهنمای داخلی پایتون را یاد خواهید گرفت.

پایتون help() تابع

این تابع به ما کمک می کند تا مستندات یک کلاس، تابع، متغیر، ماژول و غیره خاص را بدست آوریم. تابع باید استفاده شود. روی پایتون console برای دریافت جزئیات اشیاء مختلف پایتون.

ارسال یک شی به تابع help().

پایتون help() تابع دارای نحو زیر است:

>>> help(object)

در نحو بالا، the object پارامتر نام شیئی است که برای دریافت کمک در مورد آن نیاز دارید.

به عنوان مثال، برای دانستن بیشتر در مورد Python print تابع، دستور زیر را تایپ کنید روی پایتون console:

>>> help(print)

خروجی:

Help روی built-in function print in module builtins:

print(...)
    print(value, ..., sep=' ', end='\n', file=sys.stdout, flush=False)
    
    Prints the values to a stream, or to sys.stdout by default.
    Optional keyword arguments:
    file:  a file-like object (stream); defaults to the current sys.stdout.
    sep:   string inserted between values, default a space.
    end:   string appended after the last value, default a newline.
    flush: whether to forcibly flush the stream.

برای کمک گرفتن برای dict کلاس زیر را تایپ کنید روی پایتون console:

>>> help(dict)

خروجی:

Help روی class dict in module builtins:

class dict(object)
 |  dict() -> new empty dictionary
 |  dict(mapping) -> new dictionary initialized from a mapping object's
 |      (key, value) pairs
 |  dict(iterable) -> new dictionary initialized as if via:
 |      d = {}
 |      for k, v in iterable:
 |          d(k) = v
 |  dict(**kwargs) -> new dictionary initialized with the name=value pairs
 |      in the keyword argument list.  For example:  dict(one=1, two=2)
 |  
 |  Methods defined here:
 |  
 |  __contains__(self, key, /)
 |      True if D has a key k, else False.
 |  
 |  __delitem__(self, key, /)
 |      Delete self(key).
 |  
 |  __eq__(self, value, /)
 |      Return self==value.
 |  
 |  __ge__(self, value, /)
 |      Return self>=value.
 |  

...

شما همچنین می توانید یک شی لیست واقعی را به آن ارسال کنید help() تابع:

>>> help(('a', 'b', 'c'))

خروجی:

Help روی list object:

class list(object)
 |  list() -> new empty list
 |  list(iterable) -> new list initialized from iterable's items
 |  
 |  Methods defined here:
 |  
 |  __add__(self, value, /)
 |      Return self+value.
 |  
 |  __contains__(self, key, /)
 |      Return key in self.
 |  
 |  __delitem__(self, key, /)
 |      Delete self(key).
 |  
 |  __eq__(self, value, /)
 |      Return self==value.
 |  
 |  __ge__(self, value, /)
 |      Return self>=value.
 |  
 |  __getattribute__(self, name, /)
 |      Return getattr(self, name).

...

ما می توانیم ببینیم که وقتی یک شی را به آن پاس می دهید help() تابع، مستندات یا کمک آن page چاپ می شود. در بخش بعدی، با ارسال آرگومان های رشته ای به آن آشنا خواهید شد help() تابع.

ارسال یک آرگومان رشته ای به help()

اگر رشته ای را به عنوان آرگومان ارسال کنید، رشته به عنوان نام یک تابع، ماژول، کلمه کلیدی، متد، کلاس یا موضوع مستندسازی و راهنمای مربوطه در نظر گرفته می شود. page چاپ خواهد شد. برای علامت گذاری آن به عنوان یک آرگومان رشته ای، آن را در یک یا دو گیومه قرار دهید.

مثلا:

>>> help('print')

خروجی:

Help روی built-in function print in module builtins:

print(...)
    print(value, ..., sep=' ', end='\n', file=sys.stdout, flush=False)
    
    Prints the values to a stream, or to sys.stdout by default.
    Optional keyword arguments:
    file:  a file-like object (stream); defaults to the current sys.stdout.
    sep:   string inserted between values, default a space.
    end:   string appended after the last value, default a newline.
    flush: whether to forcibly flush the stream.

اگرچه گذشتیمprintبه عنوان یک آرگومان رشته ای، ما هنوز مستندات پایتون را دریافت کردیم print تابع. در اینجا یک مثال دیگر وجود دارد:

>>> help('def')

خروجی:

Function definitions
********************

A function definition defines a user-defined function object (see
section *The standard type hierarchy*):

   funcdef        ::= (decorators) "def" funcname "(" (parameter_list) ")" ("->" expression) ":" suite
   decorators     ::= decorator+
   decorator      ::= "@" dotted_name ("(" (parameter_list (",")) ")") NEWLINE
   dotted_name    ::= identifier ("." identifier)*
   parameter_list ::= (defparameter ",")*
                      | "*" (parameter) ("," defparameter)* ("," "**" parameter)
                      | "**" parameter
                      | defparameter (",") )
   parameter      ::= identifier (":" expression)
   defparameter   ::= parameter ("=" expression)
   funcname       ::= identifier

A function definition is an executable statement.  Its execution binds
the function name in the current local namespace to a function object
(a wrapper around the executable code for the function).  This

...

در اینجا ما “def” را به عنوان یک آرگومان رشته ای به رمز عبور دادیم help() تابع و مستندات را برای تعریف توابع برگرداند.

اگر شیء، متد، تابع، کلاس یا ماژول منطبقی یافت نشد، به شما اطلاع داده خواهد شد. مثلا:

>>> help('qwerty')

خروجی:

No Python documentation found for 'qwerty'.
Use help() to get the interactive help utility.
Use help(str) for help روی the str class.

به ما اطلاع داده شده است که هیچ سندی برای رشته ما یافت نشد.

گاهی اوقات، ممکن است نیاز داشته باشیم در مورد یک تابع خاص که در یک کتابخانه خاص پایتون تعریف شده است، کمک بگیریم. این مستلزم این است که ابتدا ما import کتابخانه. یک مثال خوب زمانی است که ما نیاز به دریافت اسناد برای آن داریم log تابع تعریف شده در پایتون math کتابخانه در این مورد، ابتدا نیاز داریم import را math کتابخانه سپس ما به آن زنگ می زنیم help() عملکردی که در زیر نشان داده شده است:

>>> from math import log
>>> help(log)

خروجی:

Help روی built-in function log in module math:

log(...)
    log(x(, base))
    
    Return the logarithm of x to the given base.
    If the base is not specified, returns the natural logarithm (base e) of x.

استفاده کردن help() بدون هیچ استدلال

را help() تابع بدون آرگومان قابل استفاده است. اگر تابع را بدون آرگومان اجرا کنید، ابزار کمکی تعاملی پایتون راه اندازی می شود روی مترجم console. فقط باید دستور زیر را تایپ کنید روی پایتون console:

>>> help()

این ابزار کمکی پایتون را برمی گرداند روی که می توانید نام شی مورد نیاز برای دریافت کمک را تایپ کنید. مثلا:

help> print

خروجی:

Help روی built-in function print in module builtins:

print(...)
    print(value, ..., sep=' ', end='\n', file=sys.stdout, flush=False)
    
    Prints the values to a stream, or to sys.stdout by default.
    Optional keyword arguments:
    file:  a file-like object (stream); defaults to the current sys.stdout.
    sep:   string inserted between values, default a space.
    end:   string appended after the last value, default a newline.
    flush: whether to forcibly flush the stream.

برای بازگشت به دستور قبلی، فقط “q” را فشار دهید.

در اینجا یک مثال دیگر وجود دارد:

help> return

خروجی:

The "return" statement
**********************

   return_stmt ::= "return" (expression_list)

"return" may only occur syntactically nested in a function definition,
not within a nested class definition.

If an expression list is present, it is evaluated, else "None" is
substituted.

"return" leaves the current function call with the expression list (or
"None") as return value.

When "return" passes control out of a "try" statement with a "finally"
clause, that "finally" clause is executed before really leaving the
function.

In a generator function, the "return" statement indicates that the
generator is done and will cause "StopIteration" to be raised. The
returned value (if any) is used as an argument to construct
"StopIteration" and becomes the "StopIteration.value" attribute.

Related help topics: FUNCTIONS

برای خروج از ابزار کمکی و بازگشت به پایتون console، کافی است «quit» را تایپ کنید و کلید enter را بزنید:

help> quit

خروجی:

You are now leaving help and returning to the Python interpreter.
If you want to ask for help روی a particular object directly from the
interpreter, you can type "help(object)".  Executing "help('string')"
has the same effect as typing a particular string at the help> prompt.
>>>

در بخش بعدی روش تعریف را مورد بحث قرار خواهیم داد help() برای اشیاء سفارشی ما

تعریف اسناد راهنما برای توابع و کلاس‌های سفارشی

برای ما امکان تعریف خروجی وجود دارد help() تابع برای توابع و کلاس های سفارشی ما با تعریف رشته docstring (رشته سند). در پایتون، اولین رشته کامنتی که به بدنه یک متد اضافه می شود، به عنوان رشته مستند آن تلقی می شود. نظر باید با سه نقل قول دوتایی احاطه شود. مثلا:

def product(a, b):
    """
    This function multiplies two given integers, a and b
    :param x: integer
    :param y: integer
    :returns: integer
    """
    return a * b

در مثال بالا تابعی به نام تعریف کرده ایم product. این تابع دو مقدار صحیح را ضرب می کند، a و b به عنوان آرگومان/پارامتر به آن منتقل می شود. نظر ضمیمه شده در سه نقل قول را ببینید:

    """
    This function multiplies two given integers, a and b
    :param x: integer
    :param y: integer
    :returns: integer
    """

این به عنوان رشته مستند برای تابع در نظر گرفته می شود product.

حالا یک فایل جدید بسازید و اسمش را بگذارید myfile.py. کد زیر را به فایل اضافه کنید:

def product(a, b):
    """
    This function multiplies two given integers, a and b
    :param x: integer
    :param y: integer
    :returns: integer
    """
    return a * b

class Student:
    """
    Student class in Python. It will store student details
    """
    admission = 0
    name = ''

    def __init__(self, adm, n):
        """
        A constructor of the student object
        :param adm: a positive integer,
        :param n: a string
        """
        self.admission = adm
        self.name = n

در مثال بالا یک docstring برای یک تابع، کلاس و متدها تعریف شده است.

اکنون باید نشان دهیم که چگونه می توانیم مدارک فوق را به عنوان مستندات کمکی دریافت کنیم روی پایتون ما console.

ابتدا باید اسکریپت را اجرا کنیم روی را console به منظور بارگذاری هر دو تابع و تعریف کلاس در محیط پایتون. ما می توانیم از پایتون استفاده کنیم exec() روش برای این دستور زیر را اجرا کنید روی پایتون console:

>>> exec(open("myfile.py").read())

از طرف دیگر، اگر کد را در Python IDLE نوشته اید، به سادگی باید آن را اجرا کنید.

اکنون می توانیم تأیید کنیم که آیا ماژول های تابع و کلاس با اجرای آن شناسایی شده اند globals() فرمان روی پایتون console:

>>> globals()

در مورد من، خروجی زیر را دریافت می کنم:

{'__doc__': None, 'log': <built-in function log>, '__builtins__': <module 'builtins' (built-in)>, '__spec__': None, '__package__': None, '__name__': '__main__', '__loader__': <class '_frozen_importlib.BuiltinImporter'>, '__file__': 'C:/Users/admin/myfile.py', 'Student': <class '__main__.Student', 'product': <function product at 0x0000000003569B70>}

همانطور که در خروجی بالا نشان داده شده است، هر دو Student و product در فرهنگ لغت جهانی هستند. اکنون می توانیم از help() تابع برای دریافت کمک برای Student کلاس و product تابع. کافیست دستور زیر را اجرا کنید روی پایتون console:

>>> help('myfile')

خروجی:

Help روی module `myfile`:

NAME
    myfile

CLASSES
    builtins.object
        Student
    
    class Student(builtins.object)
     |  Student class in Python. It will store student details
     |  
     |  Methods defined here:
     |  
     |  __init__(self, adm, n)
     |      A constructor of the student object
     |      :param adm: a positive integer,
     |      :param n: a string
     |  
     |  ----------------------------------------------------------------------
     |  Data descriptors defined here:
     |  
     |  __dict__
     |      dictionary for instance variables (if defined)
     |  
     |  __weakref__
     |      list of weak references to the object (if defined)
     |  
     |  ----------------------------------------------------------------------
     |  Data and other attributes defined here:
     |  
     |  admission = 0
     |  
     |  name = ''

FUNCTIONS
    product(a, b)
        This function multiplies two given integers, a and b
        :param x: integer
        :param y: integer
        :returns: integer

FILE
    c:\users\admin\myfile.py

اجازه دهید اسناد راهنما را بررسی کنیم product تابع:

>>> help('myfile.product')

خروجی:

Help روی function product in `myfile`:

myfile.product = product(a, b)
    This function multiplies two given integers, a and b
    :param x: integer
    :param y: integer
    :returns: integer

اکنون، اجازه دهید به مستندات راهنما دسترسی پیدا کنیم Student کلاس:

>>> help('myfile.Student')

خروجی:

Help روی class Student in `myfile`:

myfile.Student = class Student(builtins.object)
 |  Student class in Python. It will store student details
 |  
 |  Methods defined here:
 |  
 |  __init__(self, adm, n)
 |      A constructor of the student object
 |      :param adm: a positive integer,
 |      :param n: a string
 |  
 |  ----------------------------------------------------------------------
 |  Data descriptors defined here:
 |  
 |  __dict__
 |      dictionary for instance variables (if defined)
 |  
 |  __weakref__
 |      list of weak references to the object (if defined)
 |  
 |  ----------------------------------------------------------------------
 |  Data and other attributes defined here:
 |  
 |  admission = 0
 |  
 |  name = ''
 

در خروجی، می توانیم مستنداتی را که برای آن نوشته ایم، ببینیم Student کلاس

help() روی help()?

چه اتفاقی می افتد که شما عبور کنید help() به عنوان یک استدلال برای help()?

>>> help(help())

Welcome to Python 2.7!  This is the online help utility.

If this is your first time using Python, you should definitely check out
the tutorial روی the Internet at http://docs.python.org/2.7/tutorial/.

Enter the name of any module, keyword, or topic to get help روی writing
Python programs and using Python modules.  To quit this help utility and
return to the interpreter, just type "quit".

To get a list of available modules, keywords, or topics, type "modules",
"keywords", or "topics".  Each module also comes with a one-line summary
of what it does; to list the modules whose summaries contain a given word
such as "spam", type "modules spam".

help> 

این ابزار به شما امکان می دهد از نوشتن خودداری کنید help() بارها و بارها، و اگر اغلب از این روش استفاده می کنید، می توانید کلمات کلیدی، نام ماژول ها و غیره را مستقیماً در CLI وارد کنید. ابزاری را می چرخاند که به همان روشی که استفاده از معمولی است عمل می کند help() اما باعث می شود process کوتاه تر:

help> modules keyword

Here is a list of matching modules.  Enter any module name to get more help.

keyword - Keywords (from "graminit.c")

در اینجا، ما ماژول های موجود را بر اساس جستجو کرده ایم روی آ keyword در خلاصه آنها وجود دارد. به اندازه کافی جالب – graminit.c حاوی کلمه کلیدی است keyword در خلاصه آن

برای خروج از ابزار، فقط تایپ کنید quit:

help> quit

You are now leaving help and returning to the Python interpreter.
If you want to ask for help روی a particular object directly from the
interpreter, you can type "help(object)".  Executing "help('string')"
has the same effect as typing a particular string at the help> prompt.

نتیجه

پایتون دارای یک سیستم داخلی است که می توانیم از آن در مورد ماژول ها، کلاس ها، توابع و کلمات کلیدی کمک بگیریم. این ابزار کمکی با استفاده از Python قابل دسترسی است help() عملکرد در REPL.

وقتی این تابع را فراخوانی می کنیم و یک شی را به آن ارسال می کنیم، کمک را برمی گرداند page یا اسناد مربوط به شی. وقتی تابع را بدون آرگومان اجرا می‌کنیم، ابزار کمکی باز می‌شود که در آن می‌توانیم در مورد اشیا به روشی تعاملی راهنمایی دریافت کنیم. در نهایت، برای دریافت کمک در مورد کلاس‌ها و توابع سفارشی‌مان، می‌توانیم رشته‌های مستند را تعریف کنیم.