Skip to main content

A virtualenv Python discovery plugin for pyenv-installed interpreters

Project description

virtualenv-pyenv

A virtualenv Python discovery plugin for pyenv–installed interpreters

Installation

pip install virtualenv-pyenv

Usage

The Python discovery mechanism can be specified by:

  • the CLI option --discovery:

    virtualenv --discovery pyenv -p 3.10 testenv
    
  • the environment variable VIRTUALENV_DISCOVERY:

    export VIRTUALENV_DISCOVERY=pyenv
    virtualenv -p 3.10 testenv
    
  • the config option discovery:

    [virtualenv]
    discovery = pyenv
    
    virtualenv -p 3.10 testenv
    
  • the virtualenvwrapper environment variable VIRTUALENVWRAPPER_VIRTUALENV_ARGS:

    export VIRTUALENVWRAPPER_VIRTUALENV_ARGS='--discovery=pyenv'
    mkvirtualenv -p 3.10 testenv
    

Operation Mode

The plugin supports several operation modes. The operation mode affects various aspects of the discovery process.

mode specifier path specifier fallback to builtin
compat optional allowed no
fallback optional allowed yes
strict required error no

The mode is specified as a part of the discovery method name: pyenv-{mode}, e.g.,

virtualenv --discovery=pyenv-fallback -p 3.10 testenv

or

export VIRTUALENV_DISCOVERY=pyenv-strict
virtualenv -p 3.10 testenv

If no mode is specified, the compat mode is used, that is, --discovery=pyenv is the same as --discovery=pyenv-compat.

The compat mode is recommended for most cases. It mimics closely the builtin discovery plugin to maximize compatibility with existing tools (e.g., build, tox):

  • if no specifier is provided, the plugin falls back to sys.executable, even if it is not installed by pyenv;
  • if a path specifier (-p /path/to/bin/python) is provided, the path is used, even if it is not installed by pyenv;
  • otherwise (-p 3.7, -p py37), only pyenv–installed interpreters are used.

The fallback mode is the same as compat, but in addition falls back to the builtin plugin if no interpreter was found. If multiple specifiers are provided, all of them are tried first before falling back to the builtin plugin as a last resort.

The strict mode, as its name suggests, ensures that only pyenv–installed interpreters are used:

  • a specifier is required, sys.executable is never used as a fallback, even if it is installed by pyenv (may be relaxed in the future);
  • a path specifier is not allowed, even if the path points to a pyenv–installed interpreter (may be relaxed in the future);
  • no fallback to the builtin plugin.

Python Specifier Format

The plugin supports two specifier formats informally called “pyenv-style” and “virtualenv-style”.

The version part of both specifier formats can contain one (major), two (major.minor), or three (major.minor.patch) components. When a one–component version is specified, the latest installed final minor release is selected, ignoring pre–/dev–release. When a two–component version is specified, the latest installed final patch release is selected, ignoring pre–/dev–releases. When a three–component version is specified, the exact final release is selected, ignoring pre–/dev–releases. The pre–/dev–release version is selected only if it is explicitly requested.

installed requested selected
3.9.5; 3.9.17, 3.10.0 3 3.10.0
3.9.5; 3.9.17, 3.10.0 3.9 3.9.17
3.9.5; 3.9.17, 3.10.0 3.9.5 3.9.5
3.9.5; 3.9.17, 3.10.0 3.9.0
3.12-dev; 3.12.0b3 3.12
3.12-dev; 3.12.0b3 3.12.0
3.12-dev; 3.12.0b3 3.12-dev 3.12-dev
3.12-dev; 3.12.0b3 3.12.0b3 3.12.0b3

pyenv–style

The same format as used by pyenv (pyenv install --list).

  • a final version with 1 version component: 3
  • a final version with 2 version components: 3.11
  • a final version with 3 version components: 3.11.2
  • a pre–release version: 3.13.0a4, 3.12.0b3, 3.11.0rc1
  • a dev version: 3.13-dev

virtualenv–style

The same format as used by virtualenv (docs). A subset of this format is used by tox (docs).

  • a relative or absolute path: /path/to/bin/python (it can be any Python interpreter, not only installed by pyenv)
  • a final version with 1 version component: py3, python3, cpython3, python3-32, py3-64
  • a final version with 2 version components: 311, py311, py3.11, python311, cpython3.11, python3.11-32, py311-64
  • a final version with 3 version components: py3.11.2, python3.11.2, cpython3.11.2, python3.11.2-32, py3.11.2-64

Limitations

  • Only CPython is supported at the moment.
  • The architecture part (-32/-64) of a specifier is ignored. For example, all of the following specifiers match any installed CPython 3.8.1 regardless of the architecture: python3.8.1, python3.8.1-32, python3.8.1-64.

Internals

virtualenv-pyenv does not rely on pyenv to discover Python interpreters, that is, it never calls any pyenv command and does not require pyenv to be in PATH. Instead, the plugin uses pyenv-inspect library, which, in turn, inspects $PYENV_ROOT/versions directory contents.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

virtualenv-pyenv-0.5.0.tar.gz (8.9 kB view details)

Uploaded Source

Built Distribution

virtualenv_pyenv-0.5.0-py3-none-any.whl (7.1 kB view details)

Uploaded Python 3

File details

Details for the file virtualenv-pyenv-0.5.0.tar.gz.

File metadata

  • Download URL: virtualenv-pyenv-0.5.0.tar.gz
  • Upload date:
  • Size: 8.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.11.4

File hashes

Hashes for virtualenv-pyenv-0.5.0.tar.gz
Algorithm Hash digest
SHA256 7b0e5fe3dfbdf484f4cf9b01e1f98111e398db6942237910f666356e6293597f
MD5 8e0290128a290a90729dd64a4d1d5e1b
BLAKE2b-256 5fa375443f72408a3ab0d39a5e05a0ce6152bf0bf4c2636114c9c07d76b65bb2

See more details on using hashes here.

File details

Details for the file virtualenv_pyenv-0.5.0-py3-none-any.whl.

File metadata

File hashes

Hashes for virtualenv_pyenv-0.5.0-py3-none-any.whl
Algorithm Hash digest
SHA256 21750247e36c55b3c547cfdeb08f51a3867fe7129922991a4f9c96980c0a4a5d
MD5 1dcdc099649934e38ec4d4b2b9765ca4
BLAKE2b-256 123985a4b5b60f8425c22ceb1770fb265ee9073ca8b57654316f8108837db006

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page