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

Package – the installed package

status

PackageStatus – the status of the installed package

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)

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

str – the git URL which uniquely identifies where the Bro package is located

name

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

source

str – 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).

directory

str – 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.

metadata

dict of str -> str – 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).

dependencies()

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.

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.

class bropkg.package.PackageInfo(package=None, status=None, metadata=None, versions=None, metadata_version='', invalid_reason='')

Bases: object

Contains information on an arbitrary package.

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

package

Package – the relevant Bro package

status

PackageStatus – this attribute is set for installed packages

metadata

dict of str -> str – the contents of the package’s bro-pkg.meta file

versions

list of str – a list of the package’s availabe git version tags

metadata_version

the package version that the metadata is from

invalid_reason

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

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()

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.

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.

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

bool – whether a package is marked as “loaded”.

is_pinned

bool – whether a package is allowed to be upgraded.

is_outdated

bool – whether a newer version of the package exists.

tracking_method

str – either “branch” or “version” to indicate whether package upgrades should stick to a git branch or use git version tags.

current_version

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

current_hash

str – the git sha1 hash associated with installed package’s current version/commit.

bropkg.package.canonical_url(path)

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

bropkg.package.dependencies(metadata_dict)

Returns a dictionary of (str, str) based on metadata’s ‘depends’ 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.

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.