Pythonjenkins (1) Linux Manual Page

NAME

pythonjenkins – Python Jenkins Documentation

Python Jenkins is a python wrapper for the Jenkins REST API which aims to provide a more conventionally pythonic way of controlling a Jenkins server. It provides a higher-level API containing a number of convenience functions.

We like to use python-jenkins to automate our Jenkins servers. Here are some of the things you can use it for:

•

Create new jobs

•

Copy existing jobs

•

Delete jobs

•

Update jobs

•

Get a job’s build information

•

Get Jenkins master version information

•

Get Jenkins plugin information

•

Start a build on a job

•

Create nodes

•

Enable/Disable nodes

•

Get information on nodes

•

Create/delete/reconfig views

•

and many more..

To install:

$ sudo python setup.py install

Online documentation:

•

http://python-jenkins.readthedocs.org/en/latest/

DEVELOPERS

Bug report:

•

https://bugs.launchpad.net/python-jenkins

Repository:

•

https://git.openstack.org/cgit/stackforge/python-jenkins

Cloning:

•

git clone https://git.openstack.org/stackforge/python-jenkins

Patches are submitted via Gerrit at:

•

https://review.openstack.org/

Please do not submit GitHub pull requests, they will be automatically closed.

More details on how you can contribute is available on our wiki at:

•

http://docs.openstack.org/infra/manual/developers.html

WRITING A PATCH

We ask that all code submissions be flake8 clean. The easiest way to do that is to run tox before submitting code for review in Gerrit. It will run flake8 in the same manner as the automated test suite that will run on proposed patchsets.

INSTALLING WITHOUT SETUP.PY

Then install the required python packages using pip:

$ sudo pip install python-jenkins

API REFERENCE

See examples at example

exception jenkins.JenkinsException

General exception type for jenkins-API-related failures.

exception jenkins.NotFoundException

A special exception to call out the case of receiving a 404.

exception jenkins.EmptyResponseException

A special exception to call out the case receiving an empty response.

exception jenkins.BadHTTPException

A special exception to call out the case of a broken HTTP response.

jenkins.auth_headers(username, password)

Simple implementation of HTTP Basic Authentication.

Returns the ‘Authentication’ header value.

class jenkins.Jenkins(url, username=None, password=None, timeout=<object object at 0x7f5587ade220>)

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

•

timeout — Server connection timeout in secs (default: not set), int

Jenkins.maybe_add_crumb(req)

Jenkins.get_job_info(name, depth=0)

Get job information dictionary.

Parameters

•

name — Job name, str

•

depth — JSON depth, int

Returns

dictionary of job information

Jenkins.get_job_info_regex(pattern, depth=0)

Get a list of jobs information that contain names which match the regex pattern.

Parameters

•

pattern — regex pattern, str

•

depth — JSON depth, int

Returns

List of jobs info, list

Jenkins.get_job_name(name)

Return the name of a job using the API.

That is roughly an identity method which can be used to quickly verify a job exist or is accessible without causing too much stress on the server side.

Parameters

name — Job name, str

Returns

Name of job or None

Jenkins.debug_job_info(job_name)

Print out job info in more readable format.

Jenkins.jenkins_open(req, add_crumb=True)

Utility routine for opening an HTTP request to a Jenkins server.

This should only be used to extends the Jenkins API.

Jenkins.get_build_info(name, number, depth=0)

Get build information dictionary.

Parameters

•

name — Job name, str

•

name — Build number, int

•

depth — JSON depth, int

Returns

dictionary of build information, dict

Example:


>>> j = Jenkins() >>> next_build_number = j.get_job_info('build_name')['nextBuildNumber'] >>> output = j.build_job('build_name') >>> from time import sleep;
sleep(10) >>> build_info = j.get_build_info('build_name', next_build_number) >>> print(build_info)
{
    u'building' : False, u'changeSet' : {u'items' : [ {u'date' : u'2011-12-19T18:01:52.540557Z', u'msg' : u'test', u'revision' : 66, u'user' : u'unknown', u'paths' : [ {u'editType' : u'edit', u'file' : u'/branches/demo/index.html'} ]} ], u'kind' : u'svn', u'revisions' : [ {u'module' : u'http://eaas-svn01.i3.level3.com/eaas', u'revision' : 66} ]}, u'builtOn' : u'', u'description' : None, u'artifacts' : [ {u'relativePath' : u'dist/eaas-87-2011-12-19_18-01-57.war', u'displayPath' : u'eaas-87-2011-12-19_18-01-57.war', u'fileName' : u'eaas-87-2011-12-19_18-01-57.war'}, {u'relativePath' : u'dist/eaas-87-2011-12-19_18-01-57.war.zip', u'displayPath' : u'eaas-87-2011-12-19_18-01-57.war.zip', u'fileName' : u'eaas-87-2011-12-19_18-01-57.war.zip'} ], u'timestamp' : 1324317717000, u'number' : 87, u'actions' : [ {u'parameters' : [ {u'name' : u'SERVICE_NAME', u'value' : u'eaas'}, {u'name' : u'PROJECT_NAME', u'value' : u'demo'} ]}, {u'causes' : [ {u'userName' : u'anonymous', u'shortDescription' : u'Started by user anonymous'} ]}, {}, {}, {} ], u'id' : u'2011-12-19_18-01-57', u'keepLog' : False, u'url' : u'http://eaas-jenkins01.i3.level3.com:9080/job/build_war/87/', u'culprits' : [ {u'absoluteUrl' : u'http://eaas-jenkins01.i3.level3.com:9080/user/unknown', u'fullName' : u'unknown'} ], u'result' : u'SUCCESS', u'duration' : 8826, u'fullDisplayName' : u'build_war #87'
}

Jenkins.get_queue_info()

Returns

list of job dictionaries, [dict]

Example::

>>> j = Jenkins() >>> 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
}

Jenkins.cancel_queue(id)

Cancel a queued build.

Parameters

id — Jenkins job id number for the build, int

Jenkins.get_info()

Get information on this Master.

This information includes job list and view information.

Returns

dictionary of information about Master, dict

Example:

>>> j = Jenkins() >>> 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.get_version()

Get the version of this Master.

Returns

This master’s version number str

Example:

>>> j = Jenkins()
>>> info = j.get_version()
>>> print info
>>> 1.541

Jenkins.get_plugins_info(depth=2)

Get all installed plugins information on this Master.

This method retrieves information about each plugin that is installed on master.

Parameters

depth — JSON depth, int

Returns

info on all plugins [dict]

Example:

>>> j = Jenkins() >>> info = j.get_plugins_info() >>> print(info)
[{u’backupVersion’ : None, u’version’ : u’0.0.4′, u’deleted’ : False, u’supportsDynamicLoad’ : u’MAYBE’, u’hasUpdate’ : True, u’enabled’ : True, u’pinned’ : False, u’downgradable’ : False, u’dependencies’ : [], u’url’ : u’http://wiki.jenkins-ci.org/display/JENKINS/Gearman+Plugin’, u’longName’ : u’Gearman Plugin’, u’active’ : True, u’shortName’ : u’gearman-plugin’, u’bundled’ : False}, ..]

Jenkins.get_plugin_info(name, depth=2)

Get an installed plugin information on this Master.

This method retrieves information about a speicifc plugin. The passed in plugin name (short or long) must be an exact match.

Parameters

•

name — Name (short or long) of plugin, str

•

depth — JSON depth, int

Returns

a specific plugin dict

Example:

>>> j = Jenkins() >>> info = j.get_plugin_info(“Gearman Plugin”) >>> print(info)
{
u’backupVersion’ : None, u’version’ : u’0.0.4′, u’deleted’ : False, u’supportsDynamicLoad’ : u’MAYBE’, u’hasUpdate’ : True, u’enabled’ : True, u’pinned’ : False, u’downgradable’ : False, u’dependencies’ : [], u’url’ : u’http://wiki.jenkins-ci.org/display/JENKINS/Gearman+Plugin’, u’longName’ : u’Gearman Plugin’, u’active’ : True, u’shortName’ : u’gearman-plugin’, u’bundled’ : False
}

Jenkins.get_jobs()

Get list of jobs running.

Each job is a dictionary with ‘name’, ‘url’, and ‘color’ keys.

Returns

list of jobs, [ { str: str} ]

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

Jenkins.rename_job(from_name, to_name)

Rename an existing Jenkins job

Parameters

•

from_name — Name of Jenkins job to rename, str

•

to_name — New Jenkins job name, str

Jenkins.delete_job(name)

Delete Jenkins job permanently.

Parameters

name — Name of Jenkins job, str

Jenkins.enable_job(name)

Enable Jenkins job.

Parameters

name — Name of Jenkins job, str

Jenkins.disable_job(name)

Disable Jenkins job.

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

Parameters

name — Name of Jenkins job, str

Jenkins.job_exists(name)

Check whether a job exists

Parameters

name — Name of Jenkins job, str

Returns

True if Jenkins job exists

Jenkins.jobs_count()

Get the number of jobs on the Jenkins server

Returns

Total number of jobs, int

Jenkins.assert_job_exists(name, exception_message=’job[%s] does not exist’)

Raise an exception if a job does not exist

Parameters

•

name — Name of Jenkins job, str

•

exception_message — Message to use for the exception. Formatted with name

Throws

JenkinsException whenever the job does not exist

Jenkins.create_job(name, config_xml)

Create a new Jenkins job

Parameters

•

name — Name of Jenkins job, str

•

config_xml — config file text, str

Jenkins.get_job_config(name)

Get configuration of existing Jenkins job.

Parameters

name — Name of Jenkins job, str

Returns

job configuration (XML format)

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

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

Jenkins.build_job(name, parameters=None, token=None)

Trigger build job.

Parameters

•

name — name of job

•

parameters — parameters for job, or None, dict

•

token — Jenkins API token

Jenkins.run_script(script)

Execute a groovy script on the jenkins master.

Parameters

script — The groovy script, string

Returns

The result of the script run.

Example::

>>> j = Jenkins()
>>> info = j.run_script("println(Jenkins.instance.pluginManager.plugins)")
>>> print(info)
u'[Plugin:windows-slaves, Plugin:ssh-slaves, Plugin:translation,
Plugin:cvs, Plugin:nodelabelparameter, Plugin:external-monitor-job,
Plugin:mailer, Plugin:jquery, Plugin:antisamy-markup-formatter,
Plugin:maven-plugin, Plugin:pam-auth]'

Jenkins.stop_build(name, number)

Stop a running Jenkins build.

Parameters

•

name — Name of Jenkins job, str

•

number — Jenkins build number for the job, int

Jenkins.get_nodes()

Get a list of nodes connected to the Master

Each node is a dict with keys ‘name’ and ‘offline’

Returns

List of nodes, [ { str: str, str: bool} ]

Jenkins.get_node_info(name, depth=0)

Get node information dictionary

Parameters

•

name — Node name, str

•

depth — JSON depth, int

Returns

Dictionary of node info, dict

Jenkins.node_exists(name)

Check whether a node exists

Parameters

name — Name of Jenkins node, str

Returns

True if Jenkins node exists

Jenkins.assert_node_exists(name, exception_message=’node[%s] does not exist’)

Raise an exception if a node does not exist

Parameters

•

name — Name of Jenkins node, str

•

exception_message — Message to use for the exception. Formatted with name

Throws

JenkinsException whenever the node does not exist

Jenkins.delete_node(name)

Delete Jenkins node permanently.

Parameters

name — Name of Jenkins node, str

Jenkins.disable_node(name, msg=”)

Disable a node

Parameters

•

name — Jenkins node name, str

•

msg — Offline message, str

Jenkins.enable_node(name)

Enable a node

Parameters

name — Jenkins node name, str

Jenkins.create_node(name, numExecutors=2, nodeDescription=None, remoteFS=’/var/lib/jenkins’, labels=None, exclusive=False, launcher=’hudson.slaves.CommandLauncher’, launcher_params={})

Create a node

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

•

launcher — The launch method for the slave, jenkins.LAUNCHER_COMMAND, jenkins.LAUNCHER_SSH, jenkins.LAUNCHER_JNLP, jenkins.LAUNCHER_WINDOWS_SERVICE

•

launcher_params — Additional parameters for the launcher, dict

Jenkins.get_node_config(name)

Get the configuration for a node.

Parameters

name — Jenkins node name, str

Jenkins.reconfig_node(name, config_xml)

Change the configuration for an existing node.

Parameters

•

name — Jenkins node name, str

•

config_xml — New XML configuration, str

Jenkins.get_build_console_output(name, number)

Get build console text.

Parameters

•

name — Job name, str

•

name — Build number, int

Returns

Build console output, str

Jenkins.get_view_name(name)

Return the name of a view using the API.

That is roughly an identity method which can be used to quickly verify a view exists or is accessible without causing too much stress on the server side.

Parameters

name — View name, str

Returns

Name of view or None

Jenkins.assert_view_exists(name, exception_message=’view[%s] does not exist’)

Raise an exception if a view does not exist

Parameters

•

name — Name of Jenkins view, str

•

exception_message — Message to use for the exception. Formatted with name

Throws

JenkinsException whenever the view does not exist

Jenkins.view_exists(name)

Check whether a view exists

Parameters

name — Name of Jenkins view, str

Returns

True if Jenkins view exists

Jenkins.get_views()

Get list of views running.

Each view is a dictionary with ‘name’ and ‘url’ keys.

Returns

list of views, [ { str: str} ]

Jenkins.delete_view(name)

Delete Jenkins view permanently.

Parameters

name — Name of Jenkins view, str

Jenkins.create_view(name, config_xml)

Create a new Jenkins view

Parameters

•

name — Name of Jenkins view, str

•

config_xml — config file text, str

Jenkins.reconfig_view(name, config_xml)

Change configuration of existing Jenkins view.

To create a new view, see Jenkins.create_view().

Parameters

•

name — Name of Jenkins view, str

•

config_xml — New XML configuration, str

Jenkins.get_view_config(name)

Get configuration of existing Jenkins view.

Parameters

name — Name of Jenkins view, str

Returns

view configuration (XML format)

EXAMPLE USAGE

Example usage:


import jenkins 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') j.get_views() j.create_view('EMPTY', jenkins.EMPTY_VIEW_CONFIG_XML) j.view_exists('EMPTY') j.delete_view('EMPTY')
#build a parameterized job
#requires setting up api - test job to accept 'param1' & 'param2'
                                                                                                                                                                                                                                                                                                                                                                                                                                                     j.build_job('api-test', {'param1' : 'test value 1', 'param2' : 'test value 2' }) last_build_number = j.get_job_info('api-test')['lastCompletedBuild']['number'] build_info = j.get_job_info('api-test', last_build_number) print(build_info)

Look at the api for more details.

INSTALLING

The module is known to pip and Debian-based distributions as python-jenkins.

pip:

pip install python-jenkins

easy_install:

easy_install python-jenkins

The module has been packaged since Ubuntu Oneiric (11.10):

apt-get install python-jenkins

And on Fedora 19 and later:

yum install python-jenkins

For development:

python setup.py develop

Documentation

Documentation is included in the doc folder. To generate docs locally execute the command:

tox -e docs

The generated documentation is then available under doc/build/html/index.html.

Unit Tests

Unit tests have been included and are in the tests folder. We recently started including unit tests as examples in our documentation so to keep the examples up to date it is very important that we include unit tests for every module. To run the unit tests, execute the command:

tox -e py27

•: Note: View tox.ini to run tests on other versions of Python.

Test Coverage

To measure test coverage, execute the command:

tox -e cover

•: genindex
•: modindex
•: search

AUTHOR

Ken Conley, James Page, Tully Foote, Matthew Gertner

COPYRIGHT

2010, Willow Garage

pythonjenkins (1) Linux Manual Page

NAME

DEVELOPERS

WRITING A PATCH

INSTALLING WITHOUT SETUP.PY

API REFERENCE

EXAMPLE USAGE

INSTALLING

Documentation

Unit Tests

Test Coverage

AUTHOR

COPYRIGHT

Index

Leave a Reply Cancel reply