Struct VirtualEnv

pub struct VirtualEnv<'a> { /* private fields */ }

A Python virtual environment.

This creates or re-uses a virtual environment. All Python invocations in this environment will have access to the environment’s code, including installed libraries and packages.

Use VirtualEnv::new to create a new environment.

The virtual environment gets deactivated on Drop.

Example

use xshell_venv::{Shell, VirtualEnv};

let sh = Shell::new()?;
let venv = VirtualEnv::new(&sh, "py3")?;

venv.run("print('Hello World!')")?; // "Hello World!"

Implementations

impl<'a> VirtualEnv<'a>

pub fn new(shell: &'a Shell, name: &str) -> Result<VirtualEnv<'a>, Error>

Create a Python virtual environment with the given name.

This creates a new environment or reuses an existing one. Preserves the environment across calls and makes it available for all other commands within the same Shell.

This will try to build a path based on the following environment variables:

• CARGO_TARGET_DIR
• OUT_DIR 3 levels up¹
• CARGO_MANIFEST_DIR

¹ should usually be the crate’s/workspace’s target directory.

If none of these are set it will use the system’s temporary directory, e.g. /tmp.

Example

let sh = Shell::new()?;
let venv = VirtualEnv::new(&sh, "py3")?;

pub fn with_path( shell: &'a Shell, venv_dir: &Path, ) -> Result<VirtualEnv<'a>, Error>

Create a Python virtual environment in the given path.

This creates a new environment or reuses an existing one.

Example

let sh = Shell::new()?;

let mut dir = std::env::temp_dir();
dir.push("xshell-py3");
let venv = VirtualEnv::with_path(&sh, &dir)?;

let output = venv.run("print('hello python')")?;
assert_eq!("hello python", output);

pub fn pip_install(&self, package: &str) -> Result<()>

Install a Python package in this virtual environment.

The package can be anything pip accepts, including specifying the version ($name==1.0.0) or repositories (git+https://github.com/$name/$repo@branch#egg=$name).

Example

let sh = Shell::new()?;
let venv = VirtualEnv::new(&sh, "py3")?;

venv.pip_install("flake8")?;
let output = venv.run_module("flake8", &["--version"])?;
assert!(output.contains("flake"));

pub fn pip_upgrade(&self, package: &str) -> Result<()>

Upgrade a Python package in this virtual environment.

The package can be anything pip accepts, including specifying the version ($name==1.0.0) or repositories (git+https://github.com/$name/$repo@branch#egg=$name).

Example

let sh = Shell::new()?;
let venv = VirtualEnv::new(&sh, "py3")?;

venv.pip_install("flake8==3.9.2")?;
let output = venv.run_module("flake8", &["--version"])?;
assert!(output.contains("3.9.2"), "Expected `3.9.2` in output. Got: {}", output);

venv.pip_upgrade("flake8")?;
let output = venv.run_module("flake8", &["--version"])?;
assert!(!output.contains("3.9.2"), "Expected `3.9.2` NOT in output. Got: {}", output);

pub fn run(&self, code: &str) -> Result<String>

Run Python code in this virtual environment.

Returns the code’s output.

Example

let sh = Shell::new()?;
let venv = VirtualEnv::new(&sh, "py3")?;

let output = venv.run("print('hello python')")?;
assert_eq!("hello python", output);

pub fn run_module(&self, module: &str, args: &[&str]) -> Result<String>

Run library module as a script.

This is python -m $module. Additional arguments are passed through as is.

Example

let sh = Shell::new()?;
let venv = VirtualEnv::new(&sh, "py3")?;

let output = venv.run_module("pip", &["--version"])?;
assert!(output.contains("pip"));