| Name | virtualenv-pyenv JSON |
| Version |
0.5.0
JSON |
| download |
| home_page | |
| Summary | A virtualenv Python discovery plugin for pyenv-installed interpreters |
| upload_time | 2024-01-17 09:20:14 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.8 |
| license | MIT |
| keywords |
virtualenv
pyenv
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# virtualenv-pyenv
A [virtualenv][virtualenv] Python discovery plugin for [pyenv][pyenv]–installed interpreters
## Installation
```shell
pip install virtualenv-pyenv
```
## Usage
The Python discovery mechanism can be specified by:
* the CLI option `--discovery`:
```shell
virtualenv --discovery pyenv -p 3.10 testenv
```
* the environment variable `VIRTUALENV_DISCOVERY`:
```shell
export VIRTUALENV_DISCOVERY=pyenv
virtualenv -p 3.10 testenv
```
* the [config][virtualenv-docs-config-file] option `discovery`:
```ini
[virtualenv]
discovery = pyenv
```
```shell
virtualenv -p 3.10 testenv
```
* the [virtualenvwrapper][virtualenvwrapper] environment variable `VIRTUALENVWRAPPER_VIRTUALENV_ARGS`:
```shell
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.,
```shell
virtualenv --discovery=pyenv-fallback -p 3.10 testenv
```
or
```shell
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][build], [tox][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] (`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][virtualenv] ([docs][virtualenv-docs-specifier-format]). A subset of this format is used by [tox][tox] ([docs][tox-docs-testenv-factors]).
* 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][pyenv-inspect] library, which, in turn, inspects `$PYENV_ROOT/versions` directory contents.
[virtualenv]: https://virtualenv.pypa.io/
[pyenv]: https://github.com/pyenv/pyenv
[virtualenvwrapper]: https://virtualenvwrapper.readthedocs.io/en/latest/
[tox]: https://tox.wiki/en/latest/
[pyenv-inspect]: https://github.com/un-def/pyenv-inspect
[build]: https://github.com/pypa/build
[virtualenv-docs-config-file]: https://virtualenv.pypa.io/en/latest/cli_interface.html#configuration-file
[virtualenv-docs-specifier-format]: https://virtualenv.pypa.io/en/latest/user_guide.html#python-discovery
[tox-docs-testenv-factors]: https://tox.wiki/en/latest/user_guide.html#test-environments
Raw data
{
"_id": null,
"home_page": "",
"name": "virtualenv-pyenv",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "virtualenv,pyenv",
"author": "",
"author_email": "Dmitry Meyer <me@undef.im>",
"download_url": "https://files.pythonhosted.org/packages/5f/a3/75443f72408a3ab0d39a5e05a0ce6152bf0bf4c2636114c9c07d76b65bb2/virtualenv-pyenv-0.5.0.tar.gz",
"platform": null,
"description": "# virtualenv-pyenv\n\nA [virtualenv][virtualenv] Python discovery plugin for [pyenv][pyenv]\u2013installed interpreters\n\n## Installation\n\n```shell\npip install virtualenv-pyenv\n```\n\n## Usage\n\nThe Python discovery mechanism can be specified by:\n\n* the CLI option `--discovery`:\n ```shell\n virtualenv --discovery pyenv -p 3.10 testenv\n ```\n\n* the environment variable `VIRTUALENV_DISCOVERY`:\n ```shell\n export VIRTUALENV_DISCOVERY=pyenv\n virtualenv -p 3.10 testenv\n ```\n\n* the [config][virtualenv-docs-config-file] option `discovery`:\n ```ini\n [virtualenv]\n discovery = pyenv\n ```\n\n ```shell\n virtualenv -p 3.10 testenv\n ```\n\n* the [virtualenvwrapper][virtualenvwrapper] environment variable `VIRTUALENVWRAPPER_VIRTUALENV_ARGS`:\n ```shell\n export VIRTUALENVWRAPPER_VIRTUALENV_ARGS='--discovery=pyenv'\n mkvirtualenv -p 3.10 testenv\n ```\n\n## Operation Mode\n\nThe plugin supports several operation modes. The operation mode affects various aspects of the discovery process.\n\n|mode |specifier|path specifier|fallback to `builtin`|\n|----------|---------|--------------|---------------------|\n|`compat` |optional |allowed |no |\n|`fallback`|optional |allowed |yes |\n|`strict` |required |error |no |\n\nThe mode is specified as a part of the discovery method name: `pyenv-{mode}`, e.g.,\n\n```shell\nvirtualenv --discovery=pyenv-fallback -p 3.10 testenv\n```\n\nor\n\n```shell\nexport VIRTUALENV_DISCOVERY=pyenv-strict\nvirtualenv -p 3.10 testenv\n```\n\nIf no mode is specified, the `compat` mode is used, that is, `--discovery=pyenv` is the same as `--discovery=pyenv-compat`.\n\nThe `compat` mode is recommended for most cases. It mimics closely the `builtin` discovery plugin to maximize compatibility with existing tools (e.g., [build][build], [tox][tox]):\n\n* if no specifier is provided, the plugin falls back to `sys.executable`, even if it is not installed by pyenv;\n* if a path specifier (`-p /path/to/bin/python`) is provided, the path is used, even if it is not installed by pyenv;\n* otherwise (`-p 3.7`, `-p py37`), only pyenv\u2013installed interpreters are used.\n\nThe `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.\n\nThe `strict` mode, as its name suggests, ensures that only pyenv\u2013installed interpreters are used:\n\n* 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);\n* a path specifier is not allowed, even if the path points to a pyenv\u2013installed interpreter (may be relaxed in the future);\n* no fallback to the `builtin` plugin.\n\n## Python Specifier Format\n\nThe plugin supports two specifier formats informally called \u201cpyenv-style\u201d and \u201cvirtualenv-style\u201d.\n\nThe version part of both specifier formats can contain one (`major`), two (`major.minor`), or three (`major.minor.patch`) components. When a one\u2013component version is specified, the latest installed final minor release is selected, ignoring pre\u2013/dev\u2013release. When a two\u2013component version is specified, the latest installed final patch release is selected, ignoring pre\u2013/dev\u2013releases. When a three\u2013component version is specified, the exact final release is selected, ignoring pre\u2013/dev\u2013releases. The pre\u2013/dev\u2013release version is selected only if it is explicitly requested.\n\n|installed |requested |selected |\n|---------------------------|----------|----------|\n|`3.9.5`; `3.9.17`, `3.10.0`|`3` |`3.10.0` |\n|`3.9.5`; `3.9.17`, `3.10.0`|`3.9` |`3.9.17` |\n|`3.9.5`; `3.9.17`, `3.10.0`|`3.9.5` |`3.9.5` |\n|`3.9.5`; `3.9.17`, `3.10.0`|`3.9.0` |\u2014 |\n|`3.12-dev`; `3.12.0b3` |`3.12` |\u2014 |\n|`3.12-dev`; `3.12.0b3` |`3.12.0` |\u2014 |\n|`3.12-dev`; `3.12.0b3` |`3.12-dev`|`3.12-dev`|\n|`3.12-dev`; `3.12.0b3` |`3.12.0b3`|`3.12.0b3`|\n\n### pyenv\u2013style\n\nThe same format as used by [pyenv][pyenv] (`pyenv install --list`).\n\n* a final version with 1 version component: `3`\n* a final version with 2 version components: `3.11`\n* a final version with 3 version components: `3.11.2`\n* a pre\u2013release version: `3.13.0a4`, `3.12.0b3`, `3.11.0rc1`\n* a dev version: `3.13-dev`\n\n### virtualenv\u2013style\n\nThe same format as used by [virtualenv][virtualenv] ([docs][virtualenv-docs-specifier-format]). A subset of this format is used by [tox][tox] ([docs][tox-docs-testenv-factors]).\n\n* a relative or absolute path: `/path/to/bin/python` (it can be any Python interpreter, not only installed by pyenv)\n* a final version with 1 version component: `py3`, `python3`, `cpython3`, `python3-32`, `py3-64`\n* a final version with 2 version components: `311`, `py311`, `py3.11`, `python311`, `cpython3.11`, `python3.11-32`, `py311-64`\n* a final version with 3 version components: `py3.11.2`, `python3.11.2`, `cpython3.11.2`, `python3.11.2-32`, `py3.11.2-64`\n\n## Limitations\n\n* Only CPython is supported at the moment.\n* 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`.\n\n## Internals\n\nvirtualenv-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][pyenv-inspect] library, which, in turn, inspects `$PYENV_ROOT/versions` directory contents.\n\n\n[virtualenv]: https://virtualenv.pypa.io/\n[pyenv]: https://github.com/pyenv/pyenv\n[virtualenvwrapper]: https://virtualenvwrapper.readthedocs.io/en/latest/\n[tox]: https://tox.wiki/en/latest/\n[pyenv-inspect]: https://github.com/un-def/pyenv-inspect\n[build]: https://github.com/pypa/build\n[virtualenv-docs-config-file]: https://virtualenv.pypa.io/en/latest/cli_interface.html#configuration-file\n[virtualenv-docs-specifier-format]: https://virtualenv.pypa.io/en/latest/user_guide.html#python-discovery\n[tox-docs-testenv-factors]: https://tox.wiki/en/latest/user_guide.html#test-environments\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A virtualenv Python discovery plugin for pyenv-installed interpreters",
"version": "0.5.0",
"project_urls": {
"Changelog": "https://github.com/un-def/virtualenv-pyenv/releases",
"Homepage": "https://github.com/un-def/virtualenv-pyenv",
"Issues": "https://github.com/un-def/virtualenv-pyenv/issues",
"Repository": "https://github.com/un-def/virtualenv-pyenv.git"
},
"split_keywords": [
"virtualenv",
"pyenv"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "123985a4b5b60f8425c22ceb1770fb265ee9073ca8b57654316f8108837db006",
"md5": "1dcdc099649934e38ec4d4b2b9765ca4",
"sha256": "21750247e36c55b3c547cfdeb08f51a3867fe7129922991a4f9c96980c0a4a5d"
},
"downloads": -1,
"filename": "virtualenv_pyenv-0.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1dcdc099649934e38ec4d4b2b9765ca4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 7078,
"upload_time": "2024-01-17T09:20:12",
"upload_time_iso_8601": "2024-01-17T09:20:12.730527Z",
"url": "https://files.pythonhosted.org/packages/12/39/85a4b5b60f8425c22ceb1770fb265ee9073ca8b57654316f8108837db006/virtualenv_pyenv-0.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5fa375443f72408a3ab0d39a5e05a0ce6152bf0bf4c2636114c9c07d76b65bb2",
"md5": "8e0290128a290a90729dd64a4d1d5e1b",
"sha256": "7b0e5fe3dfbdf484f4cf9b01e1f98111e398db6942237910f666356e6293597f"
},
"downloads": -1,
"filename": "virtualenv-pyenv-0.5.0.tar.gz",
"has_sig": false,
"md5_digest": "8e0290128a290a90729dd64a4d1d5e1b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 8901,
"upload_time": "2024-01-17T09:20:14",
"upload_time_iso_8601": "2024-01-17T09:20:14.189918Z",
"url": "https://files.pythonhosted.org/packages/5f/a3/75443f72408a3ab0d39a5e05a0ce6152bf0bf4c2636114c9c07d76b65bb2/virtualenv-pyenv-0.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-17 09:20:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "un-def",
"github_project": "virtualenv-pyenv",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "virtualenv-pyenv"
}
