Extender Virtualenvwrapper¶
Una gran experiencia con soluciones caseras para personalizar un entorno de desarrollo ha demostrado cuán valioso puede ser tener la capacidad de automatizar tareas comunes y eliminar molestias persistentes. Carpinteros construyen plantillas de guía, desarrolladores de software escriben scripts de shell. virtualenvwrapper continúa la tradición de animar a un artesano a modificar sus herramientas para trabajar de la manera que ellos quieran, en vez de al revés.
Usa los ganchos provistos para eliminar operaciones manuales repetitivas y hacer más simple tu flujo de desarrollo. Por ejemplo, configura los ganchos pre_activate y post_activate para provocar que un IDE cargue un proyecto o recargue los archivos desde la última sesión de edición, administra el logueo de horas, o inicia y detiene versiones de desarrollo de un servidor de aplicaciones. Usa el gancho initialize para agregar nuevos comandos y ganchos a virtualenvwrapper. Los ganchos pre_mkvirtualenv y post_mkvirtualenv te brindan la oportunidad de instalar requerimientos básicos dentro de cada nuevo entorno de desarrollo, inicializar el repositorio de control de versiones para el código, o por otro lado configurar un nuevo proyecto.
Existen dos maneras para adjuntar tu código para que virtualenvwrapper lo ejecute: los usuarios finales pueden usar scripts de shell o otros programas para la personalización personal (ver Personalizaciones por usuario). Las extensiones también pueden ser implementadas en Python usando puntos de entrada con Distribute ,
Definir una extensión¶
Nota
Virtualenvwrapper es distribuido con un plugin para la creación y ejecución de los scripts de personalización de los usuarios (user_scripts). Los ejemplos siguientes han sido tomados de la implementación de ese plugin.
Organización del código¶
El paquete Python para virtualenvwrapper es un namespace package. Eso significa que múltiples librerías pueden instalar código dentro del paquete, incluso si ellas no son distribuidas juntas o instaladas dentro del mismo directorio. Las extensiones pueden (opcionalmente) usar el namespace de virtualenvwrapper configurando su estructura de directorios así:
- virtualenvwrapper/
- __init__.py
- user_scripts.py
Y agregando el siguiente código dentro de __init__.py:
"""virtualenvwrapper module
"""
__import__('pkg_resources').declare_namespace(__name__)
Nota
Las extensiones pueden ser cargadas desde cualquier paquete, así que usar el espacio de nombres de virtualenvwrapper no es requerido.
Extensión API¶
Después de que el paquete está establecido, el siguiente paso es crear un módulo para alojar el código de la extensión. Por ejemplo, virtualenvwrapper/user_scripts.py. El módulo debe contener la extensión actual a los entry points. Soporte de código puede ser incluido, o importado desde algún lugar usando la técnica de organización de código estándar de Python.
FIXME: I don’t like the last paragraph
La API es la misma para todos los puntos de extensión. Cada uno usa una función de Python que toma un sólo argumento, una lista de strings pasada al script que carga los ganchos en la línea de comandos.
def function_name(args):
# args is a list of strings passed to the hook loader
El contenido de la lista de argumentos está definida para cada punto de extensión a continuación (ver Puntos de extensión).
Invocación de la extensión¶
Acción directa¶
Los plugins pueden ser colgados a cada uno de los ganchos de dos formas diferentes. La estándar es tener una función y hacer algún trabajo directamente. Por ejemplo, la función initialize() para el plugin de los scripts de usuarios crea scripts de usuarios por default cuando virtualenvwrapper.sh es cargada.
def initialize(args):
for filename, comment in GLOBAL_HOOKS:
make_hook(os.path.join('$WORKON_HOME', filename), comment)
return
Modificar el entorno de usuario¶
Hay casos en dónde la extensión necesita actualizar el entorno del usuario (por ejemplo, cambiar el directorio de trabajo actual o configurar variables de entorno). Las modificaciones al entorno del usuario deben ser hechas dentro del shell actual del usuario, y no pueden ser ejecutadas en un proceso separado. Para tener código ejecutado en un proceso shell del usuario, las extensiones pueden definir funciones gancho y retornar el texto de los comandos de shell a ser ejecutados. Estos ganchos fuente son ejecutados después de los ganchos comunes con el mismo nombre, y no deben hacer ningún trabajo por ellos mismos.
El gancho initialize_source() para el plugin de scripts de usuarios busca un script initializa global y causa que este sea ejecutado en el proceso de shell actual.
def initialize_source(args):
return """
#
# Run user-provided scripts
#
[ -f "$WORKON_HOME/initialize" ] && source "$WORKON_HOME/initialize"
"""
Advertencia
Como las extensiones están modificando el shell de trabajo del usuario, se debe tener mucho cuidado de corromper el entorno sobreescribiendo variables con valores inesperados. Evita crear variables temporales cuando sea posible. Poner prefijos a las variables con el nombre de la extensión es una buena forma de manejar espacios de nombres. Por ejemplo, en vez de temp_file usa user_scripts_temp_file. Usa unset para liberar nombres de variables temporales cuando no sean más necesarias.
Advertencia
virtualenvwrapper funciona en varios shells con una sintaxis ligeramente diferente (bash, sh, zsh, ksh). Ten en cuenta esta portabilidad cuando definas ganchos incluidos (sourced hooks). Mantener la sintaxis lo más simple posible evitará problemas comunes, pero quizás haya casos donde examinar la variable de entorno SHELL y generar diferente sintaxis para cada caso sea la única manera de alcanzar el resultado deseado.
Registrar puntos de entrada¶
Las funciones definidas en el plugin necesitan ser registradas como puntos de entrada para que el cargador de ganchos de virtualenvwrapper los encuentre. Los puntos de entrada de Distribute se configuran en el setup.py de tu paquete coincidiendo el nombre del punto de entrada con la función en el paquete que lo implementa.
Una copia parcial del setup.py de virtualenvwrapper ilustra cómo los puntos de entrada initialize() y initialize_source() son configurados.
# Bootstrap installation of Distribute
import distribute_setup
distribute_setup.use_setuptools()
from setuptools import setup
setup(
name = 'virtualenvwrapper',
version = '2.0',
description = 'Enhancements to virtualenv',
# ... details omitted ...
namespace_packages = [ 'virtualenvwrapper' ],
entry_points = {
'virtualenvwrapper.initialize': [
'user_scripts = virtualenvwrapper.user_scripts:initialize',
],
'virtualenvwrapper.initialize_source': [
'user_scripts = virtualenvwrapper.user_scripts:initialize_source',
],
# ... details omitted ...
},
)
El argumento entry_points de setup() es un diccionario que mapea los grupos de nombre de puntos de entrada a listas de puntos de entrada específicos. Un nombre de grupo diferente es definido por virtualenvwrapper por cada punto de extensión (ver Puntos de extensión).
Los identificadores de puntos de entrada son strings con la sintaxis name = package.module:function. Por convención, el nombre de cada punto de entrada es el nombre del plugin, pero esto no es requerido (los nombres no son usados).
El cargador de ganchos¶
Las extensiones son ejecutadas mediante una aplicación de líneas de comando implementada en virtualenvwrapper.hook_loader. Como virtualenvwrapper.sh es invocado primero y los usuarios generalmente no necesitan ejecutar la aplicación directamente, ningún otro script es instalado por separado. En vez, para ejecutar la aplicación, usa la opción -m del intérprete:
$ python -m virtualenvwrapper.hook_loader -h
Usage: virtualenvwrapper.hook_loader [options] <hook> [<arguments>]
Manage hooks for virtualenvwrapper
Options:
-h, --help show this help message and exit
-s, --source Print the shell commands to be run in the current
shell
-l, --list Print a list of the plugins available for the given
hook
-v, --verbose Show more information on the console
-q, --quiet Show less information on the console
-n NAMES, --name=NAMES
Only run the hook from the named plugin
Para ejecutar las extensiones para el gancho initialize:
$ python -m virtualenvwrapper.hook_loader -v initialize
Para obtener los comandos de shell para el gancho initialize:
$ python -m virtualenvwrapper.hook_loader --source initialize
En la práctica, en vez de invocar al cargador de ganchos directamente es conveniente usar la función de shell, virtualenvwrapper_run_hook para ejecutar los ganchos en ambos modos.:
$ virtualenvwrapper_run_hook initialize
Todos los argumentos pasados a la función de shell son pasados directamente al cargador de ganchos.
Registro (Logging)¶
El cargador de ganchos configura el registro para que los mensajes sean escritos en $WORKON_HOME/hook.log. Los mensajes quizás sean escritos en stderr, dependiendo de la flash verbose. Por default los mensajes con un nivel mayor o igual a info se escriben en stderr, y los de nivel debug o mayor van al archivo de registro. Usar el registro de esta forma provee un mecanismo conveniente para que los usuarios controlen la verbosidad de las extensiones.
Para usar el registro en tu extensión, simplemente instancia un registro y llama a sus métodos info(), debug() y otros métodos de mensajería.
import logging
log = logging.getLogger(__name__)
def pre_mkvirtualenv(args):
log.debug('pre_mkvirtualenv %s', str(args))
# ...
Puntos de extensión¶
Los nombres de los puntos de extensión para los plugins nativos siguen una convención con varias partes: virtualenvwrapper.(pre|post)_<event>[_source]. <event> es la acción tomada por el usuario o virtualenvwrapper que provoca la extensión. (pre|post) indica si llama a la extensión antes o después de un evento. El sufijo _source es agregado para las extensiones que retornan código shell en vez de tomar una acción directamente (ver Modificar el entorno de usuario).
get_env_details¶
Los ganchos virtualenvwrapper.get_env_details son ejecutados cuando workon es ejecutado sin argumentos y una lista de entornos virtuales es impresa en pantalla. El gancho es ejecutado una vez para cada entorno, luego de que el nombre sea impreso, y puede ser utilizado para mostrar información adicional sobre ese entorno.
get_env_details¶
The virtualenvwrapper.get_env_details hooks are run when workon is run with no arguments and a list of the virtual environments is printed. The hook is run once for each environment, after the name is printed, and can be used to show additional information about that environment.
initialize¶
Los ganchos virtualenvwrapper.initialize son ejecutados cada vez que virtualenvwrapper.sh es cargado en el entorno del usuario. El gancho initialize puede ser usado para instalar plantillas para configurar archivos o preparar el sistema para una operación correcta del plugin.
pre_mkvirtualenv¶
Los ganchos virtualenvwrapper.pre_mkvirtualenv son ejecutados después de que el entorno es creado, pero antes de que el nuevo entorno sea activado. El directorio de trabajo actual para cuando el gancho es ejecutado es $WORKON_HOME y el nombre del nuevo entorno es pasado como un argumento.
post_mkvirtualenv¶
Los ganchos virtualenvwrapper.post_mkvirtualenv son ejecutado después de que un nuevo entorno sea creado y activado. $VIRTUAL_ENV es configurado para apuntar al nuevo entorno.
pre_activate¶
Los ganchos virtualenvwrapper.pre_activate son ejecutados justo antes de que un entorno sea activado. El nombre del entorno es pasado como primer argumento.
post_activate¶
Los ganchos virtualenvwrapper.post_activate son ejecutados justo después de que un entorno sea activado. $VIRTUAL_ENV apunta al entorno actual.
pre_deactivate¶
Los ganchos virtualenvwrapper.pre_deactivate son ejecutados justo antes de que un entorno sea desactivado. $VIRTUAL_ENV apunta al entorno actual.
post_deactivate¶
Los ganchos virtualenvwrapper.post_deactivate son ejecutados justo después de que un entorno sea desactivado. El nombre del entorno recién desactivado es pasado como primer argumento.
pre_rmvirtualenv¶
Los ganchos virtualenvwrapper.pre_rmvirtualenv son ejecutados justo antes de que un entorno sea eliminado. El nombre del entorno eliminado es pasado como primer argumento.
post_rmvirtualenv¶
Los ganchos virtualenvwrapper.post_rmvirtualenv son ejecutados justo después de que un entorno haya sido eliminado. El nombre del entorno eliminado es pasado como primer argumento.
Agregar nuevos puntos de extensión¶
Los plugins que definen nuevas operaciones pueden también definir nuevos puntos de extensión. No es necesario hacer ninguna configuración para permitir que el cargador de ganchos encuentre las extensiones; documentar los nombres y agregar llamadas a virtualenvwrapper_run_hook es suficiente para causar que ellos se invoquen.
El cargador de ganchos asume que todos los nombres de puntos de extensión comienzan con virtualenvwrapper. y los nuevos plugins querrán usar su propio espacio de nombres para agregar. Por ejemplo, la extensión project define nuevos eventos para crear directorios del proyecto (pre y post). Esas son llamadas a virtualenvwrapper.project.pre_mkproject y virtualenvwrapper.project.post_mkproject. Estas son invocadas con:
virtualenvwrapper_run_hook project.pre_mkproject $project_name
y:
virtualenvwrapper_run_hook project.post_mkproject
respectivamente.