5.2. bropkg.package module

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

class bropkg.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
bropkg.package.METADATA_FILENAME = 'bro-pkg.meta'

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

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

Bases: object

A Bro 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 Bro 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 bro-pkg.index containing this package is located. E.g. if the package source has a package named "foo" declared in alice/bro-pkg.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 bro-pkg.index file.

Type:str
metadata

the contents of the package's 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) or just 'bro' to indicate a dependency on a particular bro 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.

matches_path(path)

Return whether this package has a matching path/name.

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

name_with_source_directory()

Return the package's within its package source.

E.g. for a package source with a package named "foo" in alice/bro-pkg.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 bropkg.package.PackageInfo(package=None, status=None, metadata=None, versions=None, metadata_version='', invalid_reason='', version_type='', metadata_file=None)

Bases: object

Contains information on an arbitrary package.

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

package

the relevant Bro package

Type:Package
status

this attribute is set for installed packages

Type:PackageStatus
metadata

the contents of the package's bro-pkg.meta file

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 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 'master' branch.

dependencies(field='depends')

Returns a dictionary of dependency -> version strings.

The keys indicate the name of a package (shorthand name or full git URL) or just 'bro' to indicate a dependency on a particular bro 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.

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 (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 bropkg.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", or "commit" to indicate (respectively) whether package upgrades should stick to a git branch, use git version tags, or do nothing because the package is to always use a specific git commit hash.

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
bropkg.package.aliases(metadata_dict)

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

bropkg.package.canonical_url(path)

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

bropkg.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) or just 'bro' to indicate a dependency on a particular bro 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.

bropkg.package.name_from_path(path)

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

bropkg.package.short_description(metadata_dict)

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

bropkg.package.tags(metadata_dict)

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

bropkg.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, 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.