This repo contains the Emacs package tox-pyvenv. This package provides a function that shows the list of Python virtualenvs managed by tox and allows you to select and activate one of them.

Background

Emacs package pyvenv provides function pyvenv-activate that activates a Python virtualenv in Emacs. Once it is active, the Emacs Python development environment has access to all the libraries and tools available in that virtualenv and things like autocompletion work.

I prefer to use tox to manage the virtualenvs of a project and tox always creates these virtualenvs in the same subdirectory of the project root, viz. .tox. This means that everytime I want to activate such a virtualenv, I have to browse to the .tox directory and select the correct virtualenv. This is where this package comes in: its function tox-pyvenv-activate lists the virtualenvs in the .tox folder so you only have to select the one you want to activate.

Prerequisites

To do its work, it requires two other packages, the aforementioned pyvenv to activate virtualenvs and projectile to determine the root directory of the project.

This package has been developed using Emacs 26.3 on CentOS 7.

Installation when using Spacemacs

I use the Emacs configuration framework Spacemacs - its develop branch to be precise - so I provide the installation instructions for that context. It should be relatively straightforward to adapt these instructions for “plain Emacs”.

Spacemacs will automatically retrieve the package from its GitHub repo if you add an entry such as the following to the list of “additional packages” in ~/.spacemacs:

dotspacemacs-additional-packages
`(
  (tox-pyvenv :location (recipe :fetcher github :repo "swinkels/tox-pyvenv"))
  )

At this point the package will be available to Spacemacs but will not yet be loaded. The following use-package expression for dotspacemacs/user-config in ~/.spacemacs takes care of that:

(use-package tox-pyvenv
  :commands (tox-pyvenv-activate)
  :init
    (spacemacs/set-leader-keys-for-major-mode 'python-mode "vt" 'tox-pyvenv-activate))

This expression establishes two things:

• tox-pyvenv will be loaded when you call tox-pyvenv-activate for the first time;
• function tox-pyvenv-activate is bound to SPC v t in Python mode.

Development

tox-pyvenv is developed using Cask, “a project management tool for Emacs Lisp to automate the package development cycle”. For information about the installation Cask I refer to its website. In this README I only show how to use Cask for the development of tox-pyvenv.

In the directory of your clone of pyvenv, execute the following command to download its development dependencies:

$> cask init --dev

This command downloads the development dependencies to subdirectory .cask/.

There is a Makefile in the root of the repo that offers several targets as shortcuts to these Cask commands. For example, the command to download the development dependencies is also available as target init of the Makefile:

$> make init

If you add unit tests to tox-pyvenv, you should place them in subdirectory test/. To run them, execute the following command:

$> cask exec ert-runner

This command is accessible as target unit-test of the Makefile. This rule is the default rule, so just calling make runs the unit tests.

Cask is also used to generate file tox-pyvenv-pkg.el from the main tox-pyvenv file tox-pyvenv.el. To do so, execute

$> cask pkg-file

You will have to do this if you upgrade the tox-pyvenv version number.