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.
- status
the status of the installed package
- Type:
- 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 inalice/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-levelzkg.index
file.- Type:
str
- metadata
the contents of the package's
zkg.meta
orbro-pkg.meta
file. If the package has not been installed then this information may come from the last aggregation of the source'saggregate.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.
- status
this attribute is set for installed packages
- Type:
- metadata
the contents of the package's
zkg.meta
orbro-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
orbro-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
andcommit
as found in Zeek'szkg.provides
entry, construct aPackageInfo
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.