Venvstarter¶

Program to bootstrap a virtualenv for your program!

Full documentation at http://venvstarter.readthedocs.io

Installation¶

Just use pip!:

$ pip install venvstarter

Why¶

I used to manage this kind of bootstrap script with bash, similar to how I manage the virtualenv for the documentation for this project.

The problem with that approach is it becomes difficult to enforce particular versions of python and, in particular, multiple dependencies in a way that doesn’t involve some pretty horrible code. So I made this :)

Api¶

A program to manage your program in a virtualenv and ensure it and any other dependencies you may have are in that virtualenv before starting the program.

Essentially you create a bootstrap script using this program, something like:

#!/usr/bin/env python
__requires__ = ["venvstarter"]
import pkg_resources

from venvstarter import ignite
ignite(__file__, "harpoon"
    , deps = ["docker-harpoon==0.6.8.3"]
    , env = {"HARPOON_CONFIG": "{venv_parent}/harpoon.yml"}
    )

The __requires__ at the top is so that pkg_resources can tell you if venvstarter is not installed, and then we import venvstarter.ignite and use that to run the harpoon program after first ensuring we have a virtualenv called .harpoon in the same folder as this bootstrap script along with the correct version of harpoon.

As a bonus we can also set environment variables that have venv_parent formatted into them which is the folder that the virtualenv sits in.

So your folder structure would look something like:

/project
    bootstrap
    .harpoon/
    harpoon.yml

Slow Startup

There is only one disadvantage and that is this process adds about 0.4 seconds to your startup time for your application.

The reason for this is because we have to shell out to the python in the virtualenv to work out if we need to update any of the dependencies.

If you want to skip checking the versions of your dependencies, then set VENV_STARTER_CHECK_DEPS=0 in your environment before starting the bootstrap and then the delay goes down to about 0.2 seconds.

class venvstarter.Starter(venv_folder, program, deps=None, env=None, min_python_version=3.5, max_python_version=None)¶

The main class that knows how to manage the virtualenv

venv_folder

A folder that the virtualenv will sit in.

Note that if you pass in the location of a file, it will use the folder that file sits in. This is convenient so you can just pass in __file__ from your bootstrap script.

program

The name of the program in the virtualenv’s bin directory to invoke.

venvstarter will do a os.exec to this program as it’s last action.

deps

An optional list of pip dependencies to install into your virtualenv

env

An optional dictionary of environment variables to add to the environment that the program is run in.

Note that each value is formatted with venv_parent available, which is the folder the virtualenv sits in.

min_python_version

Either a string or a pkg_resources.StrictVersion instance representing the minimum version of python needed for the virtualenv.

This will always default to 3.5.

max_python_version

An optional string or a pkg_resources.StrictVersion instance representing the maximum version of python needed for the virtualenv.

This must be a version equal to or greater than min_python_version.

Usage:

Starter(*args, **kwargs).ignite()

Note

you may pass a custom args array into ignite and it will use that instead of sys.argv

venvstarter.ignite(*args, **kwargs)¶: Convenience function to create a Starter instance and call ignite on it