jenkinsapi package

Subpackages

• jenkinsapi.command_line package
  • Submodules
  • jenkinsapi.command_line.jenkins_invoke module
    • JenkinsInvoke
      • JenkinsInvoke.invokejob()
      • JenkinsInvoke.main()
      • JenkinsInvoke.mkparser()
    • main()
  • jenkinsapi.command_line.jenkinsapi_version module
    • main()
  • Module contents
• jenkinsapi.utils package
  • Submodules
  • jenkinsapi.utils.crumb_requester module
    • CrumbRequester
      • CrumbRequester.post_url()
  • jenkinsapi.utils.jenkins_launcher module
    • FailedToStart
    • JenkinsLancher
      • JenkinsLancher.JENKINS_LTS_WAR_URL
      • JenkinsLancher.JENKINS_WEEKLY_WAR_URL
      • JenkinsLancher.block_until_jenkins_ready()
      • JenkinsLancher.install_plugin()
      • JenkinsLancher.install_plugins()
      • JenkinsLancher.start()
      • JenkinsLancher.stop()
      • JenkinsLancher.update_config()
      • JenkinsLancher.update_war()
    • StreamThread
      • StreamThread.run()
      • StreamThread.stop()
      • StreamThread.stopped()
    • TimeOut
  • jenkinsapi.utils.jsonp_to_json module
    • jsonp_to_json()
  • jenkinsapi.utils.krb_requester module
    • KrbRequester
      • KrbRequester.get_request_dict()
  • jenkinsapi.utils.manifest module
    • InvalidJarError
    • Manifest
    • read_manifest()
  • jenkinsapi.utils.requester module
    • Requester
      • Requester.AUTH_COOKIE
      • Requester.VALID_STATUS_CODES
      • Requester.get_and_confirm_status()
      • Requester.get_request_dict()
      • Requester.get_url()
      • Requester.post_and_confirm_status()
      • Requester.post_url()
      • Requester.post_xml_and_confirm_status()
  • jenkinsapi.utils.simple_post_logger module
  • Module contents

Submodules

jenkinsapi.api module

This module is a collection of helpful, high-level functions for automating common tasks. Many of these functions were designed to be exposed to the command-line, hence they have simple string arguments.

jenkinsapi.api.block_until_complete(jenkinsurl: str, jobs: List[str], maxwait: int = 12000, interval: int = 30, raise_on_timeout: bool = True, username: str = '', password: str = '', ssl_verify: bool = True) → None

Wait until all of the jobs in the list are complete.

jenkinsapi.api.get_artifacts(jenkinsurl: str, jobname: str, build_no: int, username: str = '', password: str = '', ssl_verify: bool = True)

Find all the artifacts for the latest build of a job.

jenkinsapi.api.get_build(jenkinsurl: str, jobname: str, build_no: int, username: str = '', password: str = '', ssl_verify: bool = True) → Build

A convenience function to fetch down the test results from a jenkins job by build number.

jenkinsapi.api.get_latest_build(jenkinsurl: str, jobname: str, username: str = '', password: str = '', ssl_verify: bool = True) → Build

A convenience function to fetch down the very latest test results from a jenkins job.

jenkinsapi.api.get_latest_complete_build(jenkinsurl: str, jobname: str, username: str = '', password: str = '', ssl_verify: bool = True) → Build

A convenience function to fetch down the very latest test results from a jenkins job.

jenkinsapi.api.get_latest_test_results(jenkinsurl: str, jobname: str, username: str = '', password: str = '', ssl_verify: bool = True) → ResultSet

A convenience function to fetch down the very latest test results from a jenkins job.

jenkinsapi.api.get_nested_view_from_url(url: str, username: str = '', password: str = '', ssl_verify: bool = True) → View

Returns View based on provided URL. Convenient for nested views.

jenkinsapi.api.get_view_from_url(url: str, username: str = '', password: str = '', ssl_verify: bool = True) → View

Factory method

jenkinsapi.api.grab_artifact(jenkinsurl: str, jobname: str, artifactid, targetdir: str, username: str = '', password: str = '', strict_validation: bool = True, ssl_verify: bool = True) → None

Convenience method to find the latest good version of an artifact and save it to a target directory. Directory is made automatically if not exists.

jenkinsapi.api.install_artifacts(artifacts, dirstruct: Dict[str, str], installdir: str, basestaticurl: str, strict_validation: bool = False)

Install the artifacts.

jenkinsapi.api.search_artifact_by_regexp(jenkinsurl: str, jobname: str, artifactRegExp: Pattern, username: str = '', password: str = '', ssl_verify: bool = True) → Artifact

Search the entire history of a Jenkins job for a build which has an artifact whose name matches a supplied regular expression. Return only that artifact.

@param jenkinsurl: The base URL of the jenkins server @param jobid: The name of the job we are to search through @param artifactRegExp: A compiled regular expression object

(not a re-string)

@param username: Jenkins login user name, optional @param password: Jenkins login password, optional

jenkinsapi.api.search_artifacts(jenkinsurl: str, jobname: str, artifact_ids=None, username: str = '', password: str = '', ssl_verify: bool = True)

Search the entire history of a jenkins job for a list of artifact names. If same_build is true then ensure that all artifacts come from the same build of the job

jenkinsapi.artifact module

Artifacts can be used to represent data created as a side-effect of running a Jenkins build.

Artifacts are files which are associated with a single build. A build can have any number of artifacts associated with it.

This module provides a class called Artifact which allows you to download objects from the server and also access them as a stream.

class jenkinsapi.artifact.Artifact(filename: str, url: str, build: Build, relative_path: str | None = None)

Bases: object

Represents a single Jenkins artifact, usually some kind of file generated as a by-product of executing a Jenkins build.

get_data() → Any

Grab the text of the artifact

get_jenkins_obj() → Jenkins

save(fspath: str, strict_validation: bool = False) → str

Save the artifact to an explicit path. The containing directory must exist. Returns a reference to the file which has just been writen to.

Parameters:

fspath – full pathname including the filename, str

Returns:

filepath

save_to_dir(dirpath: str, strict_validation: bool = False) → str

Save the artifact to a folder. The containing directory must exist, but use the artifact’s default filename.

jenkinsapi.build module

A Jenkins build represents a single execution of a Jenkins Job.

Builds can be thought of as the second level of the Jenkins hierarchy beneath Jobs. Builds can have state, such as whether they are running or not. They can also have outcomes, such as whether they passed or failed.

Build objects can be associated with Results and Artifacts.

class jenkinsapi.build.Build(url: str, buildno: int, job: Job, depth: int = 1)

Bases: JenkinsBase

Represents a Jenkins build, executed in context of a job.

STR_TOTALCOUNT = 'totalCount'

STR_TPL_NOTESTS_ERR = '%s has status %s, and does not have any test results'

block() → None

block_until_complete(delay: int = 15) → None

get_actions() → Dict[str, Any]

get_artifact_dict() → dict[str, Artifact]

get_artifacts() → Iterator[Artifact]

get_build_url() → str

get_causes() → List[str]

Returns a list of causes. There can be multiple causes lists and some of the can be empty. For instance, when a build is manually aborted, Jenkins could add an empty causes list to the actions dict. Empty ones are ignored.

get_changeset_items()

Returns a list of changeSet items.

Each item has structure as in following example: {

“affectedPaths”: [

“content/rcm/v00-rcm-xccdf.xml”

], “author” : {

“absoluteUrl”: “http://jenkins_url/user/username79”, “fullName”: “username”

}, “commitId”: “3097”, “timestamp”: 1414398423091, “date”: “2014-10-27T08:27:03.091288Z”, “msg”: “commit message”, “paths”: [{

“editType”: “edit”, “file”: “/some/path/of/changed_file”

}], “revision”: 3097, “user”: “username”

}

get_console() → str

Return the current state of the text console.

get_description() → str

get_downstream_builds() → List[Build]

Get the downstream builds for this build :return List of Build or None

get_downstream_job_names() → List[str]

Get the downstream job names for this build :return List of string or None

get_downstream_jobs() → List[Job]

Get the downstream jobs for this build :return List of jobs or None

get_duration() → timedelta

get_env_vars() → Dict[str, str]

Return the environment variables.

This method is using the Environment Injector plugin: https://wiki.jenkins-ci.org/display/JENKINS/EnvInject+Plugin

get_estimated_duration() → int | None

Return the estimated build duration (in seconds) or none.

get_jenkins_obj() → Jenkins

get_master_build() → 'Build' | None

Get the master build if it exist, None otherwise :return Build or None

get_master_build_number() → int | None

Get the master build number if it exist, None otherwise :return: int or None

get_master_job() → Job | None

Get the master job object if it exist, None otherwise :return: Job or None

get_master_job_name() → str | None

Get the master job name if it exist, None otherwise :return: String or None

get_matrix_runs() → Iterator[Build]

For a matrix job, get the individual builds for each matrix configuration :return: Generator of Build

get_number() → int

get_params() → dict[str, str]

Return a dictionary of params names and their values, or an empty dictionary if no parameters are returned.

get_repo_url() → str

get_result_url() → str

Return the URL for the object which provides the job’s result summary.

get_resultset() → ResultSet

Obtain detailed results for this build.

Raises NoResults if the build has no results.

Returns:

ResultSet

get_revision() → str

get_revision_branch() → str

get_slave() → str

get_status() → str

get_timestamp() → datetime

Returns build timestamp in UTC

get_upstream_build() → 'Build' | None

Get the upstream build if it exist, None otherwise :return Build or None

get_upstream_build_number() → int | None

Get the upstream build number if it exist, None otherwise :return: int or None

get_upstream_job() → Job | None

Get the upstream job object if it exist, None otherwise :return: Job or None

get_upstream_job_name() → str | None

Get the upstream job name if it exist, None otherwise :return: String or None

has_resultset() → bool

Return a boolean, true if a result set is available. false if not.

is_good() → bool

Return a bool, true if the build was good. If the build is still running, return False.

is_kept_forever() → bool

is_running() → bool

Return a bool if running.

property name

stop() → bool

Stops the build execution if it’s running :return: boolean True if succeeded False otherwis

stream_logs(interval=0) → Iterator[str]

Return generator which streams parts of text console.

toggle_keep() → None

Toggle “keep this build forever” on and off

jenkinsapi.config module

Jenkins configuration

jenkinsapi.constants module

Constants for jenkinsapi

jenkinsapi.credential module

Module for jenkinsapi Credential class

class jenkinsapi.credential.AmazonWebServicesCredentials(cred_dict)

Bases: Credential

AWS credential using the CloudBees AWS Credentials Plugin See https://wiki.jenkins.io/display/JENKINS/CloudBees+AWS+Credentials+Plugin

Constructor expects following dict:

{

‘credential_id’: str, Automatically set by jenkinsapi ‘displayName’: str, Automatically set by Jenkins ‘fullName’: str, Automatically set by Jenkins ‘description’: str, ‘accessKey’: str, ‘secretKey’: str, ‘iamRoleArn’: str, ‘iamMfaSerialNumber’: str

}

When creating credential via jenkinsapi automatic fields not need to be in dict

get_attributes()

Used by Credentials object to create credential in Jenkins

get_attributes_xml()

Used by Credentials object to update a credential in Jenkins

class jenkinsapi.credential.Credential(cred_dict, jenkins_class='')

Bases: object

Base abstract class for credentials

Credentials returned from Jenkins don’t hold any sensitive information, so there is nothing useful can be done with existing credentials besides attaching them to Nodes or other objects.

You can create concrete Credential instance: UsernamePasswordCredential or SSHKeyCredential by passing credential’s description and credential dict.

Each class expects specific credential dict, see below.

get_attributes()

get_attributes_xml()

class jenkinsapi.credential.SSHKeyCredential(cred_dict: dict)

Bases: Credential

SSH key credential

Constructr expects following dict:

{

‘credential_id’: str, Automatically set by jenkinsapi ‘displayName’: str, Automatically set by Jenkins ‘fullName’: str, Automatically set by Jenkins ‘typeName’: str, Automatically set by Jenkins ‘description’: str, ‘userName’: str, ‘passphrase’: str, SSH key passphrase, ‘private_key’: str Private SSH key

}

private_key value is parsed to find type of credential to create:

private_key starts with - the value is private key itself

These credential variations are no longer supported by SSH Credentials plugin. jenkinsapi will raise ValueError if they are used:

private_key starts with / the value is a path to key private_key starts with ~ the value is a key from ~/.ssh

When creating credential via jenkinsapi automatic fields not need to be in dict

property attrs

get_attributes()

Used by Credentials object to create credential in Jenkins

get_attributes_xml()

Used by Credentials object to update a credential in Jenkins

class jenkinsapi.credential.SecretTextCredential(cred_dict)

Bases: Credential

Secret text credential

Constructor expects following dict:

{

‘credential_id’: str, Automatically set by jenkinsapi ‘displayName’: str, Automatically set by Jenkins ‘fullName’: str, Automatically set by Jenkins ‘typeName’: str, Automatically set by Jenkins ‘description’: str, ‘secret’: str,

}

When creating credential via jenkinsapi automatic fields not need to be in dict

get_attributes()

Used by Credentials object to create credential in Jenkins

get_attributes_xml()

Used by Credentials object to update a credential in Jenkins

class jenkinsapi.credential.UsernamePasswordCredential(cred_dict: dict)

Bases: Credential

Username and password credential

Constructor expects following dict:

{

‘credential_id’: str, Automatically set by jenkinsapi ‘displayName’: str, Automatically set by Jenkins ‘fullName’: str, Automatically set by Jenkins ‘typeName’: str, Automatically set by Jenkins ‘description’: str, ‘userName’: str, ‘password’: str

}

When creating credential via jenkinsapi automatic fields not need to be in dict

get_attributes()

Used by Credentials object to create credential in Jenkins

get_attributes_xml()

Used by Credentials object to update a credential in Jenkins

jenkinsapi.credentials module

This module implements the Credentials class, which is intended to be a container-like interface for all of the Global credentials defined on a single Jenkins node.

class jenkinsapi.credentials.Credentials(baseurl: str, jenkins_obj: Jenkins)

Bases: JenkinsBase

This class provides a container-like API which gives access to all global credentials on a Jenkins node.

Returns a list of Credential Objects.

get(item, default)

get_jenkins_obj() → Jenkins

iteritems() → Iterator[str, 'Credential']

iterkeys()

keys()

class jenkinsapi.credentials.Credentials2x(baseurl: str, jenkins_obj: Jenkins)

Bases: Credentials

This class provides a container-like API which gives access to all global credentials on a Jenkins node.

Returns a list of Credential Objects.

class jenkinsapi.credentials.CredentialsById(baseurl: str, jenkins_obj: Jenkins)

Bases: Credentials2x

This class provides a container-like API which gives access to all global credentials on a Jenkins node.

Returns a list of Credential Objects.

iteritems()

jenkinsapi.custom_exceptions module

Module for custom_exceptions.

Where possible we try to throw exceptions with non-generic, meaningful names.

exception jenkinsapi.custom_exceptions.AlreadyExists

Bases: JenkinsAPIException

Method requires POST and not GET

exception jenkinsapi.custom_exceptions.ArtifactBroken

Bases: JenkinsAPIException

An artifact is broken, wrong

exception jenkinsapi.custom_exceptions.ArtifactsMissing

Bases: NotFound

Cannot find a build with all of the required artifacts.

exception jenkinsapi.custom_exceptions.BadParams

Bases: JenkinsAPIException

Invocation was given bad or inappropriate params

exception jenkinsapi.custom_exceptions.BadURL

Bases: ValueError, JenkinsAPIException

A URL appears to be broken

exception jenkinsapi.custom_exceptions.FailedNoResults

Bases: NoResults

A build did not publish any results because it failed

exception jenkinsapi.custom_exceptions.JenkinsAPIException

Bases: Exception

Base class for all errors

exception jenkinsapi.custom_exceptions.NoBuildData

Bases: NotFound

A job has no build data.

exception jenkinsapi.custom_exceptions.NoResults

Bases: JenkinsAPIException

A build did not publish any results.

exception jenkinsapi.custom_exceptions.NotAuthorized

Bases: JenkinsAPIException

Not Authorized to access resource

exception jenkinsapi.custom_exceptions.NotBuiltYet

Bases: NotFound

A job has no build data.

exception jenkinsapi.custom_exceptions.NotConfiguredSCM

Bases: JenkinsAPIException

It’s a job that doesn’t have configured SCM

exception jenkinsapi.custom_exceptions.NotFound

Bases: JenkinsAPIException

Resource cannot be found

exception jenkinsapi.custom_exceptions.NotInQueue

Bases: JenkinsAPIException

It’s a job that is not in the queue

exception jenkinsapi.custom_exceptions.NotSupportSCM

Bases: JenkinsAPIException

It’s a SCM that does not supported by current version of jenkinsapi

exception jenkinsapi.custom_exceptions.PostRequired

Bases: JenkinsAPIException

Method requires POST and not GET

exception jenkinsapi.custom_exceptions.TimeOut

Bases: JenkinsAPIException

Some jobs have taken too long to complete.

exception jenkinsapi.custom_exceptions.UnknownJob

Bases: KeyError, NotFound

Jenkins does not recognize the job requested.

exception jenkinsapi.custom_exceptions.UnknownNode

Bases: KeyError, NotFound

Jenkins does not recognize the node requested.

exception jenkinsapi.custom_exceptions.UnknownPlugin

Bases: KeyError, NotFound

Jenkins does not recognize the plugin requested.

exception jenkinsapi.custom_exceptions.UnknownQueueItem

Bases: KeyError, NotFound

Jenkins does not recognize the requested queue item

exception jenkinsapi.custom_exceptions.UnknownView

Bases: KeyError, NotFound

Jenkins does not recognize the view requested.

jenkinsapi.executor module

Module for jenkinsapi Executer class

class jenkinsapi.executor.Executor(baseurl: str, nodename: str, jenkins_obj: Jenkins, number: int)

Bases: JenkinsBase

Class to hold information on nodes that are attached as slaves to the master jenkins instance

get_current_executable() → str

Returns the current Queue.Task this executor is running.

get_jenkins_obj() → Jenkins

get_number() → int

Get Executor number.

get_progress() → str

Returns percentage

is_idle() → bool

Returns Boolean: whether Executor is idle or not.

likely_stuck() → bool

Returns Boolean: whether Executor is likely stuck or not.

jenkinsapi.executors module

This module implements the Executors class, which is intended to be a container-like interface for all of the executors defined on a single Jenkins node.

class jenkinsapi.executors.Executors(baseurl: str, nodename: str, jenkins: Jenkins)

Bases: JenkinsBase

This class provides a container-like API which gives access to all executors on a Jenkins node.

Returns a list of Executor Objects.

get_jenkins_obj() → Jenkins

jenkinsapi.fingerprint module

Module for jenkinsapi Fingerprint

class jenkinsapi.fingerprint.Fingerprint(baseurl: str, id_: str, jenkins_obj: Jenkins)

Bases: JenkinsBase

Represents a jenkins fingerprint on a single artifact file ??

RE_MD5 = re.compile('^([0-9a-z]{32})$')

get_info()

Returns a tuple of build-name, build# and artifact filename for a good build.

get_jenkins_obj() → Jenkins

valid() → bool

Return True / False if valid. If returns True, self.unknown is set to either True or False, and can be checked if we have positive validity (fingerprint known at server) or negative validity (fingerprint not known at server, but not really an error).

validate() → bool

validate_for_build(filename: str, job: str, build: int) → bool

jenkinsapi.jenkins module

Module for jenkinsapi Jenkins object

class jenkinsapi.jenkins.Jenkins(baseurl: str, username: str = '', password: str = '', requester=None, lazy: bool = False, ssl_verify: bool = True, cert=None, timeout: int = 10, use_crumb: bool = True, max_retries=None)

Bases: JenkinsBase

Represents a jenkins environment.

base_server_url()

build_job(jobname: str, params=None) → None

Invoke a build by job name :param jobname: name of exist job, str :param params: the job params, dict :return: none

cancel_quiet_down()

Cancel the effect of the quiet-down command

copy_job(jobname: str, newjobname: str) → Job

create_job(jobname: str, xml) → Job

Create a job

alternatively you can create job using Jobs object: self.jobs[‘job_name’] = config :param jobname: name of new job, str :param config: configuration of new job, xml :return: new Job obj

create_multibranch_pipeline_job(jobname, xml, block=True, delay=60)

Returns:

list of new Job objects

create_node(name: str, num_executors: int = 2, node_description: str = '', remote_fs: str = '/var/lib/jenkins', labels=None, exclusive: bool = False) → Node

Create a new JNLP slave node by name.

To create SSH node, please see description in Node class

Parameters:

• name – fqdn of slave, str

• num_executors – number of executors, int

• node_description – a freetext field describing the node

• remote_fs – jenkins path, str

• labels – labels to associate with slave, str

• exclusive – tied to specific job, boolean

Returns:

node obj

create_node_with_config(name: str, config) → Node | None

Create a new slave node with specific configuration. Config should be resemble the output of node.get_node_attributes() :param str name: name of slave :param dict config: Node attributes for Jenkins API request

to create node (See function output Node.get_node_attributes())

Returns:

node obj

property credentials

property credentials_by_id

delete_job(jobname: str) → None

Delete a job by name :param jobname: name of a exist job, str :return: new jenkins_obj

delete_node(nodename: str) → None

Remove a node from the managed slave list Please note that you cannot remove the master node

Parameters:

nodename – string holding a hostname

Returns:

None

delete_plugin(plugin: str | Plugin, restart: bool = True, force_restart: bool = False, wait_for_reboot: bool = True, no_reboot_warning: bool = False) → None

Delete a plugin and optionally restart jenkins. Will not delete dependencies. @param plugin: Plugin (string or Plugin object) to be deleted @param restart: Boolean, restart Jenkins when required by plugin @param force_restart: Boolean, force Jenkins to restart,

ignoring plugin preferences

delete_plugins(plugin_list, restart: bool = True, force_restart: bool = False, wait_for_reboot: bool = True, no_reboot_warning: bool = False)

Delete a list of plugins and optionally restart jenkins. Will not delete dependencies. @param plugin_list: List of plugins (strings, Plugin objects or

a mix of the two) to be deleted

@param restart: Boolean, restart Jenkins when required by plugin @param force_restart: Boolean, force Jenkins to restart,

ignoring plugin preferences

delete_view_by_url(viewurl: str)

generate_new_api_token(new_token_name: str = 'Token By jenkinsapi python')

get_artifact_data(id_)

get_create_url() → str

get_credentials(cred_class=<class 'jenkinsapi.credentials.Credentials2x'>)

Return credentials

get_executors(nodename: str) → Executors

get_jenkins_obj()

get_jenkins_obj_from_url(url: str)

get_job(jobname: str) → Job

Get a job by name :param jobname: name of the job, str :return: Job obj

get_job_by_url(url: str, job_name: str) → Job

Get a job by url :param url: jobs’ url :param jobname: name of the job, str :return: Job obj

get_jobs()

Fetch all the build-names on this Jenkins server.

get_jobs_info()

Get the jobs information :return url, name

get_jobs_list()

get_label(label_name: str) → Label

get_master_data()

get_node(nodename: str) → Node

Get a node object for a specific node

get_node_url(nodename: str = '') → str

Return the url for nodes

get_nodes() → Nodes

get_nodes_url() → str

get_plugins(depth: int = 1) → Plugins

get_plugins_url(depth)

get_queue() → Queue

get_queue_url()

get_view_by_url(view_url: str)

has_job(jobname: str) → bool

Does a job by the name specified exist :param jobname: string :return: boolean

has_node(nodename: str) → bool

Does a node by the name specified exist :param nodename: string, hostname :return: boolean

has_plugin(plugin_name: str) → bool

install_plugin(plugin: str | Plugin, restart: bool = True, force_restart: bool = False, wait_for_reboot: bool = True, no_reboot_warning: bool = False)

Install a plugin and optionally restart jenkins. @param plugin: Plugin (string or Plugin object) to be installed @param restart: Boolean, restart Jenkins when required by plugin @param force_restart: Boolean, force Jenkins to restart,

ignoring plugin preferences

@param no_warning: Don’t show warning when restart is needed and restart parameters are set to False

install_plugins(plugin_list, restart: bool = True, force_restart: bool = False, wait_for_reboot: bool = True, no_reboot_warning: bool = False) → None

Install a list of plugins and optionally restart jenkins. @param plugin_list: List of plugins (strings, Plugin objects or

a mix of the two) to be installed

@param restart: Boolean, restart Jenkins when required by plugin @param force_restart: Boolean, force Jenkins to restart,

ignoring plugin preferences

property is_quieting_down: bool

items()

Parameters:

return – A list of pairs. Each pair will be (job name, Job object)

iteritems()

iterkeys()

property jobs

keys()

property nodes

property plugins

quiet_down()

Put Jenkins in a Quiet mode, preparation for restart. No new builds started

rename_job(jobname: str, newjobname: str) → Job

Rename a job :param jobname: name of a exist job, str :param newjobname: name of new job, str :return: new Job obj

run_groovy_script(script: str) → str

Runs the requested groovy script on the Jenkins server returning the result as text. Raises a JenkinsAPIException if the returned HTTP response code from the POST request is not 200 OK.

Example:

server = Jenkins(…) script = ‘println “Hello world!”’ result = server.run_groovy_script(script) print(result) # will print “Hello world!”

safe_exit(wait_for_exit: bool = True, max_wait: int = 360)

Restarts jenkins when no jobs are running, except for pipeline jobs

safe_restart(wait_for_reboot: bool = True)

restarts jenkins when no jobs are running

shutdown() → None

use_auth_cookie() → None

validate_fingerprint(id_)

validate_fingerprint_for_build(digest, filename, job, build)

property version: str

Return version number of Jenkins

property views

jenkinsapi.jenkinsbase module

Module for JenkinsBase class

class jenkinsapi.jenkinsbase.JenkinsBase(baseurl: str, poll: bool = True)

Bases: object

This appears to be the base object that all other jenkins objects are inherited from

get_data(url, params=None, tree=None)

get_jenkins_obj()

poll(tree=None)

pprint()

Print out all the data in this object for debugging.

process_job_folder(folder, folder_path)

classmethod python_api_url(url: str) → str

resolve_job_folders(jobs)

classmethod strip_trailing_slash(url: str) → str

jenkinsapi.job module

Module for jenkinsapi Job

class jenkinsapi.job.Job(url: str, name: str, jenkins_obj: Jenkins)

Bases: JenkinsBase, MutableJenkinsThing

Represents a jenkins job A job can hold N builds which are the actual execution environments

delete_build(build_number)

Remove build

Parameters:

build_number (int) – Build number

Raises:

NotFound – When build is not found

delete_from_queue()

Delete a job from the queue only if it’s enqueued :raise NotInQueue if the job is not in the queue

disable()

Disable job

enable()

Enable job

get_build(buildnumber)

get_build_by_params(build_params, order=1)

get_build_dict()

get_build_ids()

Return a sorted list of all good builds as ints.

get_build_metadata(buildnumber)

Get the build metadata for a given build number. For large builds with tons of tests, this method is faster than get_build by returning less data.

get_build_triggerurl() → str

get_buildnumber_for_revision(revision, refresh=False)

Parameters:

• revision – subversion revision to look for, int

• refresh – boolean, whether or not to refresh the revision -> buildnumber map

Returns:

list of buildnumbers, [int]

get_config()

Returns the config.xml from the job

get_config_xml_url()

get_description() → str

get_downstream_job_names()

Get all the possible downstream job names :return List of String

get_downstream_jobs()

Get all the possible downstream jobs :return List of Job

get_first_build()

get_first_buildnumber()

Get the numerical ID of the first build.

get_full_name()

Get the full name for a job (including parent folders) from the job URL.

static get_full_name_from_url_and_baseurl(url, baseurl)

Get the full name for a job (including parent folders) from the job URL.

get_jenkins_obj() → Jenkins

get_last_build()

Get the last build

get_last_build_or_none()

Get the last build or None if there is no builds

get_last_buildnumber()

Get the numerical ID of the last build.

get_last_completed_build()

Get the last build regardless of status

get_last_completed_buildnumber()

Get the numerical ID of the last complete build.

get_last_failed_buildnumber()

Get the numerical ID of the last failed build.

get_last_good_build()

Get the last good build

get_last_good_buildnumber()

Get the numerical ID of the last good build.

get_last_stable_build()

Get the last stable build

get_last_stable_buildnumber()

Get the numerical ID of the last stable build.

get_next_build_number()

Return the next build number that Jenkins will assign.

get_params()

Get the parameters for this job. Format varies by parameter type. Here is an example string parameter:

{

‘type’: ‘StringParameterDefinition’, ‘description’: ‘Parameter description’, ‘defaultParameterValue’: {‘value’: ‘default value’}, ‘name’: ‘FOO_BAR’

}

get_params_list()

Gets the list of parameter names for this job.

get_queue_item()

Return a QueueItem if this object is in a queue, otherwise raise an exception

get_revision_dict()

Get dictionary of all revisions with a list of buildnumbers (int) that used that particular revision

get_scm_branch()

Get list of SCM branches : return: list of SCM branches

get_scm_type()

get_scm_url()

Get list of project SCM urls For some SCM’s jenkins allow to configure and use number of SCM url’s : return: list of SCM urls

get_upstream_job_names()

Get all the possible upstream job names :return List of String

get_upstream_jobs()

Get all the possible upstream jobs :return List of Job

has_params()

If job has parameters, returns True, else False

has_queued_build(build_params)

Returns True if a build with build_params is currently queued.

invoke(securitytoken=None, block: bool = False, build_params=None, cause=None, files=None, delay: int = 5, quiet_period=None) → QueueItem

is_enabled()

is_queued()

is_queued_or_running()

is_running()

load_config()

static mk_json_from_build_parameters(build_params, file_params=None)

modify_scm_branch(new_branch, old_branch=None)

Modify SCM (“Source Code Management”) branch name for configured job. :param new_branch : new repository branch name to set.

If job has multiple branches configured and “old_branch” not provided - method will allways modify first url.

Parameters:

(optional) (old_branch) – exact value of branch name to be replaced. For some SCM’s jenkins allow set multiple branches per job this parameter intended to indicate which branch need to be modified

modify_scm_url(new_source_url, old_source_url=None)

Modify SCM (“Source Code Management”) url for configured job. :param new_source_url : new repository url to set.

If job has multiple repositories configured and “old_source_url” not provided - method will allways modify first url.

Parameters:

(optional) (old_source_url) – for some SCM’s jenkins allows settting multiple repositories per job this parameter intended to indicate which repository need to be modified

poll(tree=None)

toggle_keep_build(build_number)

update_config(config, full_response=False, encoding='utf-8')

Update the config.xml to the job Also refresh the ElementTree object since the config has changed :param full_response (optional): if True, it will return the full

response object instead of just the response text. Useful for debugging and validation workflows.

jenkinsapi.jobs module

This module implements the Jobs class, which is intended to be a container-like interface for all of the jobs defined on a single Jenkins server.

class jenkinsapi.jobs.Jobs(jenkins: Jenkins)

Bases: object

This class provides a container-like API which gives access to all jobs defined on the Jenkins server. It behaves like a dict in which keys are Job-names and values are actual jenkinsapi.Job objects.

build(job_name: str, params=None, **kwargs) → QueueItem

Executes build of a job

Parameters:

• job_name (str) – Job name

• params (dict) – Job parameters

• kwargs – Parameters for Job.invoke() function

Returns QueueItem:

Object to track build progress

copy(job_name: str, new_job_name: str) → Job

Copy a job :param str job_name: Name of an existing job :param new_job_name: Name of new job :returns Job: new Job object

create(job_name: str, config: str | bytes) → Job

Create a job

Parameters:

• jobname (str) – Name of new job

• config (str) – XML configuration of new job

Returns Job:

new Job object

create_multibranch_pipeline(job_name: str, config: str, block: bool = True, delay: int = 60) → list[Job]

Create a multibranch pipeline job

Parameters:

• jobname (str) – Name of new job

• config (str) – XML configuration of new job

• block – block until scan is finished?

• delay – max delay to wait for scan to finish (seconds)

:returns list of new Jobs after scan

iteritems() → Iterator[str, 'Job']

Iterate over the names & objects for all jobs

iterkeys() → Iterator[str]

Iterate over the names of all available jobs

itervalues() → Iterator[Job]

Iterate over all available jobs

keys() → list[str]

Return a list of the names of all jobs

poll(tree='jobs[name,color,url]')

rename(job_name: str, new_job_name: str) → Job

Rename a job

Parameters:

• job_name (str) – Name of an existing job

• new_job_name (str) – Name of new job

Returns Job:

new Job object

jenkinsapi.label module

Module for jenkinsapi labels

class jenkinsapi.label.Label(baseurl, labelname, jenkins_obj)

Bases: JenkinsBase

Class to hold information on labels that tied to a collection of jobs

get_jenkins_obj()

get_tied_job_names()

Get a list of the name of tied jobs.

get_tied_jobs()

Get a list of jobs.

is_online()

jenkinsapi.mutable_jenkins_thing module

Module for MutableJenkinsThing

class jenkinsapi.mutable_jenkins_thing.MutableJenkinsThing

Bases: object

A mixin for certain mutable objects which can be renamed and deleted.

get_delete_url() → str

get_rename_url() → str

jenkinsapi.node module

Module for jenkinsapi Node class

class jenkinsapi.node.Node(jenkins_obj: Jenkins, baseurl: str, nodename: str, node_dict, poll: bool = True)

Bases: JenkinsBase

Class to hold information on nodes that are attached as slaves to the master jenkins instance

block_until_idle(timeout: int, poll_time: int = 5) → None

Blocks until the node become idle. :param timeout: Time in second when the wait is aborted. :param poll_time: Interval in seconds between each check. :@raise TimeOut

get_architecture() → str

Returns the system architecture of the node eg. “Linux (amd64)”.

get_available_physical_memory() → int

Returns the node’s available physical memory in bytes.

get_available_swap_space() → int

Returns the node’s available swap space in bytes.

get_clock_difference() → int

Returns the difference between the node’s clock and the master Jenkins clock. Used to detect out of sync clocks.

get_config() → str

Returns the config.xml from the node.

get_config_element(el_name: str) → str

Returns simple config element.

Better not to be used to return “nodeProperties” or “launcher”

get_jenkins_obj() → Jenkins

get_labels() → str | None

Returns the labels for a slave as a string with each label separated by the ‘ ‘ character.

get_monitor(monitor_name: str, poll_monitor=True) → str

Polls the node returning one of the monitors in the monitorData branch of the returned node api tree.

get_node_attributes() → dict

Gets node attributes as dict

Used by Nodes object when node is created

Returns:

Node attributes dict formatted for Jenkins API request to create node

get_num_executors() → str

get_response_time() → int

Returns the node’s average response time.

get_temp_path() → str

Returns the local path to the node’s temp directory.

get_temp_size() → int

Returns the size in bytes of the node’s temp directory.

get_total_physical_memory() → int

Returns the node’s total physical memory in bytes.

get_total_swap_space() → int

Returns the node’s total swap space in bytes.

get_workspace_path() → str

Returns the local path to the node’s Jenkins workspace directory.

get_workspace_size() → int

Returns the size in bytes of the node’s Jenkins workspace directory.

is_idle() → bool

is_jnlpagent() → bool

is_online() → bool

is_temporarily_offline() → bool

load_config() → None

Loads the config.xml for the node allowing it to be re-queried without generating new requests.

offline_reason() → str

set_config_element(el_name: str, value: str) → None

Sets simple config element

set_num_executors(value: int | str) → None

Sets number of executors for node

Warning! Setting number of executors on master node will erase all other settings

set_offline(message='requested from jenkinsapi') → None

Set node offline. If after run node state has not been changed raise AssertionError. : param message: optional string explain why you are taking this

node offline

set_online() → None

Set node online. Before change state verify client state: if node set ‘offline’ but ‘temporarilyOffline’ is not set - client has connection problems and AssertionError raised. If after run node state has not been changed raise AssertionError.

toggle_temporarily_offline(message='requested from jenkinsapi') → None

Switches state of connected node (online/offline) and set ‘temporarilyOffline’ property (True/False) Calling the same method again will bring node status back. :param message: optional string can be used to explain why you

are taking this node offline

update_offline_reason(reason: str) → None

Update offline reason on a temporary offline clsuter

upload_config(config_xml: str) → None

Uploads config_xml to the config.xml for the node.

jenkinsapi.nodes module

Module for jenkinsapi nodes

class jenkinsapi.nodes.Nodes(baseurl: str, jenkins_obj: Jenkins)

Bases: JenkinsBase

Class to hold information on a collection of nodes

create_node(name: str, node_dict: dict) → Node

Create a new slave node

Parameters:

• name (str) – name of slave

• node_dict (dict) – node dict (See Node class)

Returns:

node obj

create_node_with_config(name: str, config: dict) → Node | None

Create a new slave node with specific configuration. Config should be resemble the output of node.get_node_attributes() :param str name: name of slave :param dict config: Node attributes for Jenkins API request

to create node (See function output Node.get_node_attributes())

Returns:

node obj

get_jenkins_obj() → Jenkins

items() → list[tuple[str, Node]]

Return a copy of the container’s list of (name, node) pairs.

iteritems() → Iterator[tuple[str, Node]]

Return an iterator over the container’s (name, node) pairs.

Using iteritems() while creating nodes may raise a RuntimeError or fail to iterate over all entries.

iterkeys() → Iterator[str]

Return an iterator over the container’s node names.

Using iterkeys() while creating nodes may raise a RuntimeError or fail to iterate over all entries.

itervalues() → Iterator[Node]

Return an iterator over the container’s nodes.

Using itervalues() while creating nodes may raise a RuntimeError or fail to iterate over all entries.

keys() → list[str]

Return a copy of the container’s list of node names.

values() → list[Node]

Return a copy of the container’s list of nodes.

jenkinsapi.plugin module

Module for jenkinsapi Plugin

class jenkinsapi.plugin.Plugin(plugin_dict: dict | str)

Bases: object

Plugin class

get_attributes() → str

Used by Plugins object to install plugins in Jenkins

get_download_link(update_center_dict) → str

is_latest(update_center_dict: dict) → bool

Used by Plugins object to determine if plugin can be installed through the update center (when plugin version is latest version), or must be installed by uploading the plugin hpi file.

to_plugin(plugin_string: str) → dict

jenkinsapi.plugins module

jenkinsapi plugins

class jenkinsapi.plugins.Plugins(url: str, jenkins_obj: Jenkins)

Bases: JenkinsBase

Plugins class for jenkinsapi

check_updates_server() → None

get_jenkins_obj() → Jenkins

get_plugins_dict() → dict[str, Plugin]

iteritems() → Generator[str, Plugin, None]

keys() → list[str]

plugin_version_already_installed(plugin) → bool

Check if plugin version is already installed

plugin_version_is_being_installed(plugin) → bool

Return true if plugin is currently being installed.

property restart_required

Call after plugin installation to check if Jenkins requires a restart

property update_center_dict

property update_center_install_status

Jenkins 2.x specific

values() → list[Plugin]

jenkinsapi.queue module

Queue module for jenkinsapi

class jenkinsapi.queue.Queue(baseurl: str, jenkins_obj: Jenkins)

Bases: JenkinsBase

Class that represents the Jenkins queue

delete_item(queue_item: QueueItem)

delete_item_by_id(item_id: str)

get_jenkins_obj() → Jenkins

get_queue_item_url(item: str) → str

get_queue_items_for_job(job_name: str)

iteritems() → Iterator[Tuple[str, QueueItem]]

iterkeys() → Iterator[str]

itervalues() → Iterator[QueueItem]

keys() → list[str]

values() → list[QueueItem]

class jenkinsapi.queue.QueueItem(baseurl: str, jenkins_obj: Jenkins)

Bases: JenkinsBase

An individual item in the queue

block_until_building(delay=5)

block_until_complete(delay=5)

get_build() → Build

get_build_number() → int

get_jenkins_obj() → Jenkins

get_job() → Job

Return the job associated with this queue item

get_job_name() → str

get_parameters()

returns parameters of queue item

is_queued() → bool

Return True if this queued item is queued.

is_running() → bool

Return True if this queued item is running.

property name

property queue_id

property why

jenkinsapi.result module

Module for jenkinsapi Result

class jenkinsapi.result.Result(**kwargs)

Bases: object

Result class

identifier() → str

Calculate an ID for this object.

jenkinsapi.result_set module

Module for jenkinsapi ResultSet

class jenkinsapi.result_set.ResultSet(url: str, build: Build)

Bases: JenkinsBase

Represents a result from a completed Jenkins run.

get_jenkins_obj() → Jenkins

items()

iteritems()

keys() → list[str]

property name

jenkinsapi.view module

Module for jenkinsapi views

class jenkinsapi.view.View(url: str, name: str, jenkins_obj: Jenkins)

Bases: JenkinsBase

View class

add_job(job_name: str, job=None) → bool

Add job to a view

Parameters:

• job_name – name of the job to be added

• job – Job object to be added

Returns:

True if job has been added, False if job already exists or job not known to Jenkins

delete() → None

Remove this view object

get_config() → str

Return the config.xml from the view

get_config_xml_url() → str

get_jenkins_obj() → Jenkins

get_job_dict() → dict

get_job_url(str_job_name: str) → str

get_nested_view_dict() → dict

items()

iteritems() → Iterator[Tuple[str, Job]]

keys() → list[str]

remove_job(job_name: str) → bool

Remove job from a view

Parameters:

job_name – name of the job to be removed

Returns:

True if job has been removed, False if job not assigned to this view

update_config(config: str) → str

Update the config.xml to the view

values() → list[Job]

property views

jenkinsapi.views module

Module for jenkinsapi Views

class jenkinsapi.views.Views(jenkins)

Bases: object

An abstraction on a Jenkins object’s views

CATEGORIZED_VIEW = 'org.jenkinsci.plugins.categorizedview.CategorizedJobsView'

DASHBOARD_VIEW = 'hudson.plugins.view.dashboard.Dashboard'

LIST_VIEW = 'hudson.model.ListView'

MY_VIEW = 'hudson.model.MyView'

NESTED_VIEW = 'hudson.plugins.nested_view.NestedView'

PIPELINE_VIEW = 'au.com.centrumsystems.hudson.plugin.buildpipeline.BuildPipelineView'

create(view_name, view_type='hudson.model.ListView', config=None)

Create a view :param view_name: name of new view, str :param view_type: type of the view, one of the constants in Views, str :param config: XML configuration of the new view :return: new View obj or None if view was not created

iteritems()

Get the names & objects for all views

iterkeys()

Get the names of all available views

keys()

Return a list of the names of all views

poll(tree=None)

Module contents

About this library

Jenkins is the market leading continuous integration system, originally created by Kohsuke Kawaguchi. This API makes Jenkins even easier to use by providing an

easy to use conventional python interface.

Jenkins (and It’s predecessor Hudson) are fantastic projects - but they are somewhat Java-centric. Thankfully the designers have provided an excellent and complete REST interface. This library wraps up that interface as more conventional python objects in order to make most Jenkins oriented tasks simpler.

This library can help you:

• Query the test-results of a completed build

• Get a objects representing the latest builds of a job

• Search for artifacts by simple criteria

• Block until jobs are complete

• Install artifacts to custom-specified directory structures

• username/password auth support for jenkins instances with auth turned on

• Ability to search for builds by subversion revision

• Ability to add/remove/query jenkins slaves

Installing JenkinsAPI

Egg-files for this project are hosted on PyPi. Most Python users should be able to use pip or distribute to automatically install this project.

Most users can do the following:

easy_install jenkinsapi

If you’d like to install in multi-version mode:

easy_install -m jenkinsapi

Project Authors

• Salim Fadhley (sal@stodge.org)

• Ramon van Alteren (ramon@vanalteren.nl)

• Ruslan Lutsenko (ruslan.lutcenko@gmail.com)

Current code lives on github: https://github.com/salimfadhley/jenkinsapi