pyenv Version Manager Plugin

A tox plugin that integrates with pyenv to discover Python executables for testing environments.

Overview

Build a tox plugin that uses pyenv to find Python executables. When pyenv is unavailable or fails, the plugin should log appropriate messages and fall back gracefully to tox's default behavior.

Requirements

Plugin Registration

The plugin must implement a hook function that tox calls to discover Python executables for test environments. This function receives an environment configuration object with a basepython attribute (e.g., "python3.8") and should return the path to the appropriate Python executable.

Logging Behavior

The plugin must provide detailed logging throughout its execution:

• When pyenv is not installed on the system, log a warning message indicating that pyenv is missing and the plugin may not be needed
• When pyenv fails to find a requested Python version, log debug-level information including the exact command that was executed and any error output from pyenv
• Use Python's standard logging module with a module-level logger

Fallback Mechanism

When pyenv cannot provide a Python executable (either because pyenv is not installed or because the requested version is not available), the plugin should return None to allow tox to use its default discovery mechanism.

Implementation Details

• Use subprocess to execute pyenv commands
• The command to find a Python executable is: pyenv which <basepython>
• Handle both OSError (when pyenv binary is missing) and non-zero exit codes (when pyenv fails to find the version)
• Capture stderr to include in debug messages when commands fail

Test Cases

• When pyenv is not installed, the hook returns None and logs a warning @test
• When pyenv successfully finds a Python executable, the hook returns the executable path @test
• When pyenv fails to find a version, the hook logs debug information including the command and stderr @test

@generates

Dependencies { .dependencies }

tox-pyenv { .dependency }

Provides pyenv integration for tox.