python

Documentation

Index

• func IsolateEnvironment(e *environ.Env, keepPythonPath bool)
• type CommandLine
  • func ParseCommandLine(args []string) (*CommandLine, error)
  • func (cl *CommandLine) AddFlag(flag CommandLineFlag)
  • func (cl *CommandLine) AddSingleFlag(flag string)
  • func (cl *CommandLine) BuildArgs() []string
  • func (cl *CommandLine) Clone() *CommandLine
  • func (cl *CommandLine) RemoveAllFlag(flag string) (found bool)
  • func (cl *CommandLine) RemoveFlag(flag CommandLineFlag) (found bool)
  • func (cl *CommandLine) RemoveFlagMatch(matchFn func(CommandLineFlag) bool) (found bool)
• type CommandLineFlag
  • func (f *CommandLineFlag) String() string
• type CommandTarget
• type Interpreter
  • func Find(c context.Context, vers Version, lookPath LookPathFunc) (*Interpreter, error)
  • func (i *Interpreter) GetVersion(c context.Context) (v Version, err error)
  • func (i *Interpreter) MkIsolatedCommand(c context.Context, target Target, args ...string) IsolatedCommand
  • func (i *Interpreter) Normalize() error
• type IsolatedCommand
  • func (iso IsolatedCommand) Cleanup()
• type LookPathFilter
• type LookPathFunc
• type LookPathResult
• type ModuleTarget
• type NoTarget
• type ScriptTarget
• type Target
• type Version
  • func ParseVersion(s string) (Version, error)
  • func (v *Version) IsSatisfiedBy(other Version) bool
  • func (v *Version) IsZero() bool
  • func (v *Version) Less(other *Version) bool
  • func (v *Version) PythonBase() string
  • func (v Version) String() string

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