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.
Python discovery¶
The python discovery mechanism is a component that needs to answer the following question: 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
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.create
, 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 toadd_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.
- add_cachedir_tag()¶
Generate a file indicating that this is not meant to be backed up.
- 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.
Create.
- 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 an 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 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 activate script for the given creator.
- Parameters:
creator – the creator (based of
virtualenv.create.creator.Creator
) we used to create this virtual environment