وظيفة المساعدة في بايثون

يُستخدم الدالة help() في Python للحصول على توثيق الوحدة النمطية أو الفئة أو الدالة أو المتغير المحدد. يُستخدم هذا الأسلوب عادةً مع وحدة تفسير Python للحصول على تفاصيل حول كائنات Python.

دالة مساعدة Python help()

نحن نجد أن تركيبة دالة مساعدة Python help() هي:

help([object])

إذا لم يتم تحديد أي argument، يُشغّل نظام المساعدة التفاعلي على وحدة تفسير Python. في وحدة تفسير Python، يمكننا تحديد أسماء الوحدة، الفئة، الدالة للحصول على توثيقها. وفيما يلي بعضها:

help> True

help> collections

help> builtins

help> modules

help> keywords

help> symbols

help> topics

help> LOOPING

إذا كنت تريد الخروج من وحدة المساعدة، اكتب quit. يمكننا أيضًا الحصول على توثيق المساعدة مباشرةً من وحدة التفسير Python عن طريق تمرير معلمة إلى دالة help().

>>> help('collections')

>>> help(print)

>>> help(globals)

لنرى ما هو الإخراج المتوقع لدالة المساعدة help() لدالة globals().

>>> help('builtins.globals')

Help on built-in function globals in builtins:

builtins.globals = globals()
    Return the dictionary containing the current scope's global variables.
    
    NOTE: Updates to this dictionary *will* affect name lookups in the current global scope and vice-versa.

تعريف دالة help() للفئات والدوال المخصصة

يمكننا تعريف إخراج دالة help() لفئاتنا ودوالنا المخصصة عن طريق تعريف سلسلة الوثائق (docstring). بشكل افتراضي، تُستخدم السلسلة التعليقية الأولى في جسم الطريقة كسلسلة وثائقها. إنها تحيط بها ثلاثة علامات اقتباس مزدوجة. لنفترض أن لدينا ملف python_help_examples.py يحتوي على الكود التالي.

def add(x, y):
    """
    This function adds the given integer arguments
    :param x: integer
    :param y: integer
    :return: integer
    """
    return x + y


class Employee:
    """
    Employee class, mapped to "employee" table in Database
    """
    id = 0
    name = ''

    def __init__(self, i, n):
        """
        Employee object constructor
        :param i: integer, must be positive
        :param n: string
        """
        self.id = i
        self.name = n

لاحظ أننا قمنا بتعريف سلسلة وثائق للدالة والفئة وأساليبها. يجب عليك اتباع بعض التنسيق للوثائق، لقد أنشأت بعض أجزاء منها تلقائيًا باستخدام بيئة تطوير PyCharm. دليل سلسلة وثائق NumPy هو مكان جيد للحصول على بعض الأفكار حول الطريقة الصحيحة لوثائق المساعدة. لنرى كيفية الحصول على هذه السلسلة كوثائق مساعدة في وحدة التحكم بالبايثون. أولاً وقبل كل شيء، سنقوم بتنفيذ هذا السكربت في وحدة التحكم لتحميل تعريفاتنا للدوال والفئات. يمكننا القيام بذلك باستخدام الأمر exec().

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

يمكننا التحقق من وجود تعريفات الدوال والفئات باستخدام الأمر globals().

>>> globals()
{'__name__': '__main__', '__doc__': None, '__package__': None, '__loader__': <class '_frozen_importlib.BuiltinImporter'>, '__spec__': None, '__annotations__': {}, '__builtins__': <module 'builtins' (built-in)>, '__warningregistry__': {'version': 0}, 'add': <function add at 0x100dda1e0>, 'Employee': <class '__main__.Employee'>}

لاحظ أن “Employee” و “add” موجودان في قاموس النطاق العالمي. الآن يمكننا الحصول على وثائق المساعدة باستخدام دالة help(). دعونا نلقي نظرة على بعض الأمثلة.

>>> help('python_help_examples')

>>> help('python_help_examples.add')

Help on function add in python_help_examples:

python_help_examples.add = add(x, y)
    This function adds the given integer arguments
    :param x: integer
    :param y: integer
    :return: integer
(END)

>>> help('python_help_examples.Employee')

>>> help('python_help_examples.Employee.__init__')


Help on function __init__ in python_help_examples.Employee:

python_help_examples.Employee.__init__ = __init__(self, i, n)
    Employee object constructor
    :param i: integer, must be positive
    :param n: string
(END)

ملخص

وظيفة المساعدة في Python مفيدة جدًا للحصول على تفاصيل حول الوحدات النمطية والفئات والوظائف. دائمًا ما يكون من الممارسات الجيدة تعريف سلسلة وثائقية للفئات والوظائف المخصصة لشرح استخدامها.

يمكنك التحقق من النص البرمجي الكامل في Python والمزيد من الأمثلة في Python من مستودعنا على GitHub.

المرجع: التوثيق الرسمي