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.
-
enable_ftp
(host, username='', password='', port=0)[source]¶ enable ftp server and set host, username, password, port.
-
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.
-
jobs
¶ get container of all jobs.
-
nodes
¶ get nodes.
-
class