View Source
const EnvironmentVersion = "v4"

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


    View Source
    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.


      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>/" 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.


              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.


                                      Path Synopsis
                                      Package assets is generated by
                                      Package assets is generated by