emodpy.bamboo_api_utils module

emodpy.bamboo_api_utils.bamboo_connection()
class emodpy.bamboo_api_utils.BambooConnection

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: 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 = False, useport: bool = False) → str

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

  • useport (bool) – whether to use the port

Returns

endpoint url

Return type

str

find_server() → str

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

Returns

server url

Return type

str

url_exists(url: str) → bool

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

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

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)

Save bamboo api login credentials using keyring.

Parameters

  • username (str) – bamboo api login username (e.g. somebody@idmod.org)

  • password (str) – bamboo api login password

ensure_logged_in()

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

login_session_exists() → bool

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, password=None) → bool

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

Parameters

  • username (str) – bamboo api login username (e.g. somebody@idmod.org)

  • password (str) – bamboo api login password

Returns

success/failure

Return type

bool

normalize_url(url: str) → str

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) → requests.models.Response

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 = {}) → requests.models.Response

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

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

Bases: object

A collection of methods for getting data on build results.

classmethod build_passed(plan_key: str, build_num: int) → bool

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

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)

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)

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)

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

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

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

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

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

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

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

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

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

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

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

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)

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

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)

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

Bases: object

Collection of methods for getting information on build plans.

static export_spec(plan_key: str) → str

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

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)

Pass through to BambooConnection.login()

emodpy.bamboo_api_utils.save_credentials(username, password)

Pass through to BambooConnection.save_credentials()