El sistema de ayuda de Python

Al escribir y ejecutar sus programas de Python, es posible que se quede atascado y necesite ayuda. Es posible que necesite saber el significado de ciertos módulos, clases, funciones,...

Al escribir y ejecutar sus programas de Python, es posible que se quede atascado y necesite ayuda. Es posible que necesite saber el significado de ciertos módulos, clases, funciones, palabras clave, etc. La buena noticia es que Python viene con un sistema de ayuda incorporado. Esto significa que no tienes que buscar ayuda fuera de Python.

En este artículo, aprenderá a utilizar el sistema de ayuda integrado de Python.

Función de ayuda de Python() {#función de ayuda de Python}

Esta función nos ayuda a obtener la documentación de una determinada clase, función, variable, módulo, etc. La función debe usarse en la consola de Python para obtener detalles de varios objetos de Python.

Pasar un objeto a la función de ayuda() {#pasar un objeto a la función de ayuda}

La función help() de Python tiene la siguiente sintaxis:

1
>>> help(object)

En la sintaxis anterior, el parámetro objeto es el nombre del objeto sobre el que necesita ayuda.

Por ejemplo, para saber más sobre la función imprimir de Python, escriba el siguiente comando en la consola de Python:

1
>>> help(print)

Producción:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
Help on 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.

Para obtener ayuda para la clase dict, escriba lo siguiente en la consola de Python:

1
>>> help(dict)

Producción:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
Help on 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.
 |  

...

También puede pasar un objeto de lista real a la función ayuda():

1
>>> help(['a', 'b', 'c'])

Producción:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
Help on 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).

...

Podemos ver que cuando pasa un objeto a la función help(), se imprime su documentación o página de ayuda. En la siguiente sección, aprenderá a pasar argumentos de cadena a la función help().

Pasar un argumento de cadena para ayudar() {#pasar un argumento de cadena para ayudar}

Si pasa una cadena como argumento, la cadena se tratará como el nombre de una función, módulo, palabra clave, método, clase o tema de documentación y se imprimirá la página de ayuda correspondiente. Para marcarlo como un argumento de cadena, enciérrelo entre comillas simples o dobles.

Por ejemplo:

1
>>> help('print')

Producción:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
Help on 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.

Aunque pasamos 'print' como un argumento de cadena, todavía tenemos la documentación para la función print de Python. Aquí hay otro ejemplo:

1
>>> help('def')

Producción:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
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

...

Aquí pasamos "def" como un argumento de cadena a la función help() y devolvió la documentación para definir funciones.

Si no se encuentra ningún objeto, método, función, clase o módulo que coincida, se le notificará. Por ejemplo:

1
>>> help('qwerty')

Producción:

1
2
3
No Python documentation found for 'qwerty'.
Use help() to get the interactive help utility.
Use help(str) for help on the str class.

Se nos notifica que no se encontró documentación para nuestra cadena.

A veces, es posible que necesitemos obtener ayuda sobre una determinada función que está definida en una determinada biblioteca de Python. Esto requiere que primero importemos la biblioteca. Un buen ejemplo es cuando necesitamos obtener la documentación para la función log definida en la biblioteca math de Python. En este caso, primero debemos importar la biblioteca math y luego llamamos a la función help() como se muestra a continuación:

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

Producción:

1
2
3
4
5
6
7
Help on built-in function log in module math:

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

Uso de help() sin argumento

La función help() se puede utilizar sin argumentos. Si ejecuta la función sin un argumento, la utilidad de ayuda interactiva de Python se iniciará en la consola del intérprete. Solo tienes que escribir el siguiente comando en la consola de Python:

1
>>> help()

Esto devolverá la utilidad de ayuda de Python en la que puede escribir el nombre del objeto sobre el que necesita obtener ayuda. Por ejemplo:

1
help> print

Producción:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
Help on 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.

Para volver al mensaje anterior, simplemente presione "q".

Aquí hay otro ejemplo:

1
help> return

Producción:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
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

Para salir de la utilidad de ayuda y volver a la consola de Python, simplemente escriba "salir" y presione la tecla Intro:

1
help> quit

Producción:

1
2
3
4
5
You are now leaving help and returning to the Python interpreter.
If you want to ask for help on 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.
>>>

En la siguiente sección, discutiremos cómo definir help() para nuestros objetos personalizados.

Definición de documentos de ayuda para funciones y clases personalizadas {#definición de documentos de ayuda para funciones y clases personalizadas}

Es posible para nosotros definir la salida de la función help() para nuestras funciones y clases personalizadas definiendo una cadena de documentación (cadena de documento). En Python, la primera cadena de comentario agregada al cuerpo de un método se trata como su cadena de documentación. El comentario debe estar rodeado de tres comillas dobles. Por ejemplo:

1
2
3
4
5
6
7
8
def product(a, b):
    """
    This function multiplies two given integers, a and b
    :param x: integer
    :param y: integer
    :returns: integer
    """
    return a * b

En el ejemplo anterior, hemos definido una función llamada producto. Esta función multiplica dos valores enteros, a y b que se le pasan como argumentos/parámetros. Ver el comentario encerrado entre tres comillas dobles:

1
2
3
4
5
6
    """
    This function multiplies two given integers, a and b
    :param x: integer
    :param y: integer
    :returns: integer
    """

Esto se tratará como la cadena de documentación para la función producto.

Ahora, cree un nuevo archivo y asígnele el nombre "myfile.py". Agregue el siguiente código al archivo:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
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

En el ejemplo anterior, se ha definido una cadena de documentos para una función, una clase y métodos.

Ahora debemos demostrar cómo podemos obtener la cadena de documentación anterior como documentación de ayuda en nuestra consola de Python.

Primero, necesitamos ejecutar el script en la consola para cargar tanto la función como la definición de clase en el entorno de Python. Podemos usar el método exec() de Python para esto. Ejecute el siguiente comando en la consola de Python:

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

Alternativamente, si ha escrito el código dentro de Python IDLE, simplemente tiene que ejecutarlo.

Ahora podemos confirmar si los módulos de función y clase han sido detectados ejecutando el comando globals() en la consola de Python:

1
>>> globals()

En mi caso, obtengo el siguiente resultado:

1
{'__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>}

Como se muestra en el resultado anterior, tanto Student como product están en el diccionario de alcance global. Ahora podemos usar la función ayuda() para obtener ayuda para la clase Estudiante y la función producto. Simplemente ejecute el siguiente comando en la consola de Python:

1
>>> help('myfile')

Producción:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
Help on 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

Revisemos la documentación de ayuda para la función producto:

1
>>> help('myfile.product')

Producción:

1
2
3
4
5
6
7
Help on 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

Ahora, accedamos a la documentación de ayuda para la clase Student:

1
>>> help('myfile.Student')

Producción:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
Help on 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 = ''
 

En la salida, podemos ver la documentación que escribimos para la clase Student.

ayuda() en ayuda()?

¿Qué sucede cuando pasa help() como argumento a help()?

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
>>> 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 on the Internet at http://docs.python.org/2.7/tutorial/.

Enter the name of any module, keyword, or topic to get help on 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> 

Esta utilidad le permite evitar escribir help() una y otra vez, y simplemente puede ingresar las palabras clave, los nombres de los módulos, etc. directamente en la CLI, si usa el método con frecuencia. Activa una utilidad que funciona de la misma manera que usar help() normal, pero hace que el proceso sea más corto:

1
2
3
4
5
help> modules keyword

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

keyword - Keywords (from "graminit.c")

Aquí, hemos buscado los módulos disponibles, basados ​​en una palabra clave presente en sus resúmenes. Curiosamente, graminit.c contiene la palabra clave palabra clave en su resumen.

Para salir de la utilidad, simplemente escriba quit:

1
2
3
4
5
6
help> quit

You are now leaving help and returning to the Python interpreter.
If you want to ask for help on 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.

Conclusión

Python viene con un sistema incorporado desde el cual podemos obtener ayuda con respecto a módulos, clases, funciones y palabras clave. Se puede acceder a esta utilidad de ayuda mediante el uso de la función help() de Python en el REPL.

Cuando llamamos a esta función y le pasamos un objeto, devuelve la página de ayuda o la documentación del objeto. Cuando ejecutamos la función sin un argumento, se abre la utilidad de ayuda donde podemos obtener ayuda sobre los objetos de forma interactiva. Finalmente, para obtener ayuda con respecto a nuestras clases y funciones personalizadas, podemos definir docstrings.

Licensed under CC BY-NC-SA 4.0