cup.jenkinslib package

Subpackages

Module contents

Library for jenkins.

You can use Jenkins to access your jenkins server easily.

This library uses defensive programming with EAFP principle. Kinds of exceptions based on jenkins.Error may be raise. You should use this library with try … except.

Authors: liushuxian(liushuxian) Date: 2015/01/21

usage:

import cup
import cup.jenkinslib

############### quick start ###############
jenkins = cup.jenkinslib.Jenkins('cup.jenkins.baidu.com')

job = jenkins['cup_quick']
print job.name, job.last_stable_build_number, job.description
print job[5], job["lastSuccessBuild"], job.last_stable_build

qi = job.invoke()
build = qi.block_until_building()
print build.name, build.number, build.timestamp

try:
    build.block_until_complete(timeout=20)
except cup.jenkinslib.RunTimeout as err:
    print "timeout:", err
    build.stop()

print build.duration, build.result, build.description

build.description = "new description"

jenkins.enable_ftp('ftp.baidu.com', 'cup', 'password', 22)
with build.ftp_artifacts as af:
    af['artifacts_path'].download('./local_path')
class cup.jenkinslib.Jenkins(url, username=None, password=None, static=False)[source]

Bases: cup.jenkinslib.internal.base.JenkinsBase

Represents a jenkins server.

class Artifacts(build, name='', path='', is_dir=True)

Bases: cup.jenkinslib.internal.artifacts.ArtifactsBase

Represents artifacts, file or directory.

class Build(url, build_number, job, depth=None)

Bases: cup.jenkinslib.internal.base.JenkinsBase

Represents a build.

actions

get actions of build.

artifacts

get artifacts object of build.

block()

block until this build stop running.

Do not use this method too often, because it will request jenkins server every second.

block_until_complete(delay=15, timeout=None)

block until this build stop running.

Args:
delay: check status every delay seconds, default is 15s. timeout: wait timeout seconds at most, default is forever.
Returns:
True if stopped, False if still running.
cause_description

get short description of causes.

causes

get causes of build, empty causes will be ignored.

changeset

get changeset info, only support svn.

console

get text console of build.

description

get description of build if exists, otherwise None.

Returns:
description info of this build, encoding in utf-8. return None if not exists.
duration

get build duration(s).

duration_ms

get build duration(ms).

ftp_artifacts

get ftp artifacts object of build.

get_jenkins_obj()

get object of current jenkins.

is_running

check build is running or not.

is_started_by_scm_change

check if is started by an SCM change.

is_started_by_timer

check if is started by timer.

is_started_by_upstream_project

check if is started by upstream project.

is_started_by_user

check if is started by user.

is_success

check build is success or not, return False if is running.

name

get build name.

number

get build number.

promote(name)

force promotion by name.

result

get build result.

revision

get latest revision, only support svn.

revisions

get all revisions info, only support svn.

stop()

Stops the build execution if it’s running.

timestamp

get build timestamp.

upstream_build

get upstream build object if exists, otherwise None.

upstream_build_number

get upstream build number if exists, otherwise None.

upstream_job

get upstream job object if exists, otherwise None.

upstream_job_name

get upstream job name if exists, otherwise None.

user_id

get id of user who invoke this build if exists, otherwise None.

user_name

get name of user who invoke this build if exists, otherwise None.

class FTPArtifacts(build, name='', path='', is_dir=True)

Bases: cup.jenkinslib.internal.artifacts.ArtifactsBase

Represents artifacts on FTP.

Because ftp connection is used, close should be called if connected. It is recommended to use with as like:

with FTPArtifacts(build) as af:
bin_af = af[“bin”] bin_af.download(“./output”)
close()

close ftp connection.

connect()

connect to ftp, return ftp connection.

url

get ftp artifact url.

class Job(url, name, jenkins)

Bases: cup.jenkinslib.internal.base.JenkinsBase

Represents a job.

build(block=False, build_params=None, cause=None, files=None, delay=15)

trigger a new build.

Args:
block: block until the new build stopped. build_params: trigger new build with params. cause: set cause info. files: send build params in files. delay: if block is True, check status every delay seconds.
builds

get container of all builds.

config

get config element tree object of job.

config_text

get config.xml text of job.

Returns:
config.xml text in Unicode type. You can encode it in ‘utf-8’ or ‘gb18030’.
description

get description of job.

disable()

disable job.

downstream_job_names

get list of downstream job names.

downstream_jobs

get list of downstream job objects.

enable()

enable job.

first_build

get first build.

first_build_number

get number of first build.

get_build(build_number, depth=None)

get build by number.

Also support special build:
firstBuild lastBuild lastStableBuild lastSuccessfulBuild lastCompletedBuild lastFailedBuild
get_build_trigger_url(files)

get trigger url of job.

get_delete_url()

get delete url of job.

get_jenkins_obj()

get object of current jenkins.

get_rename_url()

get rename url of job.

has_params

check build has params or not.

invoke(block=False, build_params=None, cause=None, files=None, delay=15)

trigger a new build.

Args:
block: block until the new build stopped. build_params: trigger new build with params. cause: set cause info. files: send build params in files. delay: if block is True, check status every delay seconds.
is_enabled

check if job is enabled.

is_queued

check job is queued or not.

is_queued_or_running

check job is queued/running or not.

is_running

check job is running or not.

last_build

get last build.

last_build_number

get number of last build.

last_completed_build

get last completed build.

last_completed_build_number

get number of last completed build.

last_failed_build

get last failed build.

last_failed_build_number

get number of last failed build.

last_stable_build

get last stable build.

last_stable_build_number

get number of last stable build.

last_successful_build

get last successful build.

last_successful_build_number

get number of last successful build.

static mk_json_from_build_parameters(build_params, file_params=None)

make build parameters to json format.

next_build_number

get number of next build.

promotions

get promotions of job.

upstream_job_names

get list of upstream job names.

upstream_jobs

get list of upstream job objects.

class Jobs(jenkins)

Bases: object

A container of Job objects.

create(job_name, config)

create new job.

Args:
job_name: name of new job. config: configure for new job, xml text.
Returns:
new job object.
iterkeys()

get all job name.

keys()

get all job name.

rename(job_name, new_job_name)

rename a job.

Args:
job_name: name of a existing job. new_job_name: new job name.
Returns:
new job object.
class Label(label, jenkins)

Bases: cup.jenkinslib.internal.base.JenkinsBase

A container of Node objects.

busy_node_num

busy node num.

get_jenkins_obj()

get object of current jenkins.

get_node_url(node_name)

get url of node.

Args:
node_name: node name.
Returns:
node url.
is_online

label is online or not.

iteritems()

get all nodes.

iterkeys()

get all node name.

keys()

get all node name.

node_num

get node num.

tied_job_num

get tied job num.

tied_jobs

get all tied job name on this label.

tied_jobs_iterator

get all tied job name on this label.

class Node(url, name, jenkins)

Bases: cup.jenkinslib.internal.base.JenkinsBase

Represents a node.

get_jenkins_obj()

get object of current jenkins.

is_idle

node is idle or not.

is_online

node is online or not.

is_temporarily_offline

node is temporarily offline or not.

class Nodes(jenkins)

Bases: cup.jenkinslib.internal.base.JenkinsBase

A container of Node objects.

get_jenkins_obj()

get object of current jenkins.

get_node_url(node_name)

get url of node.

Args:
node_name: node name.
Returns:
node url.
iteritems()

get all nodes.

iterkeys()

get all node name.

keys()

get all node name.

class Promotion(url, name, job)

Bases: cup.jenkinslib.internal.base.JenkinsBase

Represents a promotion.

builds

get container of all builds.

description

get description of promotion.

first_build

get first build.

first_build_number

get number of first build.

get_build(build_number, depth=None)

get build by number.

Also support special build:
firstBuild lastBuild lastStableBuild lastSuccessfulBuild lastCompletedBuild lastFailedBuild
get_jenkins_obj()

get object of current jenkins.

is_queued

check promotion is queued or not.

is_queued_or_running

check promotion is queued/running or not.

is_running

check promotion is running or not.

last_build

get last build.

last_build_number

get number of last build.

last_completed_build

get last completed build.

last_completed_build_number

get number of last completed build.

last_failed_build

get last failed build.

last_failed_build_number

get number of last failed build.

last_stable_build

get last stable build.

last_stable_build_number

get number of last stable build.

last_successful_build

get last successful build.

last_successful_build_number

get number of last successful build.

next_build_number

get number of next build.

class PromotionBuild(url, build_number, promotion, depth=None)

Bases: cup.jenkinslib.internal.base.JenkinsBase

Represents a promotion build.

actions

get actions of build.

block()

block until this build stop running.

Do not use this method too often, because it will request jenkins server every second.

block_until_complete(delay=15, timeout=None)

block until this build stop running.

Args:
delay: check status every delay seconds, default is 15s. timeout: wait timeout seconds at most, default is forever.
Returns:
True if stopped, False if still running.
cause_description

get short description of causes.

causes

get causes of build, empty causes will be ignored.

console

get text console of build.

description

get description of build if exists, otherwise None.

Returns:
description info of this build, encoding in utf-8. return None if not exists.
duration

get build duration(s).

duration_ms

get build duration(ms).

get_jenkins_obj()

get object of current jenkins.

is_running

check build is running or not.

is_started_by_scm_change

check if is started by an SCM change.

is_started_by_timer

check if is started by timer.

is_started_by_upstream_project

check if is started by upstream project.

is_started_by_user

check if is started by user.

is_success

check build is success or not, return False if is running.

job_build

get Build object of target job build.

job_build_number

get build number of target job build.

name

get build name.

number

get build number.

result

get build result.

revision

get latest revision, only support svn.

stop()

Stops the build execution if it’s running.

timestamp

get build timestamp.

user_name

get name of user who invoke this build if exists, otherwise None.

class Promotions(job, depth=None)

Bases: cup.jenkinslib.internal.base.JenkinsBase

A container of Promotions objects.

get_jenkins_obj()

get object of current jenkins.

iterkeys()

get all promotion name.

keys()

get all promotion name.

class Requester(username=None, password=None)

Bases: object

A class which help you access jenkins.

VALID_STATUS_CODES = [200]
get(url, params=None, headers=None, allow_redirects=True)

request url in GET method.

Returns:
Response object.
get_and_confirm_status(url, params=None, headers=None, valid=None)

request url in GET method, and check status code.

Returns:
Response object.
post(url, params=None, data=None, files=None, headers=None, allow_redirects=True)

request url in POST method.

Returns:
Response object.
post_and_confirm_status(url, params=None, data=None, files=None, headers=None, valid=None, allow_redirects=True)

request url in POST method, and check status code.

Returns:
Response object.
post_xml_and_confirm_status(url, params=None, data=None, valid=None)

request url in POST method with text/xml context, and check status code.

Returns:
Response object.
create_job(job_name, config)[source]

create a new job.

create a new job named ‘job_name’. same as self.jobs[‘job_name’] = config.

Args:
job_name: name of new job. config: configure for new job, xml text.
Returns:
new job object.
delete_job(job_name)[source]

delete a job by name.

Args:
job_name: job name.
enable_ftp(host, username='', password='', port=0)[source]

enable ftp server and set host, username, password, port.

get_create_url()[source]

url for creating job.

static get_jenkins_by_name(name)[source]

get special jenkins class by name.

Args:
name: name of jenkins server.
Returns:
special jenkins class or Jenkins.
static get_jenkins_by_url(url)[source]

get special jenkins class by url.

Args:
url: url of jenkins server.
Returns:
special jenkins class or Jenkins.
get_jenkins_obj()[source]

get object of current jenkins.

get_job(job_name)[source]

get job by name.

get_label(label)[source]

get label by name.

get_node(node_name)[source]

get node by name.

has_job(job_name)[source]

job exists or not.

jobs

get container of all jobs.

nodes

get nodes.

static register_special_jenkins(url, cls)[source]

register special jenkins.

Args:
url: url of jenkins server. cls: special jenkins class.
rename_job(job_name, new_job_name)[source]

rename a job.

Args:
job_name: name of a existing job. new_job_name: new job name.
Returns:
new job object.