Welcome to Python Jenkins’s documentation!

Python Jenkins is a library for the remote API of the Jenkins continuous integration server. It is useful for creating and managing jobs as well as build nodes.

Example usage:

j = jenkins.Jenkins('http://your_url_here', 'username', 'password')
j.get_jobs()
j.create_job('empty', jenkins.EMPTY_CONFIG_XML)
j.disable_job('empty')
j.copy_job('empty', 'empty_copy')
j.enable_job('empty_copy')
j.reconfig_job('empty_copy', jenkins.RECONFIG_XML)

j.delete_job('empty')
j.delete_job('empty_copy')

# build a parameterized job
j.build_job('api-test', {'param1': 'test value 1', 'param2': 'test value 2'})

Python Jenkins development is hosted on Launchpad: https://launchpad.net/python-jenkins

Installing

pip:

pip install python-jenkins

easy_install:

easy_install python-jenkins

Ubuntu Oneiric or later:

apt-get install python-jenkins

API documentation

class JenkinsException

General exception type for jenkins-API-related failures.

class Jenkins(url[, username=None[, password=None]])

Create handle to Jenkins instance.

All methods will raise JenkinsException on failure.

Parameters:

• username – Server username, str
• password – Server password, str
• url – URL of Jenkins server, str

get_jobs(self)

Get list of jobs running. Each job is a dictionary with ‘name’, ‘url’, and ‘color’ keys.

Returns:list of jobs, [ { str: str} ]

job_exists(name)

Parameters:

• name – Name of Jenkins job, str

Returns:

True if Jenkins job exists

build_job(name[, parameters=None[, token=None]])

Trigger build job.

Parameters:

• parameters – parameters for job, or None, dict

build_job_url(name[, parameters=None[, token=None]])

Get URL to trigger build job. Authenticated setups may require configuring a token on the server side.

Parameters:

• parameters – parameters for job, or None., dict
• token – (optional) token for building job, str

Returns:

URL for building job

create_job(name, config_xml)

Create a new Jenkins job

Parameters:

• name – Name of Jenkins job, str
• config_xml – config file text, str

copy_job(from_name, to_name)

Copy a Jenkins job

Parameters:

• from_name – Name of Jenkins job to copy from, str
• to_name – Name of Jenkins job to copy to, str

delete_job(name)

Delete Jenkins job permanently.

Parameters:

• name – Name of Jenkins job, str

enable_job(name)

Enable Jenkins job.

Parameters:

• name – Name of Jenkins job, str

disable_job(name)

Disable Jenkins job. To re-enable, call Jenkins.enable_job().

Parameters:

• name – Name of Jenkins job, str

get_job_config(name) → str

Get configuration XML of existing Jenkins job.

Parameters:

• name – Name of Jenkins job, str

Returns:

Job configuration XML

get_job_info(name)

Get job information dictionary.

Parameters:

• name – Job name, str

Returns:

dictionary of job information

debug_job_info(job_name)

Print out job info in more readable format

reconfig_job(name, config_xml)

Change configuration of existing Jenkins job. To create a new job, see Jenkins.create_job().

Parameters:

• name – Name of Jenkins job, str
• config_xml – New XML configuration, str

get_node_info(name) → dict

Get node information dictionary

Parameters:

• name – Node name, str

Returns:

Dictionary of node info, dict

node_exists(name) → bool

Parameters:

• name – Name of Jenkins node, str

Returns:

True if Jenkins node exists

create_node(name[, numExecutors=2[, nodeDescription=None[, remoteFS='/var/lib/jenkins'[, labels=None[, exclusive=False]]]]])

Parameters:

• name – name of node to create, str
• numExecutors – number of executors for node, int
• nodeDescription – Description of node, str
• remoteFS – Remote filesystem location to use, str
• labels – Labels to associate with node, str
• exclusive – Use this node for tied jobs only, bool

delete_node(name)

Delete Jenkins node permanently.

Parameters:

• name – Name of Jenkins node, str

get_queue_info(self)

Returns:list of job dictionaries, [dict]

Example:

>>> queue_info = j.get_queue_info()
>>> print(queue_info[0])
{u'task': {u'url': u'http://your_url/job/my_job/', u'color': u'aborted_anime', u'name': u'my_job'}, u'stuck': False, u'actions': [{u'causes': [{u'shortDescription': u'Started by timer'}]}], u'buildable': False, u'params': u'', u'buildableStartMilliseconds': 1315087293316, u'why': u'Build #2,532 is already in progress (ETA:10 min)', u'blocked': True}

get_info(self)

Get information on this Master. This information includes job list and view information.

Returns:dictionary of information about Master, dict

Example:

>>> info = j.get_info()
>>> jobs = info['jobs']
>>> print(jobs[0])
{u'url': u'http://your_url_here/job/my_job/', u'color': u'blue', u'name': u'my_job'}

jenkins_open(req)

Utility routine for opening an HTTP request to a Jenkins server. This should only be used to extends the Jenkins API.

Indices and tables

• Index
• Module Index
• Search Page