0
# tox-pyenv
1

2
A tox plugin that integrates pyenv with tox for Python version management during testing. The plugin replaces tox's default Python executable discovery mechanism with pyenv's `pyenv which` command, ensuring tox uses specific Python versions managed by pyenv rather than falling back to system-wide installations.
3

4
## Package Information
5

6
- **Package Name**: tox-pyenv
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install tox-pyenv`
10

11
## Core Imports
12

13
```python
14
import tox_pyenv
15
```
16

17
For accessing specific components:
18

19
```python
20
from tox_pyenv import ToxPyenvException, PyenvMissing, PyenvWhichFailed
21
```
22

23
## Basic Usage
24

25
The plugin automatically activates when installed alongside tox. No explicit import or initialization is required in user code - it operates through tox's plugin system.
26

27
```yaml
28
# Example circle.yml configuration
29
dependencies:
30
  override:
31
    - pip install tox tox-pyenv
32
    - pyenv local 2.7.9 3.4.3 3.5.0
33
```
34

35
```ini
36
# Example tox.ini configuration
37
[tox]
38
envlist = py27,py34,py35
39

40
[testenv]
41
# Optional: disable fallback to tox's default behavior
42
tox_pyenv_fallback = False
43
```
44

45
```bash
46
# Command line usage with no-fallback option
47
tox --tox-pyenv-no-fallback
48
```
49

50
## Capabilities
51

52
### Plugin Hook Functions
53

54
Functions that integrate with tox's plugin system to modify its behavior.
55

56
```python { .api }
57
def tox_get_python_executable(envconfig):
58
    """
59
    Return a python executable for the given python base name using pyenv which.
60
    
61
    This hook function replaces tox's default python executable discovery.
62
    Uses `pyenv which {basepython}` to locate the appropriate python executable.
63
    
64
    Args:
65
        envconfig: testenv configuration object containing .envname and .basepython settings
66
        
67
    Returns:
68
        str or None: Path to python executable, or None if fallback is needed
69
        
70
    Raises:
71
        PyenvWhichFailed: If pyenv which command fails and fallback is disabled
72
    """
73

74
def tox_addoption(parser):
75
    """
76
    Add command line option to the argparse-style parser object.
77
    
78
    Adds the --tox-pyenv-no-fallback command line option and corresponding
79
    tox_pyenv_fallback configuration option.
80
    
81
    Args:
82
        parser: tox argument parser object
83
    """
84
```
85

86
### Exception Classes
87

88
Custom exceptions for plugin-specific error handling.
89

90
```python { .api }
91
class ToxPyenvException(Exception):
92
    """Base class for exceptions from this plugin."""
93

94
class PyenvMissing(ToxPyenvException, RuntimeError):
95
    """The pyenv program is not installed."""
96

97
class PyenvWhichFailed(ToxPyenvException):
98
    """Calling `pyenv which` failed."""
99
```
100

101
### Configuration Options
102

103
#### Command Line Options
104

105
- `--tox-pyenv-no-fallback` / `-F`: Disable fallback to tox's built-in python executable discovery when pyenv fails
106

107
#### tox.ini Configuration
108

109
- `tox_pyenv_fallback` (bool): If `pyenv which {basepython}` fails, allow fallback to tox's built-in default logic (default: True)
110

111
### Module Metadata
112

113
Package information constants available for introspection.
114

115
```python { .api }
116
__title__ = 'tox-pyenv'
117
__summary__ = 'tox plugin that makes tox use `pyenv which` to find python executables'
118
__url__ = 'https://github.com/samstav/tox-pyenv'
119
__version__ = '1.1.0'
120
__author__ = 'Sam Stavinoha'
121
__email__ = 'smlstvnh@gmail.com'
122
__keywords__ = ['tox', 'pyenv', 'python']
123
__license__ = 'Apache License, Version 2.0'
124
```
125

126
## Plugin Registration
127

128
The plugin is automatically registered with tox via setuptools entry points:
129

130
```python
131
# In setup.py
132
ENTRY_POINTS = {
133
    'tox': [
134
        'pyenv = tox_pyenv',
135
    ]
136
}
137
```
138

139
## Error Handling
140

141
The plugin includes comprehensive error handling for common failure scenarios:
142

143
- **OSError**: When pyenv command is not found or not executable
144
- **Subprocess failures**: When `pyenv which` command returns non-zero exit code
145
- **Configurable fallback**: Plugin can fall back to tox's default behavior or raise exceptions based on configuration
146

147
When fallback is enabled (default: True), the plugin logs warnings and allows tox to continue with its built-in executable discovery. When fallback is disabled, the plugin raises `PyenvWhichFailed` exceptions to halt execution.
148

149
## Dependencies
150

151
- **tox** >= 2.0: Required for plugin system integration
152
- **py**: Used for path utilities and system executable finding
153
- **subprocess**: Standard library module for executing pyenv commands
154
- **logging**: Standard library module for debug and warning messages