API

class venvstarter.Starter(program, venv_folder, venv_folder_name, deps=None, no_binary=None, env=None, min_python_version=None, max_python_version=None, packaging_version='23.2')

The main class that knows how to manage the virtualenv. It is recommended that manager is used instead of directly using this class.

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 program to run as None, a list, a string or as a function.

If set as None, then the python in the virtualenv is run

If the program is given as a string, we invoke it from the scripts in the virtualenv.

If the program is given as a list, then we os.execve(result[0], result + args, env)

If the program is given as a function, that function is provided the location to the virtualenv. If the function returns None then venvstarter will do nothing more. Otherwise if it will continue as if the program was the result of the function all along.

deps

An optional list of pip dependencies to install into your virtualenv

no_binary

List of deps that must not be installed as binary. It will identify if the dependency has already been installed as a binary and reinstall it to be installed from source.

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

An int, float, str, tuple or object with “version” of a tuple.

For example:

3
3.7
“3.7.13”
(3, 7, 13)
distutils.StrictVersion(“3.7.13”)

Represents the minimum version of python needed for the virtualenv.

This will always default to 3.7.

max_python_version

An int, float, str, tuple or object with “version” of a tuple.

For example:

3
3.7
“3.7.13”
(3, 7, 13)
distutils.StrictVersion(“3.7.13”)

Represents the maximum version of python allowed for the virtualenv.

This is optional but when specified must be a version equal to or greater than min_python_version.

Usage:

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

Note

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

There are also two environment variables that can change what this class does:

VENVSTARTER_ONLY_MAKE_VENV=1: This will make the class ensure the virtualenv exists and has the correct versions of specified dependencies but will then not do anything with that virtualenv
VENV_STARTER_CHECK_DEPS=0: This will make the class not check if the dependencies in the virtualenv are correct. This increases startup time at the cost of potentially having the wrong versions of dependencies in the virtualenv.
VENVSTARTER_UPGRADE_PIP=0: This will make sure that pip is not ensured to be greater than 23 before requirements are installed

class venvstarter.manager(program, here=None)

This is the main entry point to venvstarter. It provides a chained API for configuring a venvstarter Starter class and then running it.

Usage looks like:

(__import__("venvstarter").manager("black")
    .add_pypi_deps("black==23.9.1")
    .run()
    )

add_env(**env): Updates the dictionary of environment variables to run the program with

add_local_dep(*parts, editable=True, version_file=None, with_tests=False, name)

Adds a dependency that is local to your script. The path to where a folder where a setup.py can be found is provided as parts of a file that are joined together. Formatted into each part is here, home and venv_parent just like the parts in add_requirements_file().

editable: This is the same as saying pip install -e {path}. This is how pip is told to install the dependency as a symlink rather than as a static copy of the code at the time of installation.
version_file: This needs to be a tuple of strings. These are joined as a path from the source code of your dependency. This must be a file containing a variable called VERSION that is a version number for the dependency. Venvstarter will reinstall the local dependency if this number changes, which allows any new sub dependencies to be found.
with_tests: This is equivalent to saying pip install "{path}[tests]" and will tell pip to also install any dependencies found in the tests section of the extra_requires in setup.py.
name: This is used to tell pip the name of the dependency that is installed from this location.

add_no_binary(*no_binary): This will register more dependencies that must be installed from source. See Starter.

add_pypi_deps(*deps): This will add to the list of dependencies from pypi. This method may be called multiple times to add many dependencies.

add_requirements_file(*parts)

This adds a single requirements file. The strings you provide will be joined together to form one path. Each string will be formatted with:

here: The location of the directory your script exists in
home: The location of your current user’s home folder
venv_parent: The location of the folder the virtualenv will sit in.

For example:

manager(...).add_requirements_file("{here}", "..", "requirements.txt")

max_python(version): This will set the maximum version of python as provided. See Starter

min_python(version): This will set the minimum version of python as provided. See Starter

named(name): This will set the name of the virtualenv folder

place_venv_in(location): This will configure the virtualenv to exist in the provided location.

run(): This creates the Starter instance with the specified configuration and calls run on that.

set_packaging_version(packaging_version): This will override the default packaging version installed in the virtualenv for python versions from python3.8 and up

property venv_folder: The folder the virtualenv will sit in. If this has explicitly set, then that is returned, otherwise the value for here is returned.

property venv_folder_name

Returns the name of the virtualenv folder.

If it has been explicitly set, then that value is returned. Otherwise if the program is a string then it is returned with a prefixed dot, otherwise it uses .venv.