python-jenkins/doc/index.rst

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

General exception type for jenkins-API-related failures.

Create handle to Jenkins instance.

All methods will raise JenkinsException on failure.

param username

Server username, str

param password

Server password, str

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

param name

Name of Jenkins job, str

returns

True if Jenkins job exists

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

Trigger build job.

param 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.

param parameters

parameters for job, or None., dict

param token

(optional) token for building job, str

returns

URL for building job

create_job(name, config_xml)

Create a new Jenkins job

param name

Name of Jenkins job, str

param config_xml

config file text, str

copy_job(from_name, to_name)

Copy a Jenkins job

param from_name

Name of Jenkins job to copy from, str

param to_name

Name of Jenkins job to copy to, str

delete_job(name)

Delete Jenkins job permanently.

param name

Name of Jenkins job, str

enable_job(name)

Enable Jenkins job.

param name

Name of Jenkins job, str

disable_job(name)

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

param name

Name of Jenkins job, str

get_job_config(name) -> str

Get configuration XML of existing Jenkins job.

param name

Name of Jenkins job, str

returns

Job configuration XML

get_job_info(name)

Get job information dictionary.

param 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.

param name

Name of Jenkins job, str

param config_xml

New XML configuration, str

get_node_info(name) -> dict

Get node information dictionary

param name

Node name, str

returns

Dictionary of node info, dict

node_exists(name) -> bool

param 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]]]]])

param name

name of node to create, str

param numExecutors

number of executors for node, int

param nodeDescription

Description of node, str

param remoteFS

Remote filesystem location to use, str

param labels

Labels to associate with node, str

param exclusive

Use this node for tied jobs only, bool

delete_node(name)

Delete Jenkins node permanently.

param 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

• genindex
• modindex
• search