La fonction d’aide Python

La fonction help() de Python est utilisée pour obtenir la documentation du module, de la classe, de la fonction, des variables, etc. spécifiés. Cette méthode est généralement utilisée avec la console d’interpréteur Python pour obtenir des détails sur les objets Python.

La fonction help() de Python

La syntaxe de la fonction help() de Python est:

help([object])

Si aucun argument n’est donné, le système d’aide interactif démarre sur la console de l’interpréteur. Dans la console d’aide Python, nous pouvons spécifier les noms de module, classe, fonction pour obtenir leur documentation d’aide. Certains d’entre eux sont:

help> True

help> collections

help> builtins

help> modules

help> keywords

help> symbols

help> topics

help> LOOPING

Si vous voulez sortir de la console d’aide, tapez quit. Nous pouvons également obtenir la documentation d’aide directement depuis la console Python en passant un paramètre à la fonction help().

>>> help('collections')

>>> help(print)

>>> help(globals)

Voyons quelle est la sortie de la fonction help() pour la fonction 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.

Définition de help() pour les classes et fonctions personnalisées

Nous pouvons définir la sortie de la fonction help() pour nos classes et fonctions personnalisées en définissant une docstring (chaîne de documentation). Par défaut, la première chaîne de commentaire dans le corps d’une méthode est utilisée comme docstring. Elle est entourée de trois guillemets doubles. Disons que nous avons un fichier Python python_help_examples.py avec le code suivant.

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

Remarquez que nous avons défini une docstring pour la fonction, la classe et ses méthodes. Vous devez suivre un certain format pour la documentation, j’ai généré une partie d’entre elles automatiquement en utilisant l’IDE PyCharm. Le guide de docstring de NumPy est un bon endroit pour avoir une idée de la manière correcte de documenter l’aide. Voyons comment obtenir cette docstring comme documentation d’aide dans la console Python. Tout d’abord, nous devrons exécuter ce script dans la console pour charger notre fonction et la définition de classe. Nous pouvons le faire en utilisant la commande exec().

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

Nous pouvons vérifier que les fonctions et les définitions de classe sont présentes en utilisant la commande 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'>}

Remarquez que « Employee » et « add » sont présents dans le dictionnaire de portée globale. Maintenant, nous pouvons obtenir la documentation d’aide en utilisant la fonction help(). Regardons quelques exemples.

>>> 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)

Résumé

La fonction help() de Python est très utile pour obtenir des détails sur les modules, les classes et les fonctions. Il est toujours recommandé de définir une docstring pour les classes et fonctions personnalisées afin d’expliquer leur utilisation.

Vous pouvez consulter le script Python complet et d’autres exemples de Python depuis notre Dépôt GitHub.

Référence: Documentation officielle