.. _plugins: ========================== 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 :ref:`plugins-pre_activate` y :ref:`plugins-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 :ref:`plugins-initialize` para agregar nuevos comandos y ganchos a virtualenvwrapper. Los ganchos :ref:`plugins-pre_mkvirtualenv` y :ref:`plugins-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 :ref:`scripts`). Las extensiones también pueden ser implementadas en Python usando *puntos de entrada* con Distribute_ , Definir una extensión ===================== .. note:: Virtualenvwrapper es distribuido con un plugin para la creación y ejecución de los scripts de personalización de los usuarios (:ref:`extensions-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__) .. note:: 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 :ref:`plugins-extension-points`). 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 .. _plugins-user-env: 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" """ .. warning:: 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. .. warning:: 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 :ref:`plugins-extension-points`). 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). .. seealso:: * `namespace packages `__ * `Extensible Applications and Frameworks `__ 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] [] 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)) # ... .. seealso:: * `Standard library documentation for logging `__ * `PyMOTW for logging `__ .. _plugins-extension-points: 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)_[_source]``. ** 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 :ref:`plugins-user-env`). .. _plugins-initialize: 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. .. _plugins-pre_mkvirtualenv: 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. .. _plugins-post_mkvirtualenv: 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. .. _plugins-pre_activate: 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. .. _plugins-post_activate: post_activate ------------- Los ganchos ``virtualenvwrapper.post_activate`` son ejecutados justo después de que un entorno sea activado. ``$VIRTUAL_ENV`` apunta al entorno actual. .. _plugins-pre_deactivate: pre_deactivate -------------- Los ganchos ``virtualenvwrapper.pre_deactivate`` son ejecutados justo antes de que un entorno sea desactivado. ``$VIRTUAL_ENV`` apunta al entorno actual. .. _plugins-post_deactivate: 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. .. _plugins-pre_rmvirtualenv: 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. .. _plugins-post_rmvirtualenv: 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. .. _Distribute: http://packages.python.org/distribute/ .. _project: http://www.doughellmann.com/projects/virtualenvwrapper.project/