This not an attempt to create another, or even better, set of wrapper functions for Virtualenv. This is a set of wrappers that I've built, like, and use everyday.
- Philosophy of Virtualenv
Just clone the repo. I use a ~/.virtualcandy directory to hold the code, but the location doesn't matter much.
cd; git clone git://github.com/jeffbuttars/virtualcandy.git .virtualcandy
To enable VirtualCandy, you just source it in your ~/.bashrc file. Add the following line into your ~/.bashrc file:
or add the following line to your ~/.zshrc, as appropriate:
That's it, VirtualCandy is installed!
Philosophy of Virtualenv
My usage of Virtualenv is very similar to how one uses Git or Hg.
I create one Virtualenv environment per project and that Virtualenv environment
is located at the top of the project's directory tree. I also name
all of my Virtualenv directories the same name,
.venv, and this project
uses that as the default Virtualenv directory name. But that is configurable.
Most VirtualCandy functions can be used from anywhere within a project using a Virtualenv. VirtualCandy will find the nearest install of Virtualenv by traversing up the directory tree until one or no Virtualenv are found.
Set the following environmental variables in your ~/.bashrc, before you source the virtualcandy.sh file, to configure VirtualCandy settings.
Available config variables
VC_DEFAULT_VENV_NAMEName of the Virtualenv directory, default is '.venv'
VC_DEFAULT_VENV_REQFILEName of the requirements file, default is 'requirements.txt'
VC_AUTO_ACTIVATIONEnable auto Virtualenv activation, default is true
VC_PYTHON_EXEPython executable to use for the Virtualenv, default is $(basename $(which python))
VC_VIRTUALENV_EXEVirtualenv command to use, default is virtualenv
Set the name of your Virtualenv directory created by and used by VirtualCandy
Set the name of the requirements file used by Pip freeze and VirtualCandy to store your installed package information
The auto activation (when set to 'true', it's off by default) of a Virtualenv when you enter its containing directory. If you use Virtualenv often, this is a very handy option. Example: If you have a directory named ~/Dev1 that has a Virtualenv in it. Then upon changing into the ~/Dev1 directory that Virtualenv will be activated. If you a Virtualenv activated and cd into a directory containing a Virtualenv that is different from the currently activated Virtualenv, then the current Virtualenv will be deactivated and the new one will be activated.
Start a new virtualenv, or build one from a requirements file. This
function only works on your current working directory(all other functions work
anywhere within a Virtualenv project). If you run
vcstart in a
directory without a Virtualenv of the name defined by
then a new Virtualenv will be created. After the Virtualenv is created, if a
requirements file is present, all of the packages listed in the
requirements file will be installed. If a Virtualenv defined by the name
$VC_DEFAULT_VENV_NAME already exists and a requirements file exists then no
new Virtualenv will be created, the packages listed in a present requirements file will be
installed/updated if necessary.
Any arguments given to the
vcstart command will be considered package names and
will be installed after the virtualenv is created. If package parameters are given
and there is an existing requirements.txt file, the requirements.txt file we be
updated to include the additional packages.
vcactivate will activate the Virtualenv of the current project.
the current project by using the
Install a package into the current Virtualenv and update the requirements file.
# install the latest versions of Django and djnagorestframework # and update the requirements file vcin Django djnagorestframework
A wrapper around
pip install. All arguments to
vcin are passed to
pip install is run
vcfreeze is run.
This will upgrade all of the packages listed in the requirements file to their latest version and then re-write the requirements file to reflect the update.
Create a Python package skeleton of the specified name. This includes some
boilerplate code for
Will create a folder structure:
<package-name> LICENSE.txt MANIFEST.in README.rst Makefile requirements.txt setup.py \ <package_name> (directory for package sources) __init__.py
setup.py will include boilerplate. Also the
includes default version variables:
__version__ = "0.1.0.dev1" __version_info__ = (0, 1, 0, 'dev1')
- TODO: Make the inotify watch optional with a command line flag
- TODO: Make the Virtualenv name option a command line flag
Runs ctags and creates a tags file in your current working directory. The
Virtualenv directory of the current project will be explicitly scanned by ctags
and included in the tags file. If no parameters are given to
vctags then the
current working directory will also be recursively added to the tags file. Any
parameters given to the
vctags command will be treated as files and/or
directories that should be scanned by ctags.
Write a new requirements file for the current Virtualenv. The
requirements file contents are the result of the
pip freeze command. The
requirements file is written in the same directory that contains the
Virtualenv directory, even if the command is ran in a subdirectory.
If you don't want to name the output file to be
requirements.txt, you can
change the name of the output file with the
Creates a package bundle containing all of the packages listed in the current Virtualenv's VC_DEFAULT_VENV_REQFILE file. The name of the bundle output will be 'VC_DEFAULT_VENV_NAME.pybundle', but with any leading '.' stripped from the Virtualenv name. For instance, if VC_DEFAULT_VENV_NAME is '.myenv' the bundle will be named 'myenv.pybundle'.
Recursively clean files matching a set of patterns.
Be careful using this. It's very convenient and very destructive
By default the file patterns
*.pyo will be matched by default and
without question. You can add additional patterns as parameters:
# Ex: clean out all files ending in .txt and .md vcclean '*.txt' '*.md' # Ex: clean out all tags files. vcclean tags
If additional patterns are given you will be prompted to confirm the use of the
vcclean is just a wrapper around:
find . -iname "<pattern>" | xargs rm -fv
Checks the current directory for a Virtualenv named VC_DEFAULT_VENV_NAME. If it exists it is activated. This function is put into the PROMPT_COMMAND variable and executed on every changed of directory. This function is intended for internal use by VirtualCandy itself, but it is available to the user.
This will find and print the full path of the current project's Virtualenv location. This function is intended for internal use by VirtualCandy itself, but it is available to the user.
This is used to find the nearest directory containing the Virtualenv named by
$VC_DEFAULT_VENV_NAME bash variable. For instance you have Virtualenv
and you run vcfinddir from the directory:
the result will be:
This function is intended for internal use by VirtualCandy itself, but it is
available to the user.
This will print out environemental variables used by VirtualCandy to stdout. This can be useful for
creating a base
.vc_proj file for a project.
Per project settings via
You can use per project Virtualcandy settings by adding a file named
the same directory as your
requirements.txt file. The
.vc_proj file will be sourced
every time a Virtualcandy command is used. Settings in the
.vc_proj file is a simple matter
of setting shell variables.
.vc_proj file that sets the Python executable to Python3 and sets the name of the
Virtualenv directory to
It's helpful to use the
vcproj command to create a base
.vc_proj file with defaults to get
vcproj > .vc_proj
Available config variables
VC_DEFAULT_VENV_NAMEName of the Virtualenv directory, Default is '.venv'
VC_DEFAULT_VENV_REQFILEName of the requirements file, Default is 'requirements.txt'
VC_AUTO_ACTIVATIONEnable auto Virtualenv activation, Default is true
VC_PYTHON_EXEPython executable to use for the Virtualenv, Default is $(basename $(which python))
VC_VIRTUALENV_EXEVirtualenv command to use, Default is virtualenv