5.2. zeekpkg.package module

A module with various data structures used for interacting with and querying the properties and status of Zeek packages.

class zeekpkg.package.InstalledPackage(package, status)

Bases: object

An installed package and its current status.

package

the installed package

Type:

Package

status

the status of the installed package

Type:

PackageStatus

fullfills(version_spec)

Does the current version fullfill version_spec?

is_builtin()
zeekpkg.package.METADATA_FILENAME = 'zkg.meta'

The name of files used by packages to store their metadata.

class zeekpkg.package.Package(git_url, source='', directory='', metadata=None, name=None, canonical=False)

Bases: object

A Zeek package.

This class contains properties of a package that are defined by the package git repository itself and the package source it came from.

git_url

the git URL which uniquely identifies where the Zeek package is located

Type:

str

name

the canonical name of the package, which is always the last component of the git URL path

Type:

str

source

the package source this package comes from, which may be empty if the package is not a part of a source (i.e. the user is referring directly to the package's git URL).

Type:

str

directory

the directory within the package source where the zkg.index containing this package is located. E.g. if the package source has a package named "foo" declared in alice/zkg.index, then dir is equal to "alice". It may also be empty if the package is not part of a package source or if it's located in a top-level zkg.index file.

Type:

str

metadata

the contents of the package's zkg.meta or bro-pkg.meta file. If the package has not been installed then this information may come from the last aggregation of the source's aggregate.meta file (it may not be accurate/up-to-date).

Type:

dict of str -> str

aliases()

Return a list of package name aliases.

The canonical one is listed first.

dependencies(field='depends')

Returns a dictionary of dependency -> version strings.

The keys indicate the name of a package (shorthand name or full git URL). The names 'zeek' or 'zkg' may also be keys that indicate a dependency on a particular Zeek or zkg version.

The values indicate a semantic version requirement.

If the dependency field is malformed (e.g. number of keys not equal to number of values), then None is returned.

is_builtin()
matches_path(path)

Return whether this package has a matching path/name.

E.g for a package with qualified_name() of "zeek/alice/foo", the following inputs will match: "foo", "alice/foo", "zeek/alice/foo"

name_with_source_directory()

Return the package's name within its package source.

E.g. for a package source with a package named "foo" in alice/zkg.index, this method returns "alice/foo". If the package has no source or sub-directory within the source, then just the package name is returned.

qualified_name()

Return the shortest name that qualifies/distinguishes the package.

If the package is part of a source, then this returns "source_name/name_with_source_directory()", else the package's git URL is returned.

short_description()

Return a short description of the package.

This will be the first sentence of the package's 'description' field and may return results from the source's aggregated metadata if the package has not been installed yet.

tags()

Return a list of keyword tags associated with the package.

This will be the contents of the package's tags field and may return results from the source's aggregated metadata if the package has not been installed yet.

user_vars()

Returns a list of (str, str, str) from metadata's 'user_vars' field.

Each entry in the returned list is a the name of a variable, it's value, and its description.

If the 'user_vars' field is not present, an empty list is returned. If it is malformed, then None is returned.

class zeekpkg.package.PackageInfo(package=None, status=None, metadata=None, versions=None, metadata_version='', invalid_reason='', version_type='', metadata_file=None, default_branch=None)

Bases: object

Contains information on an arbitrary package.

If the package is installed, then its status is also available.

package

the relevant Zeek package

Type:

Package

status

this attribute is set for installed packages

Type:

PackageStatus

metadata

the contents of the package's zkg.meta or bro-pkg.meta

Type:

dict of str -> str

versions

a list of the package's availabe git version tags

Type:

list of str

metadata_version

the package version that the metadata is from

version_type

either 'version', 'branch', or 'commit' to indicate whether the package info/metadata was taken from a release version tag, a branch, or a specific commit hash.

invalid_reason

this attribute is set when there is a problem with gathering package information and explains what went wrong.

Type:

str

metadata_file

the absolute path to the zkg.meta or bro-pkg.meta for this package. Use this if you'd like to parse the metadata yourself. May not be defined, in which case the value is None.

aliases()

Return a list of package name aliases.

The canonical one is listed first.

best_version()

Returns the best/latest version of the package that is available.

If the package has any git release tags, this returns the highest one, else it returns the default branch like 'main' or 'master'.

dependencies(field='depends')

Returns a dictionary of dependency -> version strings.

The keys indicate the name of a package (shorthand name or full git URL). The names 'zeek' or 'zkg' may also be keys that indicate a dependency on a particular Zeek or zkg version.

The values indicate a semantic version requirement.

If the dependency field is malformed (e.g. number of keys not equal to number of values), then None is returned.

is_builtin()
short_description()

Return a short description of the package.

This will be the first sentence of the package's 'description' field.

tags()

Return a list of keyword tags associated with the package.

This will be the contents of the package's tags field.

user_vars()

Returns a list of user variables parsed from metadata's 'user_vars' field.

If the 'user_vars' field is not present, an empty list is returned. If it is malformed, then None is returned.

Returns:

list of zeekpkg.uservar.UserVar, or None on error

class zeekpkg.package.PackageStatus(is_loaded=False, is_pinned=False, is_outdated=False, tracking_method=None, current_version=None, current_hash=None)

Bases: object

The status of an installed package.

This class contains properties of a package related to how the package manager will operate on it.

is_loaded

whether a package is marked as "loaded".

Type:

bool

is_pinned

whether a package is allowed to be upgraded.

Type:

bool

is_outdated

whether a newer version of the package exists.

Type:

bool

tracking_method

either "branch", "version", "commit", or "builtin" to indicate (respectively) whether package upgrades should stick to a git branch, use git version tags, do nothing because the package is to always use a specific git commit hash, or do nothing because the package is built into Zeek.

Type:

str

current_version

the current version of the installed package, which is either a git branch name or a git version tag.

Type:

str

current_hash

the git sha1 hash associated with installed package's current version/commit.

Type:

str

class zeekpkg.package.PackageVersion(method, version)

Bases: object

Helper class to compare package versions with version specs.

fullfills(version_spec)

Whether this package version fullfills the given version_spec.

Returns:

(some message, bool)

zeekpkg.package.aliases(metadata_dict)

Return a list of package aliases found in metadata's 'aliases' field.

zeekpkg.package.canonical_url(path)

Returns the url of a package given a path to its git repo.

zeekpkg.package.dependencies(metadata_dict, field='depends')

Returns a dictionary of (str, str) based on metadata's dependency field.

The keys indicate the name of a package (shorthand name or full git URL). The names 'zeek' or 'zkg' may also be keys that indicate a dependency on a particular Zeek or zkg version.

The values indicate a semantic version requirement.

If the dependency field is malformed (e.g. number of keys not equal to number of values), then None is returned.

zeekpkg.package.is_valid_name(name)

Returns True if name is a valid package name, else False.

zeekpkg.package.make_builtin_package(*, name: str, current_version: str, current_hash: str = None)

Given name, version and commit as found in Zeek's zkg.provides entry, construct a PackageInfo instance representing the built-in package.

zeekpkg.package.name_from_path(path)

Returns the name of a package given a path to its git repository.

zeekpkg.package.short_description(metadata_dict)

Returns the first sentence of the metadata's 'desciption' field.

zeekpkg.package.tags(metadata_dict)

Return a list of tag strings found in the metadata's 'tags' field.

zeekpkg.package.user_vars(metadata_dict)

Returns a list of (str, str, str) from metadata's 'user_vars' field.

Each entry in the returned list is a the name of a variable, its value, and its description.

If the 'user_vars' field is not present, an empty list is returned. If it is malformed, then None is returned.