luci: go.chromium.org/luci/vpython/spec Index | Files

package spec

import "go.chromium.org/luci/vpython/spec"

Index

Package Files

env.go load.go match.go spec.go

Constants

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

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

See LoadForScript for more information.

Variables

var DefaultCommonSpecNames = []string{
    "common" + Suffix,
}

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.

func Hash Uses

func Hash(spec *vpython.Spec, rt *vpython.Runtime, extra ...string) string

Hash hashes the contents of the supplied "spec" and "rt" and returns the result as a hex-encoded string.

If not empty, the contents of extra are prefixed to hash string. This can be used to factor additional influences into the spec hash.

func Load Uses

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

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

func LoadEnvironment Uses

func LoadEnvironment(path string, environment *vpython.Environment) error

LoadEnvironment loads an environment file text protobuf from the supplied path.

func NormalizeEnvironment Uses

func NormalizeEnvironment(env *vpython.Environment) error

NormalizeEnvironment normalizes the supplied Environment such that two messages with identical meaning will have identical representation.

func NormalizeSpec Uses

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 Uses

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 Uses

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 deafult case where the user specifies no constraints.

See PEP425Matches for information about how tags are matched.

func Parse Uses

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

Parse loads a specification message from a content string.

func ParseEnvironment Uses

func ParseEnvironment(content string, environment *vpython.Environment) error

ParseEnvironment loads a environment protobuf message from a content string.

func Render Uses

func Render(spec *vpython.Spec) string

Render creates a human-readable string from spec.

type Loader Uses

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
}

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

func (*Loader) LoadForScript Uses

func (l *Loader) LoadForScript(c context.Context, path string, isModule bool) (*vpython.Spec, 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. 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.

Package spec imports 17 packages (graph) and is imported by 9 packages. Updated 2018-10-23. Refresh now. Tools for package owners.