Documentation

Index

Constants

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

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

    See LoadForScript for more information.

    Variables

    View Source
    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

      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

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

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

          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

              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 ParseEnvironment

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

                        ParseEnvironment loads a environment protobuf message from a content string.

                        func Render

                        func Render(spec *vpython.Spec) string

                          Render creates a human-readable string from spec.

                          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.