venv

Documentation

Index

• Constants
• Variables
• func Delete(c context.Context, cfg Config) error
• func EnvRootFromStampPath(path string) (string, error)
• func StripVirtualEnvPaths(env environ.Env) (ret environ.Env, pruned []string)
• func With(c context.Context, cfg Config, fn func(context.Context, *Env) error) error
• type Config
  • func (cfg *Config) HasWheels() bool
  • func (cfg *Config) Prune(c context.Context) error
  • func (cfg *Config) WithoutWheels() *Config
• type Env
  • func (e *Env) AssertCompleteAndLoad() error
  • func (e *Env) Delete(c context.Context) error
  • func (e *Env) Interpreter() *python.Interpreter
  • func (e *Env) WriteEnvironmentStamp() error
• type Iterator
  • func (it *Iterator) ForEach(c context.Context, cfg *Config, cb func(context.Context, *Env) error) error
• type PackageLoader

Constants

const EnvironmentVersion = "v4"

EnvironmentVersion is an environment version string. It must advance each time the layout of a VirtualEnv environment changes.

Variables

var ErrNotComplete = errors.New("environment is not complete")

ErrNotComplete is a sentinel error returned by AssertCompleteAndLoad to indicate that the Environment is missing its completion flag.

Functions

func Delete

func Delete(c context.Context, cfg Config) error

Delete removes all resources consumed by an environment.

Delete will acquire an exclusive lock on the environment and assert that it is not in use prior to deletion. This is non-blocking, and an error will be returned if the lock could not be acquired.

If deletion fails, a wrapped error will be returned.

func EnvRootFromStampPath

func EnvRootFromStampPath(path string) (string, error)

EnvRootFromStampPath calculates the environment root from an exported environment specification file path.

The specification path is: <EnvRoot>/<SpecHash>/EnvironmentStampPath, so our EnvRoot is two directories up.

We export EnvSpecPath as an asbolute path. However, since someone else could have overridden it or exported their own, let's make sure.

func StripVirtualEnvPaths

func StripVirtualEnvPaths(env environ.Env) (ret environ.Env, pruned []string)

StripVirtualEnvPaths looks for all $PATH elements which are the `BinDir` of a VirtualEnv deployment (created by VPython or not), and removes them. These directories contain a `python` interpreter and various scripts (like activate).

This uses VirtualEnv's "<BinDir>/activate_this.py" file to identify VirtualEnvs, which is installed by all known versions of VirtualEnv.

This returns a modified copy of env and a list of pruned paths (if any).

func With

func With(c context.Context, cfg Config, fn func(context.Context, *Env) error) error

With creates a new Env and executes "fn" with assumed ownership of that Env.

The Context passed to "fn" will be cancelled if we lose perceived ownership of the configured environment. This is not an expected scenario, and should be considered an error condition. The Env passed to "fn" is valid only for the duration of the callback.

It will lock around the VirtualEnv to ensure that multiple processes do not conflict with each other. If a VirtualEnv for this specification already exists, it will be used directly without any additional setup.

If another process holds the lock, With will return an error if cfg.FailIfLocked is true, or try again until it obtains the lock otherwise.

Types

type Config

type Config struct {
	// MaxHashLen is the maximum number of hash characters to use in VirtualEnv
	// directory names.
	MaxHashLen int

	// BaseDir is the parent directory of all VirtualEnv.
	BaseDir string

	// SetupEnv if not nil, is the base environment that will be used during
	// VirtualEnv setup operations.
	SetupEnv environ.Env

	// OverrideName overrides the name of the specified VirtualEnv.
	//
	// Because the name is no longer derived from the specification, this will
	// force revalidation and deletion of any existing content if it is not a
	// fully defined and matching VirtualEnv
	OverrideName string

	// Package is the VirtualEnv package to install. It must be non-nil and
	// valid. It will be used if the environment specification doesn't supply an
	// overriding one.
	Package vpython.Spec_Package

	// Python is the Python interpreter to use. If empty, one will be resolved
	// based on the Spec and the current PATH.
	Python string

	// LookPathFunc, if not nil, will be used instead of exec.LookPath to find the
	// underlying Python interpreter.
	LookPathFunc python.LookPathFunc

	// Spec is the specification file to use to construct the VirtualEnv. If
	// nil, or if fields are missing, they will be filled in by probing the system
	// PATH.
	Spec *vpython.Spec

	// PruneThreshold, if >0, is the maximum age of a VirtualEnv before it should
	// be pruned. If <= 0, there is no maximum age, so no pruning will be
	// performed.
	PruneThreshold time.Duration
	// MaxPrunesPerSweep applies a limit to the number of items to prune per
	// execution.
	//
	// If <= 0, no limit will be applied.
	MaxPrunesPerSweep int

	// Loader is the PackageLoader instance to use for package resolution and
	// deployment.
	Loader PackageLoader

	// FailIfLocked, if true, means that if a lock is encountered during
	// VirtualEnv operation, the VirtualEnv will exit immediately with an error.
	// If false, the VirtualEnv will block pending the lock's availability.
	FailIfLocked bool
	// contains filtered or unexported fields
}

Config is the configuration for a managed VirtualEnv.

A VirtualEnv is specified based on its resolved vpython.Spec.

func (*Config) HasWheels

func (cfg *Config) HasWheels() bool

HasWheels returns true if this environment declares wheel dependencies.

func (*Config) Prune

func (cfg *Config) Prune(c context.Context) error

Prune performs a pruning round on the environment set described by this Config.

func (*Config) WithoutWheels

func (cfg *Config) WithoutWheels() *Config

WithoutWheels returns a clone of cfg that depends on no additional packages.

If cfg is already an empty it will be returned directly.

type Env

type Env struct {
	// Config is this Env's Config, fully-resolved.
	Config *Config

	// Root is the Env container's root directory path.
	Root string

	// Name is the hash of the specification file for this Env.
	Name string

	// Python is the path to the Env Python interpreter.
	Python string

	// Environment is the resolved Python environment that this VirtualEnv is
	// configured with. It is resolved during environment setup and saved into the
	// environment's EnvironmentStampPath.
	Environment *vpython.Environment

	// BinDir is the VirtualEnv "bin" directory, containing Python and installed
	// wheel binaries.
	BinDir string

	// EnvironmentStampPath is the path to the vpython.Environment stamp file that
	// details a constructed environment. It will be in text protobuf format, and,
	// therefore, suitable for input to other "vpython" invocations.
	EnvironmentStampPath string

	// LockHandle is the active lock handle for the current VirtualEnv lock.
	// Only read-only operations should be performed on the handle.
	LockHandle fslock.Handle
	// contains filtered or unexported fields
}

Env is a fully set-up Python virtual environment. It is configured based on the contents of an vpython.Spec file by Setup.

Env should not be instantiated directly; it must be created by calling Config.Env.

All paths in Env are absolute.

func (*Env) AssertCompleteAndLoad

func (e *Env) AssertCompleteAndLoad() error

AssertCompleteAndLoad asserts that the VirtualEnv's completion flag exists. If it does, the environment's stamp is loaded into e.Environment and nil is returned.

An error is returned if the completion flag does not exist, or if the VirtualEnv environment stamp could not be loaded.

func (*Env) Delete

func (e *Env) Delete(c context.Context) error

Delete removes all resources consumed by an environment.

Delete will acquire an exclusive lock on the environment and assert that it is not in use prior to deletion. This is non-blocking, and an error will be returned if the lock could not be acquired.

If the environment was not deleted, a non-nil wrapped error will be returned. If the deletion failed because the lock was held, a wrapped fslock.ErrLockHeld will be returned.

func (*Env) Interpreter

func (e *Env) Interpreter() *python.Interpreter

Interpreter returns the VirtualEnv's isolated Python Interpreter instance.

func (*Env) WriteEnvironmentStamp

func (e *Env) WriteEnvironmentStamp() error

WriteEnvironmentStamp writes a text protobuf form of spec to path.

type Iterator

type Iterator struct {
	// Only return VirtualEnv entries with completion flags.
	OnlyComplete bool

	// Shuffle VirtualEnv results before returning them.
	Shuffle bool
}

Iterator iterates over the contents of a "vpython" configuration directory, returning all associated VirtualEnv instances.

func (*Iterator) ForEach

func (it *Iterator) ForEach(c context.Context, cfg *Config, cb func(context.Context, *Env) error) error

ForEach iterates over all VirtualEnv installations for the supplied "cfg".

"cb" will be invoked for each VirtualEnv, regardless of its completion status. The callback may perform additional operations on the VirtualEnv to determine its actual status. If the callback returns an error, iteration will stop and the error will be forwarded.

If the supplied Context is cancelled, iteration will stop prematurely and return the Context's error.

type PackageLoader

type PackageLoader interface {
	// Resolve processes the packages defined in e, updating their fields to their
	// resolved values. Resolved packages must fully specify the package instance
	// that is being deployed, and will be used when determining the environment's
	// fingerprint (used for locking and naming).
	Resolve(c context.Context, e *vpython.Environment) error

	// Ensure installs the supplied packages into root.
	//
	// The packages will have been previously resolved via Resolve.
	Ensure(c context.Context, root string, packages []*vpython.Spec_Package) error

	// Verify verifies that all listed packages can be sufficiently resolved
	// for each supplied PEP425 tag.
	//
	// "spec" may be mutated during verification.
	Verify(c context.Context, spec *vpython.Spec, tags []*vpython.PEP425Tag) error
}

PackageLoader loads package information from a specification file's Package message onto the local system.

The PackageLoader instance is responsible for managing any caching, configuration, or setup required to operate.