5.4. zeekpkg.template module

A module for instantiating different types of Zeek packages.

exception zeekpkg.template.Error

Bases: Exception

Base class for any template-related errors.

class zeekpkg.template.Feature

Bases: _Content

Features overlay additional functionality onto a package.

This class fills in feature-specific functionality but it still abstract. At a minimum, your template's Feature derivative needs to implement contentdir().

name()

A name for this feature. Defaults to its content directory.

exception zeekpkg.template.GitError

Bases: LoadError

There's git trouble while producing template output.

exception zeekpkg.template.InputError

Bases: Error

Something's amiss in the input arguments for a package.

exception zeekpkg.template.LoadError

Bases: Error

Something's going wrong while retrieving a template.

exception zeekpkg.template.OutputError

Bases: Error

Something's going wrong while producing template output.

class zeekpkg.template.Package

Bases: _Content

Template content for a Zeek package.

This class fills in package-specific functionality but it still abstract. At a minimum, your template's Package derivative needs to implement contentdir().

do_instantiate(tmpl, packagedir, use_force=False)

Main driver for instantiating template content.

zkg calls this internally as part of template instantiation. You'll likely want to focus on instantiate() for customization.

Parameters:

  • tmpl (zeekpkg.template.Template) -- template context

  • packagedir (str) -- output folder for the instantiation

  • use_force (bool) -- whether to overwrite/recreate files as needed

class zeekpkg.template.Template(templatedir, api_version, version=None, repo=None)

Bases: object

Base class for any template.

Templates need to derive from this class in their toplevel __init__.py. Instances of this class pull together the components in a given template and capture their parameterization.

api_version()

The template API version string declared in this instance's module.

apply_user_vars(user_vars)

Apply the user variables to this template.

Override this by invoking self.define_param() as needed to create template parameters based on the provided user vars. The relationship of user vars to template parameters is up to you. They can be a 1:1 mapping, you can derive additional parameters from a single user var (e.g. to accommodate string suffixes), or you can use a combination of user vars to define a resulting parameter.

Parameters:

user_vars (list of zeekpkg.uservar.UserVar) -- input values for the template.

define_param(name, val)

Defines a parameter of the given name and value.

define_user_vars()

Defines the full set of user vars supported by this template.

This function defines the complete set of user vars supported by the template content. Instances of zeekpkg.template.Package and zeekpkg.template.Feature declare which of these user vars they require by implementing the needed_user_vars() method, returning the names of those variables.

The default implementation declares no user variables.

Returns:

list of zeekpkg.uservar.Uservar instances

features()

Provides any additional features templates supported.

If the template provides extra features, return each as an instance of zeekpkg.template.Feature instance in a list. By default, a template offers no features.

Returns:

list of zeekpkg.template.Feature instances

has_repo()

Returns True if this template has a git repository, False otherwise.

info()

Returns a dict capturing information about this template

This is usable when rendered as JSON, and also serves as the input for our human-readable template information.

static is_api_compatible(tmpl_ver)

Validate template API compatibility.

Given a semver string describing the API version for which a template was written, verifies that we are compatible with it according to semantic versioning rules:

MAJOR version changes when we make incompatible API changes MINOR version changes when you add backwards-compatible functionality PATCH version changes when you make backwards-compatible bug fixes.

Returns:

bool indicating whether template is comatible.

Raises:

ValueError when given version isn't semver-parseable --

static load(config, template, version=None)

Template loader.

This function instantiates a zeekpkg.template.Template from a template source present either locally on disk or provided as a repo URL.

It first uses the template's __init__.py to bootstrap a module on the fly, then instantiates the zeekpkg.template.Template derivative that must be present in it.

Parameters:

  • config (configparser.ConfigParser) -- a zkg configuration

  • template (str) -- template source repo, as directory or git URL

  • version (str) -- if provided, a specific version tag to use. Ignored when "template" is a local directory. Otherwise, the same logic applies as with packages: the most recent version tag is picked, and if no version tags are available, the default branch.

Returns:

zeekpkg.template.Template derivative

Raises:
lookup_param(name, default='')

Looks up a parameter, falling back to the given default.

name()

A name for this template, derived from the repo URL.

package()

Provides a package template to instantiate.

If the template provides a Zeek package, return a Package instance from this method.

Returns:

zeekpkg.template.Package instance

params()

Returns current str->str template parameter dict.

templatedir()

Returns the path to the template's source tree on disk.

version()

A version string for the template.

This can be a git tag, branch, commit hash, or None if we're using the latest version on the default branch.

version_branch()

Name of the branch the template is on, if any.

Returns branch name if this template version is a branch HEAD, None otherwise (i.e. when it's a specific commit or tag, or we have no repository).

version_sha()

The git commit hash for this template's version.

Returns None when this template got instantiated without a git repo, otherwise a string with the full hash value in ASCII.