emodpy.bamboo_api_utils module#

emodpy.bamboo_api_utils.bamboo_connection()[source]#
class emodpy.bamboo_api_utils.BambooConnection[source]#

Bases: object

Bamboo API config and basic functionality/connectivity wrapper.

Automatically probes the most likely endpoint locations (with and without https, with and without port numbers).

Important functions:

  • login: logs into the bamboo api, caches the login token so you don’t have to pass creds for every req. in a session

  • get_bamboo_api_url: translate a relative API URL into a fully qualified URL

  • normalize_url: detect whether a URL is relative or not, translate relative URLs to fully qualified ones

  • make_get_request: makes a request to the specified API url, adds some convenient error and login handling

  • download_file: downloads a file from the specified artifacts url to a location on disk

property server: str#

str: Keeps track of a single instance of the server base url. (e.g. http://idm-bamboo:8085)

str: Automatically load and instance the login session cookie jar.

get_server_url(ssl: bool = True, useport: bool = False) → str[source]#

Get a particular variant of the server url w/ or w/o ssl and port (e.g. False/False -> http://idm-bamboo)

Parameters:

  • ssl (bool) – whether to use ssl, default to using ssl

  • useport (bool) – whether to use the port, default to not use port

Returns:

endpoint url

Return type:

str

find_server() → str[source]#

Explore all possible server urls, return the first one found to exist.

Returns:

server url

Return type:

str

url_exists(url: str) → bool[source]#

Try a simple get request given an endpoint url, return whether it was successful (code 200).

Parameters:

url (str) – url to issue a test request to

Returns:

whether or not a request to the url succeeds (w/ status 200)

Return type:

bool

File where bamboo session cookie is stored.

Returns:

fully qualified file path of session cookie file

Return type:

str

Load api login session cookies from disk.

Returns:

session cookie jar

Return type:

requests.cookies

Write post-login cookies for session to disk.

get_bamboo_url(relative_url: str) → str[source]#

Add bamboo server, port, and protocol to bamboo url.

Parameters:

relative_url (str) – relative url (artifact link or api url)

Returns:

fully qualified url

Return type:

str

get_bamboo_api_url(relative_url: str, json: bool = False, params: dict = {}) → str[source]#

Get fully qualified bamboo api url from a relative url w/ given json mode and appending all parameters.

Parameters:

  • relative_url (str) – api url (e.g. project/<project-key>)

  • json (bool) – whether to get results in json format (otherwise, default is xml)

  • params (dict) – name/value dictionary of query parameters

Returns:

fully qualified url that a request can be issued against

Return type:

str

save_credentials(username: str, password: str)[source]#

Save bamboo api login credentials using keyring.

Parameters:
ensure_logged_in()[source]#

Check if a login session exists using saved cookies, if not login using keyring stored creds.

login_session_exists() → bool[source]#

Test whether an existing session cookie exists and an active login session exists.

Returns:

whether an active login session exists

Return type:

bool

login(username: str | None = None, password=None) → bool[source]#

Login to the bamboo api. If username or password are not provided, use stored credentials from keyring.

Parameters:
Returns:

success/failure

Return type:

bool

normalize_url(url: str) → str[source]#

Determine whether a url is relative or fully qualified, translate relative urls to fully qualified versions.

Parameters:

url (str) – relative or fully qualified url

Returns:

fully qualified url

Return type:

str

make_get_request(url: str, retries: int = 3) → Response[source]#

Make a get request against the bamboo server.

Parameters:

url (str) – relative or fully qualified url

Returns:

request object returned from requests.get()

Return type:

requests.Response

make_api_get_request(relative_url: str, json: bool = False, params: dict = {}) → Response[source]#

Translate relative api url to the fully qualified bamboo api url, make a get request against it.

Parameters:

  • relative_url (str) – url relative to the bamboo api endpoint (e.g. ‘result/MYPROJ-MYPLAN/123’) to make the request against

  • json (bool) – whether to return results in json

  • params (dict) – name/value dictionary of additional parameters to pass

Returns:

request object returned from requests.get()

Return type:

requests.Response

download_file(url: str, destination: str) → list[source]#

Download a specific artifact file (from the full artifact url provided) to disk.

Streams the download to avoid common ‘gotchas’ with downloading via http.

Parameters:

  • url (str) – url to download

  • destination (str) – destination path or filename where the artifact is to be downloaded to

Returns:

local filename of file that has been downloaded

Return type:

(str)

class emodpy.bamboo_api_utils.BuildInfo[source]#

Bases: object

A collection of methods for getting data on build results.

classmethod build_passed(plan_key: str, build_num: int) → bool[source]#

Determine whether a given build succeeded or not.

Parameters:

  • plan_key (str) – bamboo plan key (including project key)

  • build_num (int) – build number to retrieve results for

Returns:

whether the build succeeded

Return type:

bool

static successful_build_result(result) → bool[source]#

Analyze a build result json object and determine if it corresponds to a successful build

Parameters:

result – json build result

Returns:

whether the build was successful

Return type:

bool

static get_build_info(plan_key: str, index: int)[source]#

Retrieve the build info in json format for a given build plan with a relative index (0=latest)

Parameters:

  • plan_key (str) – bamboo plan key (including project key)

  • index (int) – index of build to retrieve info for (0=latest, 1=2nd most recent, etc.)

Returns:

build info results json

classmethod get_latest_successful_build(plan_key: str, scheduled_only: bool = True, max_iterations: int = 100)[source]#

Find the latest successful build within the last max_iterations builds for a given plan.

Parameters:

  • plan_key (str) – bamboo plan key (including project key)

  • scheduled_only (bool) – only count automatically run scheduled or triggered builds as successful

  • max_iterations (int) – maximum number of older builds to look through

Returns:

tuple containing:

build_num (str): build number of last successful build build_info: json data structure of build info for that build

Return type:

(tuple)

classmethod get_latest_build(plan_key: str)[source]#

Get the build info for the most recently run build for a given plan.

Parameters:

plan_key (str) – bamboo plan key (including project key)

Returns:

tuple containing:

build_num (str): build number of last successful build build_info: json data structure of build info for that build

Return type:

(tuple)

class emodpy.bamboo_api_utils.BuildArtifacts[source]#

Bases: object

A collection of methods for finding and interacting with build artifacts.

ERADICATION_EXE = 'Eradication.exe'#
SCHEMA_JSON = 'schema.json'#
REPORTER_PLUGINS = 'Reporter-Plugins'#
classmethod find_artifacts_by_name(plan_key: str, build_num: int, artifact: str) → list[source]#

Find all urls for files of an artifact of a given name for a specific build.

Parameters:

  • plan_key (str) – bamboo plan key (including project key)

  • build_num (int) – build number to retrieve artifact urls for

  • artifact (str) – artifact name/id

Returns:

list of artifact urls that can be downloaded

Return type:

(list of str)

classmethod find_artifacts(plan_key: str, build_num: int, artifact_list: list) → list[source]#

Find all urls for files of a list of artifacts for a specific build.

Parameters:

  • plan_key (str) – bamboo plan key (including project key)

  • build_num (int) – build number to retrieve artifact urls for

  • artifact_list (list) – list of artifact names/ids

Returns:

list of artifact urls that can be downloaded

Return type:

(list of str)

classmethod find_build_essential_artifacts(plan_key: str, build_num: int) → list[source]#

Find all ‘build essential’ artifact urls (Eradication, schema, reporters) for a specific build

Parameters:

  • plan_key (str) – bamboo plan key (including project key)

  • build_num (int) – build number to retrieve artifact urls for

Returns:

list of artifact urls that can be downloaded

Return type:

(list of str)

classmethod find_all_artifacts(plan_key: str, build_num: int) → list[source]#

Find all artifact urls (Eradication, schema, reporters) for a specific build

Parameters:

  • plan_key (str) – bamboo plan key (including project key)

  • build_num (int) – build number to retrieve artifact urls for

Returns:

list of artifact urls that can be downloaded

Return type:

(list of str)

classmethod find_all_artifact_names(plan_key: str, build_num: int) → list[source]#

Find all artifact names (e.g. ‘Eradication.exe’) for a specific build (can be plugged into find_artifacts() to get actual urls that can be downloaded)

Parameters:

  • plan_key (str) – bamboo plan key (including project key)

  • build_num (int) – build number to retrieve artifact urls for

Returns:

list of artifact names that can be downloaded

Return type:

(list of str)

classmethod download_artifact_to_file(plan_key: str, build_num: int, artifact, destination: str) → list[source]#

Download files found for a named artifact to the filepath provided.

Additional files found will be downloaded as _2, _3, _4, etc. For example, if there are 3 files for ‘Eradication.exe’ the first will be Eradication.exe, the second will be Eradication_2.exe, the third Eradication_3.exe.

Parameters:

  • plan_key (str) – bamboo plan key (including project key)

  • build_num (int) – build number to retrieve artifact urls for

  • artifact (list or str) – list (or string) of artifact names

  • destination (str) – destination path or filename where the artifact is to be downloaded to

Returns:

list of local filenames of files that have been downloaded

Return type:

(list of str)

classmethod download_artifacts_to_path(plan_key: str, build_num: int, artifact, destination_path: str) → list[source]#

Download all the files for a given artifact and build to a specific folder, using their original filenames.

Parameters:

  • plan_key (str) – bamboo plan key (including project key)

  • build_num (int) – build number to retrieve artifact urls for

  • artifact (list or str) – list (or string) of artifact names

  • destination_path (str) – path to destination folder where files are to be downloaded

Returns:

list of local filenames of files that have been downloaded

Return type:

(list of str)

classmethod download_latest_good_Eradication_exe(plan_key: str, destination: str) → str[source]#

Find the latest successful build for a specified plan, download the Eradication.exe artifact to a specified path.

Parameters:

  • plan_key (str) – bamboo plan key (including project key)

  • destination (str) – destination path or filename where the artifact is to be downloaded to

Returns:

build number of build that was found and had its artifact downloaded

Return type:

str

classmethod download_latest_good_schema_json(plan_key: str, destination: str) → str[source]#

Find the latest successful build for a specified plan, download the schema.json artifact to a specified path.

Parameters:

  • plan_key (str) – bamboo plan key (including project key)

  • destination (str) – destination path or filename where the artifact is to be downloaded to

Returns:

build number of build that was found and had its artifact downloaded

Return type:

str

classmethod download_eradication_exe(plan_key: str, build_num: str, destination: str) → str[source]#

Download Eradication.exe artifact from a specific build.

Parameters:

  • plan_key (str) – bamboo plan key (including project key)

  • build_num (str) – build number to download from

  • destination (str) – destination path or filename where the artifact is to be downloaded to

classmethod make_exe_executable(file_path: str)[source]#

On linux change the file permissions on a binary to make it executable

Parameters:

file_path (str) – binary file to mark as executable

classmethod download_schema_json(plan_key: str, build_num: str, destination: str) → str[source]#

Download schema.json artifact from a specific build.

Parameters:

  • plan_key (str) – bamboo plan key (including project key)

  • build_num (str) – build number to download from

  • destination (str) – destination path or filename where the artifact is to be downloaded to

classmethod download_from_bamboo_url(url: str, destination: str)[source]#

Download Eradication.exe/Eradication directly from bamboo url Assume you already done login

Parameters:

  • url –

  • destination (str) – destination path or filename where the artifact is to be downloaded to

Returns:

local file path that have been downloaded

Return type:

str

class emodpy.bamboo_api_utils.BuildPlans[source]#

Bases: object

Collection of methods for getting information on build plans.

static export_spec(plan_key: str) → str[source]#

Export a specific build plan to java specs.

Parameters:

plan_key (str) – bamboo plan key (including project key)

Returns:

full text of the .java file for the plan spec, if the plan was found (empty string if not)

Return type:

str

static get_plans_for_project(project_key: str) → list[source]#

Return a list of all the build plans for every plan in the project.

Parameters:

project_key (str) – bamboo project key

Returns:

list of plan keys for each plan that was found in the project

Return type:

(list of str)

emodpy.bamboo_api_utils.login(username=None, password=None)[source]#

Pass through to BambooConnection.login()

emodpy.bamboo_api_utils.save_credentials(username, password)[source]#

Pass through to BambooConnection.save_credentials()