vpython

Documentation

Overview

Package vpython implements the vpython tool and associated libraries.

Index

• Variables
• func Exec(c context.Context, interp *python.Interpreter, cl *python.CommandLine, ...) error
• func Run(c context.Context, opts Options) error
• type Options
  • func (o *Options) ResolveSpec(c context.Context) (err error)

Variables

var IsUserError = errors.BoolTag{
	Key: errors.NewTagKey("this error occurred due to a user input."),
}

IsUserError is tagged into errors caused by bad user inputs (e.g. modules or scripts which don't exist).

Functions

func Exec

func Exec(c context.Context, interp *python.Interpreter, cl *python.CommandLine, env environ.Env, dir string, setupFn func() error) error

Exec runs the specified Python command.

Once the process launches, Context cancellation will not have an impact.

interp is the Python interperer to run.

cl is the populated CommandLine to run.

env is the environment to install.

dir, if not empty, is the working directory of the command.

setupFn, if not nil, is a function that will be run immediately before execution, after all operations that are permitted to fail have completed. Any error returned here will result in a panic.

If an error occurs during execution, it will be returned here. Otherwise, Exec will not return, and this process will exit with the return code of the executed process.

The implementation of Exec is platform-specific.

func Run

func Run(c context.Context, opts Options) error

Run sets up a Python VirtualEnv and executes the supplied Options.

If the Python interpreter was successfully launched, Run will never return, and the process will exit with the return code of the Python interpreter.

If the Python environment could not be set-up, or if the interpreter could not be invoked, Run will return an non-nil error.

Run consists of:

• Identify the target Python script to run (if there is one).
• Identifying the Python interpreter to use.
• Composing the environment specification.
• Constructing the virtual environment (download, install).
• Execute the Python process with the supplied arguments.

The Python subprocess is bound to the lifetime of ctx, and will be terminated if ctx is cancelled.

Types

type Options

type Options struct {
	// The Python command-line to execute. Must not be nil.
	CommandLine *python.CommandLine

	// EnvConfig is the VirtualEnv configuration to run from.
	EnvConfig venv.Config

	// DefaultSpec is the default specification to use, if no specification was
	// supplied or probed.
	DefaultSpec *vpython.Spec

	// BaseWheels is the set of wheels to include in the spec. These will always
	// be merged into the runtime spec and normalized, such that any duplicate
	// wheels will be deduplicated.
	BaseWheels []*vpython.Spec_Package

	// SpecLoader is the spec.Loader to use to load a specification file for a
	// given script.
	//
	// The empty value is a valid default spec.Loader.
	SpecLoader spec.Loader

	// WaitForEnv, if true, means that if another agent holds a lock on the target
	// environment, we will wait until it is available. If false, we will
	// immediately exit Setup with an error.
	WaitForEnv bool

	// WorkDir is the Python working directory. If empty, the current working
	// directory will be used.
	//
	// If EnvRoot is empty, WorkDir will be used as the base environment root.
	WorkDir string

	// Environ is environment to pass to subprocesses.
	Environ environ.Env

	// ClearPythonPath, if true, instructs vpython to clear the PYTHONPATH
	// environment variable prior to launch.
	//
	// TODO(iannucci): Delete this once we're satisfied that PYTHONPATH exports
	// are under control.
	ClearPythonPath bool

	// VpythonOptIn, if true, means that users must explicitly chose to enter/stay
	// in the vpython environment when invoking subprocesses. For example, they
	// would need to use sys.executable or 'vpython' for the subprocess.
	//
	// Practically, when this is true, the virtualenv's bin directory will NOT be
	// added to $PATH for the subprocess.
	VpythonOptIn bool
}

Options is the set of options to use to construct and execute a VirtualEnv Python application.

func (*Options) ResolveSpec

func (o *Options) ResolveSpec(c context.Context) (err error)

ResolveSpec resolves the configured environment specification. The resulting spec is installed into o's EnvConfig.Spec field.