Python Interpreter Hot-Swapping¶

omnipkg eliminates the need for separate virtual environments or containers to manage different Python versions. With the swap and python commands, you can instantly “hot-swap” the active Python interpreter for your entire shell session.

This is a cornerstone feature for working on legacy projects that require an older Python version while developing new features on a modern one, all within the same terminal.

How It Works: The Control Plane¶

omnipkg uses a stable “control plane” (running on Python 3.11) to manage all interpreter operations. When you request a swap, omnipkg: 1. Validates that the target interpreter is managed. 2. Atomically updates its configuration to point to the new interpreter’s executable. 3. Adjusts shell-level pointers (like python and pip symlinks) within its managed environment to reflect the change.

The result is a near-instantaneous switch of your environment’s context, without restarting your shell.

Managing Your Interpreters¶

Step 1: Adopting Interpreters¶

On first run, omnipkg automatically “adopts” your system’s default Python. To make other installed Python versions available for swapping, you must adopt them.

# Make your system's Python 3.9 available to omnipkg
omnipkg python adopt 3.9

# Make your system's Python 3.10 available
omnipkg python adopt 3.10

Step 2: Listing Available Interpreters¶

To see which interpreters are ready for swapping, run:

omnipkg list python

Hot-Swapping in Practice¶

The omnipkg swap command is the easiest way to switch your active Python.

Direct Swap¶

If you know the version you want, specify it directly:

# Check current version
python --version
# Python 3.11.5

# Swap to Python 3.9
omnipkg swap python 3.9
# 🎉 Successfully switched omnipkg context to Python 3.9!

# Verify the change
python --version
# Python 3.9.18

Interactive Swap¶

If you want to choose from a list of available interpreters, run the command without a version:

omnipkg swap python

Use Case: Multiverse Analysis¶

This powerful feature enables “multiverse analysis,” where a single script or CI/CD pipeline can execute tasks across multiple Python versions in sequence, within a single environment. The omnipkg stress-test command is a live demonstration of this capability, proving its robustness and efficiency. ```