Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func IsolateEnvironment

func IsolateEnvironment(e *environ.Env, keepPythonPath bool)

    IsolateEnvironment mutates e to remove any environmental influence over the Python interpreter.

    If keepPythonPath is true, PYTHONPATH will not be cleared. This is used by the actual VirtualEnv Python invocation to preserve PYTHONPATH since it is a form of user input.

    If e is nil, no operation will be performed.

    Types

    type CommandLine

    type CommandLine struct {
    	// Target is the Python target type.
    	Target Target
    
    	// Flags are flags to the Python interpreter.
    	Flags []CommandLineFlag
    	// FlagSeparator, if true, means that a "--" flag separator, which separates
    	// the interpreter's flags from its positional arguments, was found.
    	FlagSeparator bool
    	// Args are arguments passed to the Python script.
    	Args []string
    }

      CommandLine is a parsed Python command-line.

      CommandLine can be parsed from arguments via ParseCommandLine.

      func ParseCommandLine

      func ParseCommandLine(args []string) (*CommandLine, error)

        ParseCommandLine parses Python command-line arguments and returns a structured representation.

        func (*CommandLine) AddFlag

        func (cl *CommandLine) AddFlag(flag CommandLineFlag)

          AddFlag adds an interpreter flag to cl if it's not already present.

          func (*CommandLine) AddSingleFlag

          func (cl *CommandLine) AddSingleFlag(flag string)

            AddSingleFlag adds a single no-argument interpreter flag to cl if it's not already specified.

            func (*CommandLine) BuildArgs

            func (cl *CommandLine) BuildArgs() []string

              BuildArgs returns an array of Python interpreter arguments for cl.

              func (*CommandLine) Clone

              func (cl *CommandLine) Clone() *CommandLine

                Clone returns an independent deep copy of cl.

                func (*CommandLine) RemoveAllFlag

                func (cl *CommandLine) RemoveAllFlag(flag string) (found bool)

                  RemoveAllFlag removes all instances of the specified flag from the interpreter command line.

                  func (*CommandLine) RemoveFlag

                  func (cl *CommandLine) RemoveFlag(flag CommandLineFlag) (found bool)

                    RemoveFlag removes all instances of the specified flag from the interpreter command line.

                    func (*CommandLine) RemoveFlagMatch

                    func (cl *CommandLine) RemoveFlagMatch(matchFn func(CommandLineFlag) bool) (found bool)

                      RemoveFlagMatch removes all instances of flags that match the selection function.

                      matchFn is a function that accepts a candidate flag and returns true if it should be removed, false if it should not.

                      type CommandLineFlag

                      type CommandLineFlag struct {
                      	Flag string
                      	Arg  string
                      }

                        CommandLineFlag is a command-line flag and its associated argument, if one is provided.

                        func (*CommandLineFlag) String

                        func (f *CommandLineFlag) String() string

                          String returns a string representation of this flag, which is a command-line suitable representation of its value.

                          type CommandTarget

                          type CommandTarget struct {
                          	// Command is the command contents.
                          	Command string
                          }

                            CommandTarget is a Target implementation for a command-line string (-c ...).

                            type Interpreter

                            type Interpreter struct {
                            	// Python is the path to the system Python interpreter.
                            	Python string
                            	// contains filtered or unexported fields
                            }

                              Interpreter represents a system Python interpreter. It exposes the ability to use common functionality of that interpreter.

                              func Find

                              func Find(c context.Context, vers Version, lookPath LookPathFunc) (*Interpreter, error)

                                Find attempts to find a Python interpreter matching the supplied version using PATH.

                                In order to accommodate multiple configurations on operating systems, Find will attempt to identify versions that appear on the path

                                func (*Interpreter) GetVersion

                                func (i *Interpreter) GetVersion(c context.Context) (v Version, err error)

                                  GetVersion runs the specified Python interpreter to extract its version from `platform.python_version` and maps it to a known specification version.

                                  func (*Interpreter) MkIsolatedCommand

                                  func (i *Interpreter) MkIsolatedCommand(c context.Context, target Target, args ...string) IsolatedCommand

                                    MkIsolatedCommand returns a configurable exec.Cmd structure bound to this Interpreter.

                                    The supplied arguments have several Python isolation flags prepended to them to remove environmental factors such as:

                                    - The user's "site.py".
                                    - The current PYTHONPATH environment variable.
                                    - The current working directory (i.e. avoids `import foo` picking up local
                                      foo.py)
                                    - Compiled ".pyc/.pyo" files.
                                    

                                    The caller MUST call IsolatedCommand.Cleanup when they no longer need the IsolatedCommand.

                                    func (*Interpreter) Normalize

                                    func (i *Interpreter) Normalize() error

                                      Normalize normalizes the Interpreter configuration by resolving relative paths into absolute paths.

                                      type IsolatedCommand

                                      type IsolatedCommand struct {
                                      	*exec.Cmd
                                      	// contains filtered or unexported fields
                                      }

                                        IsolatedCommand has an *exec.Cmd, as well as the temporary directory created for this Cmd.

                                        func (IsolatedCommand) Cleanup

                                        func (iso IsolatedCommand) Cleanup()

                                          Cleanup must be called after the IsolatedCommand is no longer needed.

                                          type LookPathFilter

                                          type LookPathFilter func(c context.Context, i *Interpreter) error

                                            LookPathFilter is given a candidate python interpreter, and returns nil if that interpreter passes the filter, and an error explaining why it failed otherwise

                                            type LookPathFunc

                                            type LookPathFunc func(c context.Context, target string, filter LookPathFilter) (*LookPathResult, error)

                                              LookPathFunc attempts to find a file identified by "target", similar to exec.LookPath.

                                              "target" will be the name of the program being looked up. It will NOT be a path, relative or absolute. It also should not include an extension where otherwise applicable (e.g., "python" instead of "python.exe"); the lookup function is responsible for trying known extensions as part of the lookup.

                                              A nil LookPathFunc will use exec.LookPath.

                                              type LookPathResult

                                              type LookPathResult struct {
                                              	// Path, if not zero, is the absolute path to the identified target
                                              	// executable.
                                              	Path string
                                              
                                              	// Version, if not zero, is the Python version string. The most common (only?)
                                              	// LookPathFunc implementation (in go.chromium.org/luci/vpython/application/probe.go)
                                              	// calls the candidate Python to determine its version, and then stashes the
                                              	// result here to void redundant lookups if this LookPathResult ends up being
                                              	// selected.
                                              	Version Version
                                              }

                                                LookPathResult is the result of LookPathFunc.

                                                type ModuleTarget

                                                type ModuleTarget struct {
                                                	// Module is the name of the target module.
                                                	Module string
                                                }

                                                  ModuleTarget is a Target implementing indicating a Python module (-m ...).

                                                  type NoTarget

                                                  type NoTarget struct{}

                                                    NoTarget is a Target implementation indicating no Python target (i.e., interactive).

                                                    type ScriptTarget

                                                    type ScriptTarget struct {
                                                    	// Path is the path to the script that is being invoked.
                                                    	//
                                                    	// This may be "-", indicating that the script is being read from STDIN.
                                                    	Path string
                                                    	// FollowsSeparator is true if the script argument follows the flag separator.
                                                    	FollowsSeparator bool
                                                    }

                                                      ScriptTarget is a Python executable script target.

                                                      type Target

                                                      type Target interface {
                                                      	// contains filtered or unexported methods
                                                      }

                                                        Target describes a Python invocation target.

                                                        Targets are identified by parsing a Python command-line using ParseCommandLine.

                                                        A Target is identified through type assertion, and will be one of:

                                                        - NoTarget
                                                        - ScriptTarget
                                                        - CommandTarget
                                                        - ModuleTarget
                                                        

                                                        type Version

                                                        type Version struct {
                                                        	Major int
                                                        	Minor int
                                                        	Patch int
                                                        }

                                                          Version is a Python interpreter version.

                                                          It is a simplified version of the Python interpreter version scheme defined in PEP 440: https://www.python.org/dev/peps/pep-0440/

                                                          Notably, it extracts the major, minor, and patch values out of the version.

                                                          func ParseVersion

                                                          func ParseVersion(s string) (Version, error)

                                                            ParseVersion parses a Python version from a version string (e.g., "1.2.3").

                                                            func (*Version) IsSatisfiedBy

                                                            func (v *Version) IsSatisfiedBy(other Version) bool

                                                              IsSatisfiedBy returns true if "other" is a suitable match for this version. A suitable match:

                                                              - MUST have a Major version.
                                                              - If v is zero, other is automatically suitable.
                                                              - If v is non-zero, other must have the same Major version as v, and a
                                                                minor/patch version that is >= v's.
                                                              

                                                              func (*Version) IsZero

                                                              func (v *Version) IsZero() bool

                                                                IsZero returns true if the Version is empty. This is true if the Major field, which must be set, is empty.

                                                                func (*Version) Less

                                                                func (v *Version) Less(other *Version) bool

                                                                  Less returns true if "v"'s Version semantically precedes "other".

                                                                  func (*Version) PythonBase

                                                                  func (v *Version) PythonBase() string

                                                                    PythonBase returns the base Python interpreter name for this version.

                                                                    func (Version) String

                                                                    func (v Version) String() string