Extend functionality

virtualenv allows one to extend the builtin functionality via a plugin system. To add a plugin you need to:

  • write a python file containing the plugin code which follows our expected interface,

  • package it as a python library,

  • install it alongside the virtual environment.

Warning

The public API of some of these components is still to be finalized, consider the current interface a beta one until we get some feedback on how well we planned ahead. We expect to do this by end of Q3 2020. Consider the class interface explained below as initial draft proposal. We reserve the right to change the API until then, however such changes will be communicated in a timely fashion, and you’ll have time to migrate. Thank you for your understanding.

Python discovery

The python discovery mechanism is a component that needs to answer the following answer: based on some type of user input give me a Python interpreter on the machine that matches that. The builtin interpreter tries to discover an installed Python interpreter (based on PEP-515 and PATH discovery) on the users machine where the user input is a python specification. An alternative such discovery mechanism for example would be to use the popular pyenv project to discover, and if not present install the requested Python interpreter. Python discovery mechanisms must be registered under key virtualenv.discovery, and the plugin must implement virtualenv.discovery.discover.Discover:

virtualenv.discovery =
     pyenv = virtualenv_pyenv.discovery:PyEnvDiscovery
class virtualenv.discovery.discover.Discover(options)

Discover and provide the requested Python interpreter

Create a new discovery mechanism.

Parameters

options – the parsed options as defined within add_parser_arguments()

classmethod add_parser_arguments(parser)

Add CLI arguments for this discovery mechanisms.

Parameters

parser – the CLI parser

abstract run()

Discovers an interpreter.

Returns

the interpreter ready to use for virtual environment creation

property interpreter
Returns

the interpreter as returned by run(), cached

Creators

Creators are what actually perform the creation of a virtual environment. The builtin virtual environment creators all achieve this by referencing a global install; but would be just as valid for a creator to install a brand new entire python under the target path; or one could add additional creators that can create virtual environments for other python implementations, such as IronPython. They must be registered under and entry point with key virtualenv.discovery , and the class must implement virtualenv.create.creator.Creator:

virtualenv.create =
     cpython3-posix = virtualenv.create.via_global_ref.builtin.cpython.cpython3:CPython3Posix
class virtualenv.create.creator.Creator(options, interpreter)

A class that given a python Interpreter creates a virtual environment

Construct a new virtual environment creator.

Parameters

  • options – the CLI option as parsed from add_parser_arguments()

  • interpreter – the interpreter to create virtual environment from

classmethod can_create(interpreter)

Determine if we can create a virtual environment.

Parameters

interpreter – the interpreter in question

Returns

None if we can’t create, any other object otherwise that will be forwarded to add_parser_arguments()

classmethod add_parser_arguments(parser, interpreter, meta, app_data)

Add CLI arguments for the creator.

Parameters

  • parser – the CLI parser

  • app_data – the application data folder

  • interpreter – the interpreter we’re asked to create virtual environment for

  • meta – value as returned by can_create()

abstract create()

Perform the virtual environment creation.

setup_ignore_vcs()

Generate ignore instructions for version control systems.

Seed mechanism

Seeders are what given a virtual environment will install somehow some seed packages into it. They must be registered under and entry point with key virtualenv.seed , and the class must implement virtualenv.seed.seeder.Seeder:

virtualenv.seed =
     db = virtualenv.seed.fromDb:InstallFromDb
class virtualenv.seed.seeder.Seeder(options, enabled)

A seeder will install some seed packages into a virtual environment.

Parameters

  • options – the parsed options as defined within add_parser_arguments()

  • enabled – a flag weather the seeder is enabled or not

classmethod add_parser_arguments(parser, interpreter, app_data)

Add CLI arguments for this seed mechanisms.

Parameters

  • parser – the CLI parser

  • app_data – the CLI parser

  • interpreter – the interpreter this virtual environment is based of

abstract run(creator)

Perform the seed operation.

Parameters

creator – the creator (based of virtualenv.create.creator.Creator) we used to create this virtual environment

Activation scripts

If you want add an activator for a new shell you can do this by implementing a new activator. They must be registered under and entry point with key virtualenv.activate , and the class must implement virtualenv.activation.activator.Activator:

virtualenv.activate =
     bash = virtualenv.activation.bash:BashActivator
class virtualenv.activation.activator.Activator(options)

Generates an activate script for the virtual environment

Create a new activator generator.

Parameters

options – the parsed options as defined within add_parser_arguments()

classmethod supports(interpreter)

Check if the activation script is supported in the given interpreter.

Parameters

interpreter – the interpreter we need to support

Returns

True if supported, False otherwise

classmethod add_parser_arguments(parser, interpreter)

Add CLI arguments for this activation script.

Parameters

  • parser – the CLI parser

  • interpreter – the interpreter this virtual environment is based of

abstract generate(creator)

Generate the activate script for the given creator.

Parameters

creator – the creator (based of virtualenv.create.creator.Creator) we used to create this virtual environment