Ayuda y documentación
en IPython
Si no lee ninguna otra sección de este capítulo, lea esta: Encuentro que las herramientas discutidas aquí son las contribuciones más transformadoras de IPython a mi flujo de trabajo diario.
Cuando se le pide a una persona con mentalidad tecnológica que ayude a un amigo, familiar o colega con un problema informático, la mayoría de las veces se trata menos de saber la respuesta correcta que de saber cómo encontrar rápidamente una respuesta desconocida. En la ciencia de datos es lo mismo: los recursos web de búsqueda, como la documentación en línea, los hilos de la lista de correo y las respuestas de StackOverflow, contienen una gran cantidad de información, incluso (¡especialmente!) si se trata de un tema en el que se ha encontrado buscando antes. Ser un practicante eficaz de la ciencia de datos se trata menos de memorizar la herramienta o comando que debe usar para cada situación posible, y más de aprender a encontrar de manera efectiva la información que no conoce, ya sea a través de un motor de búsqueda web u otro medio.
Una de las funciones más útiles de IPython / Jupyter es acortar la brecha entre el usuario y el tipo de documentación y búsqueda que le ayudará a realizar su trabajo de forma eficaz. Si bien las búsquedas en la web aún juegan un papel en la respuesta a preguntas complicadas, se puede encontrar una cantidad asombrosa de información solo a través de IPython. Algunos ejemplos de las preguntas que IPython puede ayudar a responder con unas pocas teclas:
- ¿Cómo llamo a esta función? ¿Qué argumentos y opciones tiene?
- ¿Cómo es el código fuente de este objeto Python?
- ¿Qué hay en este paquete que importé? ¿Qué atributos o métodos tiene este objeto?
Aquí discutiremos las herramientas de IPython para acceder rápidamente a esta información, a saber, el carácter ? para explorar la documentación, los caracteres ?? para explorar el código fuente y la tecla Tab para completado.
Accediendo a la documentación con ??¶
El lenguaje Python y su ecosistema de ciencia de datos se construyen pensando en el usuario, y una gran parte de eso es el acceso a la documentación. Cada objeto de Python contiene la referencia a una cadena, conocida como cadena de documentación, que en la mayoría de los casos contendrá un resumen conciso del objeto y cómo usarlo. Python tiene una función help() incorporada que puede acceder a esta información e imprime los resultados. Por ejemplo, para ver la documentación de la función incorporada len, puede hacer lo siguiente:
In [1]: help(len)
Help on built-in function len in module builtins:
len(...)
len(object) -> integer
Return the number of items of a sequence or mapping.
Dependiendo de su intérprete, esta información puede mostrarse como texto en línea o en alguna ventana emergente separada.
Debido a que encontrar ayuda en un objeto es tan común y útil, IPython presenta el carácter ? como una forma abreviada de acceder a esta documentación y otra información relevante:
In [2]: len?
Type: builtin_function_or_method
String form: <built-in function len>
Namespace: Python builtin
Docstring:
len(object) -> integer
Return the number of items of a sequence or mapping.
Esta notación funciona para casi cualquier cosa, incluidos los métodos de objeto:
In [3]: L = [1, 2, 3]
In [4]: L.insert?
Type: builtin_function_or_method
String form: <built-in method insert of list object at 0x1024b8ea8>
Docstring: L.insert(index, object) -- insert object before index
o incluso los propios objetos, con la documentación de su tipo:
In [5]: L?
Type: list
String form: [1, 2, 3]
Length: 3
Docstring:
list() -> new empty list
list(iterable) -> new list initialized from iterable's items
Es importante destacar que esto incluso funcionará para funciones u otros objetos que cree usted mismo. Aquí definiremos una pequeña función con una cadena de documentos:
In [6]: def square(a):
....: """Return the square of a."""
....: return a ** 2
....:
Tenga en cuenta que para crear una cadena de documentos para nuestra función, simplemente colocamos una cadena literal en la primera línea. Debido a que las cadenas de documentos suelen ser de varias líneas, por convención utilizamos la notación de comillas triples de Python para las cadenas de varias líneas.
Ahora usaremos la marca ? para encontrar esta cadena de documentos:
In [7]: square?
Type: function
String form: <function square at 0x103713cb0>
Definition: square(a)
Docstring: Return the square of a.
Este acceso rápido a la documentación a través de cadenas de documentos es una de las razones por las que debe acostumbrarse a agregar siempre dicha documentación en línea al código que escribe.
Acceder al código fuente con ??¶
Debido a que el lenguaje Python es tan fácil de leer, generalmente se puede obtener otro nivel de conocimiento leyendo el código fuente del objeto que le interesa. IPython proporciona un acceso directo al código fuente con el doble signo de interrogación (??):
In [8]: square??
Type: function
String form: <function square at 0x103713cb0>
Definition: square(a)
Source:
def square(a):
"Return the square of a"
return a ** 2
Para funciones simples como esta, el doble signo de interrogación puede brindar una visión rápida de los detalles subyacentes.
Si juega con esto, notará que a veces el sufijo ?? no muestra ningún código fuente: esto se debe generalmente a que el objeto en cuestión no está implementado en Python, sino en C o algún otro lenguaje de extensión compilado. Si este es el caso, el sufijo ?? da el mismo resultado que el sufijo ?. Encontrará esto particularmente con muchos de los objetos y tipos integrados de Python, por ejemplo, len de arriba:
In [9]: len??
Type: builtin_function_or_method
String form: <built-in function len>
Namespace: Python builtin
Docstring:
len(object) -> integer
Return the number of items of a sequence or mapping.
El uso de ? y/o ?? proporciona una interfaz potente y rápida para encontrar información sobre lo que hace cualquier función o módulo de Python.
Exploración de módulos con
finalización de tabulaciones¶
La otra interfaz útil de IPython es el uso de la tecla de tabulación para autocompletar y explorar el contenido de objetos, módulos y espacios de nombres. En los ejemplos que siguen, usaremos <TAB> para indicar cuándo se debe presionar la tecla Tab.
Completar tabulación del contenido del objeto¶
Cada objeto de Python tiene varios atributos y métodos asociados. Al igual que con la función help discutida anteriormente, Python tiene una función dir incorporada que devuelve una lista de estos, pero la interfaz de finalización de tabulación es mucho más fácil de usar en la práctica. Para ver una lista de todos los atributos disponibles de un objeto, puede escribir el nombre del objeto seguido de un punto (".") y la tecla Tab:
In [10]: L.<TAB>
L.append L.copy L.extend L.insert L.remove L.sort
L.clear L.count L.index L.pop L.reverse
Para reducir la lista, puede escribir el primer carácter o varios caracteres del nombre, y la tecla Tab encontrará los atributos y métodos coincidentes:
In [10]: L.c<TAB>
L.clear L.copy L.count
In [10]: L.co<TAB>
L.copy L.count
Si solo hay una opción, al presionar la tecla Tab se completará la línea. Por ejemplo, lo siguiente se reemplazará instantáneamente con L.count:
In [10]: L.cou<TAB>
Aunque Python no tiene una distinción estrictamente impuesta entre atributos públicos / externos y atributos privados / internos, por convención se usa un guión bajo anterior para denotar tales métodos. Para mayor claridad, estos métodos privados y métodos especiales se omiten de la lista de forma predeterminada, pero es posible enumerarlos escribiendo explícitamente el guión bajo:
In [10]: L._<TAB>
L.__add__ L.__gt__ L.__reduce__
L.__class__ L.__hash__ L.__reduce_ex__
En aras de la brevedad, solo mostramos las primeras dos líneas del resultado. La mayoría de estos son métodos especiales de doble subrayado de Python (a menudo denominados métodos "dunder").
Finalización de tabulación al importar¶
La finalización de tabulación también es útil al importar objetos de paquetes. Aquí lo usaremos para encontrar todas las posibles importaciones en el paquete itertools que comienzan con co:
In [10]: from itertools import co<TAB>
combinations compress
combinations_with_replacement countDel mismo modo, puede utilizar la función de tabulación para ver qué importaciones están disponibles en su sistema (esto cambiará según los scripts y módulos de terceros que estén visibles en su sesión de Python):
In [10]: import <TAB>
Display all 399 possibilities? (y or n)
Crypto dis py_compile
Cython distutils pyclbr
... ... ...
difflib pwd zmq
In [10]: import h<TAB>
hashlib hmac http
heapq html husl(Tenga en cuenta que, para abreviar, no imprimí aquí los 399 paquetes y módulos importables en mi sistema).
Más allá de la finalización de la pestaña:
coincidencia de comodines¶
La finalización de tabulación es útil si conoce los primeros caracteres del objeto o atributo que está buscando, pero es de poca ayuda si desea hacer coincidir los caracteres en el medio o al final de la palabra. Para este caso de uso, IPython proporciona un medio de coincidencia de comodines para los nombres que utilizan el carácter *.
Por ejemplo, podemos usar esto para listar todos los objetos en el espacio de nombres que terminan con Warning:
In [10]: *Warning?
BytesWarning RuntimeWarning
DeprecationWarning SyntaxWarning
FutureWarning UnicodeWarning
ImportWarning UserWarning
PendingDeprecationWarning Warning
ResourceWarning
Observe que el carácter * coincide con cualquier cadena, incluida la cadena vacía.
De manera similar, suponga que estamos buscando un método de cadena que contenga la palabra find en algún lugar de su nombre. Podemos buscarlo de esta manera:
In [10]: str.*find*?
str.find
str.rfind
Encuentro que este tipo de búsqueda flexible con comodines puede ser muy útil para encontrar un comando en particular al conocer un nuevo paquete o volver a familiarizarme con uno familiar.