spec

Documentation

Overview

Package spec contains implementation for search, parse, normalize vpython spec.

Index

• Constants
• Variables
• func Load(path string, spec *vpython.Spec) error
• func NormalizeSpec(spec *vpython.Spec, tags []*vpython.PEP425Tag) error
• func PEP425Matches(match *vpython.PEP425Tag, tags []*vpython.PEP425Tag) bool
• func PackageMatches(pkg *vpython.Spec_Package, tags []*vpython.PEP425Tag) bool
• func Parse(content string, spec *vpython.Spec) error
• func ResolveSpec(c context.Context, l *Loader, target python.Target, workDir string) (*vpython.Spec, error)
• type Loader
  • func (l *Loader) LoadForScript(c context.Context, path string, isModule bool) (*vpython.Spec, string, error)

Constants

const (
	// DefaultInlineBeginGuard is the default loader InlineBeginGuard value.
	DefaultInlineBeginGuard = "[VPYTHON:BEGIN]"
	// DefaultInlineEndGuard is the default loader InlineEndGuard value.
	DefaultInlineEndGuard = "[VPYTHON:END]"
)

const DefaultPartnerSuffix = ".vpython"

DefaultPartnerSuffix is the default filesystem suffix for a script's partner specification file.

See LoadForScript for more information.

Variables

var DefaultCommonSpecNames = []string{
	"common.vpython",
}

DefaultCommonSpecNames is the name of the "common" specification file.

If a script doesn't explicitly specific a specification file, "vpython" will automatically walk up from the script's directory towards filesystem root and will use the first file named CommonName that it finds. This enables repository-wide and shared environment specifications.

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 Load

func Load(path string, spec *vpython.Spec) error

Load loads an specification file text protobuf from the supplied path.

func NormalizeSpec

func NormalizeSpec(spec *vpython.Spec, tags []*vpython.PEP425Tag) error

NormalizeSpec normalizes the specification Message such that two messages with identical meaning will have identical representation.

If multiple wheel entries exist for the same package name, they must also share a version. If they don't, an error will be returned. Otherwise, they will be merged into a single wheel entry.

NormalizeSpec will prune any Wheel entries that don't match the specified tags, and will remove the match entries from any remaining Wheel entries.

func PEP425Matches

func PEP425Matches(match *vpython.PEP425Tag, tags []*vpython.PEP425Tag) bool

PEP425Matches returns true if match matches at least one of the tags in tags.

A match is determined if the non-zero fields in match equal the equivalent fields in a tag.

func PackageMatches

func PackageMatches(pkg *vpython.Spec_Package, tags []*vpython.PEP425Tag) bool

PackageMatches returns true if the package's match constraints are compatible with tags. A package matches if:

• None of the tags matches any of the "not_match_tag" entries, and
• Every "match_tag" entry matches at least one tag.

As a special case, if the package doesn't specify any match tags, it will always match regardless of the supplied PEP425 tags. This handles the default case where the user specifies no constraints.

See PEP425Matches for information about how tags are matched.

func Parse

func Parse(content string, spec *vpython.Spec) error

Parse loads a specification message from a content string.

func ResolveSpec

func ResolveSpec(c context.Context, l *Loader, target python.Target, workDir string) (*vpython.Spec, error)

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

Types

type Loader

type Loader struct {
	// InlineBeginGuard is a string that signifies the beginning of an inline
	// specification. If empty, DefaultInlineBeginGuard will be used.
	InlineBeginGuard string
	// InlineEndGuard is a string that signifies the end of an inline
	// specification. If empty, DefaultInlineEndGuard will be used.
	InlineEndGuard string

	// CommonFilesystemBarriers is a list of filenames. During common spec, Loader
	// walks directories towards root looking for a file named CommonName. If a
	// directory is observed to contain a file in CommonFilesystemBarriers, the
	// walk will terminate after processing that directory.
	CommonFilesystemBarriers []string

	// CommonSpecNames, if not empty, is the list of common "vpython" spec files
	// to use. If empty, DefaultCommonSpecNames will be used.
	//
	// Names will be considered in the order that they appear.
	CommonSpecNames []string

	// PartnerSuffix is the filesystem suffix for a script's partner spec file. If
	// empty, DefaultPartnerSuffix will be used.
	PartnerSuffix string
}

Loader implements the generic ability to load a "vpython" spec file.

func (*Loader) LoadForScript

func (l *Loader) LoadForScript(c context.Context, path string, isModule bool) (*vpython.Spec, string, error)

LoadForScript attempts to load a spec file for the specified script. If nothing went wrong, a nil error will be returned. If a spec file was identified, it will also be returned along with the path to the spec file itself. Otherwise, a nil spec will be returned.

Spec files can be specified in a variety of ways. This function will look for them in the following order, and return the first one that was identified:

• Partner File
• Inline

Partner File ============

LoadForScript traverses the filesystem to find the specification file that is naturally associated with the specified path.

If the path is a Python script (e.g, "/path/to/test.py"), isModule will be false, and the file will be found at "/path/to/test.py.vpython".

If the path is a Python module (isModule is true), findForScript walks upwards in the directory structure, looking for a file that shares a module directory name and ends with ".vpython". For example, for module:

/path/to/foo/bar/baz/__init__.py
/path/to/foo/bar/__init__.py
/path/to/foo/__init__.py
/path/to/foo.vpython

LoadForScript will first look at "/path/to/foo/bar/baz", then walk upwards until it either hits a directory that doesn't contain an "__init__.py" file, or finds the ES path. In this case, for module "foo.bar.baz", it will identify "/path/to/foo.vpython" as the ES file for that module.

Inline ======

LoadForScript scans through the contents of the file at path and attempts to load specification boundaries.

If the file at path does not exist, or if the file does not contain spec guards, a nil spec will be returned.

The embedded specification is a text protobuf embedded within the file. To parse it, the file is scanned line-by-line for a beginning and ending guard. The content between those guards is minimally processed, then interpreted as a text protobuf.

[VPYTHON:BEGIN]
wheel {
  path: ...
  version: ...
}
[VPYTHON:END]

To allow VPYTHON directives to be embedded in a language-compatible manner (with indentation, comments, etc.), the processor will identify any common characters preceding the BEGIN and END clauses. If they match, those characters will be automatically stripped out of the intermediate lines. This can be used to embed the directives in comments:

// [VPYTHON:BEGIN]
// wheel {
//   path: ...
//   version: ...
// }
// [VPYTHON:END]

In this case, the "// " characters will be removed.

Common ======

LoadForScript will examine successive parent directories starting from the script's location, looking for a file named in CommonSpecNames. If it finds one, it will use that as the specification file. This enables scripts to implicitly share an specification.