tox-pyenv

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.

Package Information

• Package Name: tox-pyenv
• Package Type: pypi
• Language: Python
• Installation: pip install tox-pyenv

Core Imports

import tox_pyenv

For accessing specific components:

from tox_pyenv import ToxPyenvException, PyenvMissing, PyenvWhichFailed

Basic Usage

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.

# Example circle.yml configuration
dependencies:
  override:
    - pip install tox tox-pyenv
    - pyenv local 2.7.9 3.4.3 3.5.0

# Example tox.ini configuration
[tox]
envlist = py27,py34,py35

[testenv]
# Optional: disable fallback to tox's default behavior
tox_pyenv_fallback = False

# Command line usage with no-fallback option
tox --tox-pyenv-no-fallback

Capabilities

Plugin Hook Functions

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

def tox_get_python_executable(envconfig):
    """
    Return a python executable for the given python base name using pyenv which.
    
    This hook function replaces tox's default python executable discovery.
    Uses `pyenv which {basepython}` to locate the appropriate python executable.
    
    Args:
        envconfig: testenv configuration object containing .envname and .basepython settings
        
    Returns:
        str or None: Path to python executable, or None if fallback is needed
        
    Raises:
        PyenvWhichFailed: If pyenv which command fails and fallback is disabled
    """

def tox_addoption(parser):
    """
    Add command line option to the argparse-style parser object.
    
    Adds the --tox-pyenv-no-fallback command line option and corresponding
    tox_pyenv_fallback configuration option.
    
    Args:
        parser: tox argument parser object
    """

Exception Classes

Custom exceptions for plugin-specific error handling.

class ToxPyenvException(Exception):
    """Base class for exceptions from this plugin."""

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

class PyenvWhichFailed(ToxPyenvException):
    """Calling `pyenv which` failed."""

Configuration Options

Command Line Options

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

tox.ini Configuration

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

Module Metadata

Package information constants available for introspection.

__title__ = 'tox-pyenv'
__summary__ = 'tox plugin that makes tox use `pyenv which` to find python executables'
__url__ = 'https://github.com/samstav/tox-pyenv'
__version__ = '1.1.0'
__author__ = 'Sam Stavinoha'
__email__ = 'smlstvnh@gmail.com'
__keywords__ = ['tox', 'pyenv', 'python']
__license__ = 'Apache License, Version 2.0'

Plugin Registration

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

# In setup.py
ENTRY_POINTS = {
    'tox': [
        'pyenv = tox_pyenv',
    ]
}

Error Handling

The plugin includes comprehensive error handling for common failure scenarios:

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

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.

Dependencies

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