Documentation
¶
Index ¶
- Constants
- Variables
- func Hash(spec *vpython.Spec, rt *vpython.Runtime, extra ...string) string
- func Load(path string, spec *vpython.Spec) error
- func LoadEnvironment(path string, environment *vpython.Environment) error
- func NormalizeEnvironment(env *vpython.Environment) 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 ParseEnvironment(content string, environment *vpython.Environment) error
- func Render(spec *vpython.Spec) string
- type Loader
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.
Functions ¶
func Hash ¶
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 LoadEnvironment ¶
func LoadEnvironment(path string, environment *vpython.Environment) error
LoadEnvironment loads an environment file text protobuf from the supplied path.
func NormalizeEnvironment ¶
func NormalizeEnvironment(env *vpython.Environment) error
NormalizeEnvironment normalizes the supplied Environment such that two messages with identical meaning will have identical representation.
func NormalizeSpec ¶
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 ¶
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 ParseEnvironment ¶
func ParseEnvironment(content string, environment *vpython.Environment) error
ParseEnvironment loads a environment protobuf message from a content string.
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.
Source Files