pyjen.job module¶

Primitives for interacting with Jenkins jobs

class pyjen.job.Job(api)[source]¶

Bases: object

Abstraction for operations common to all job types on Jenkins

Parameters: api (/utils/jenkins_api/JenkinsAPI) – Pre-initialized connection to the Jenkins REST API

add_property(new_property)[source]¶

Adds a new job property to the configuration

Parameters: new_property – Custom job property to be added. May be any PyJen plugin that supports the Jenkins job property plugin API.

all_builds¶

Gets all recorded builds for this job

Returns: all recorded builds for this job
Return type: list of Build objects

build_health¶

Gets the percentage of good builds from recorded history of this job

This metric is associated with the “weather” icon that can be shown next to jobs in certain views

Returns: percentage of good builds on record for this job
Return type: int

clone(new_job_name, disable=True)[source]¶

“Create a new job with the same configuration as this one

Parameters

new_job_name (str) – Name of the new job to be created
disable (bool) – Indicates whether the newly created job should be disabled after creation to prevent builds from accidentally triggering immediately after creation

Returns

reference to the newly created job

Return type

pyjen.job.Job

config_xml¶

Gets the raw XML configuration for the job

Allows callers to manipulate the raw job configuration file as desired.

Returns: the full XML tree describing this jobs configuration
Return type: str

delete()[source]¶: Deletes this job from the Jenkins dashboard

disable()[source]¶

Disables this job

Sets the state of this job to disabled so as to prevent the job from being triggered.

Use in conjunction with enable() and is_disabled to control the state of the job.

enable()[source]¶

Enables this job

If this jobs current state is disabled, it will be re-enabled after calling this method. If the job is already enabled then this method does nothing.

Enabling a job allows it to be triggered, either automatically via commit hooks / polls or manually through the dashboard.

Use in conjunction with disable() and is_disabled to control the state of the job

find_build_by_queue_id(queue_id)[source]¶

Gets the build of this job which correlates to a specific queue item

Parameters: queue_id (int) – ID of the build queue item to correlate with. Typically extracted from the pyjen.queue_item.QueueItem.id() property.
Returns: reference to the build associated with the specified queue id None if no such reference exsts

get_build_by_number(build_number)[source]¶

Gets a specific build of this job from the build history

Parameters: build_number (int) – Numeric identifier of the build to retrieve Value is typically non-negative
Returns: Build object for the build with the given numeric identifier If such a build does not exist, returns None
Return type: Build

get_builds_in_time_range(start_time, end_time)[source]¶

Returns a list of all of the builds for a job that occurred between the specified start and end times

Parameters

start_time (datetime) – starting time index for range of builds to find
end_time (datetime) – ending time index for range of builds to find

Returns

a list of 0 or more builds

Return type

list of Build objects

classmethod get_supported_plugins()[source]¶

Returns a list of PyJen plugins that derive from this class

Return type: list of class

has_been_built¶

Checks to see whether this job has ever been built or not

Returns: True if the job has been built at least once, otherwise false
Return type: bool

static instantiate(json_data, rest_api)[source]¶

Factory method for finding the appropriate PyJen view object based on data loaded from the Jenkins REST API

Parameters

json_data (dict) – data loaded from the Jenkins REST API summarizing the view to be instantiated
rest_api – PyJen REST API configured for use by the parent container. Will be used to instantiate the PyJen view that is returned.

Returns

PyJen view object wrapping the REST API for the given Jenkins view

Return type

View

is_disabled¶

Indicates whether this job is disabled or not

Returns: True if the job is disabled, otherwise False
Return type: bool

is_failing¶

Indicates whether the current state of the job is ‘failed’

Returns: True if the latest build of the job is a failure, otherwise False
Return type: bool

is_unstable¶

Indicates whether the current state of this job is ‘unstable’

Returns: True if the latest build of the job is unsable, otherwise False
Return type: bool

jenkins_plugin_name¶

Extracts the name of the Jenkins plugin associated with this job

The data returned by this helper property is extracted from the config XML that defines this job.

Return type: str

last_build¶

Returns a reference to the most recent build of this job

Synonymous with the “Last Build” permalink on the jobs’ main status page

Returns: object that provides information and control for the most recent build of this job. If there are no such builds in the build history, this method returns None
Return type: Build

last_failed_build¶

the most recent build of this job with a status of “failed”

Synonymous with the “Last failed build” permalink on the jobs’ main status page

Returns: Most recent build with a status of ‘failed’. If there are no such builds in the build history, this method returns None
Return type: Build

last_good_build¶

Gets the most recent successful build of this job

Synonymous with the “Last successful build” permalink on the jobs’ main status page

Returns: object that provides information and control for the last build which completed with a status of ‘success’ If there are no such builds in the build history, this method returns None
Return type: Build

last_stable_build¶

the most recent build of this job with a status of “stable”

Synonymous with the “Last stable build” permalink on the jobs’ main status page

Returns: Most recent build with a status of ‘stable’. If there are no such builds in the build history, this method returns None
Return type: Build

last_unsuccessful_build¶

the most recent build of this job with a status of “unstable”

Synonymous with the “Last unsuccessful build” permalink on the jobs’ main status page

Returns: Most recent build with a status of ‘unstable’ If there are no such builds in the build history, this method returns None
Return type: Build

name¶

Returns the name of the job managed by this object

Returns: The name of the job
Return type: str

properties¶: all plugins configured as extra configuration properties

recent_builds¶

Gets a list of the most recent builds for this job

Rather than returning all data on all available builds, this method only returns the latest 20 or 30 builds. This list is synonymous with the short list provided on the main info page for the job on the dashboard.

Returns: a list of the most recent builds for this job
Return type: list of Build objects

rename(new_job_name)[source]¶

Changes the name of this job

Parameters: new_job_name (str) – new name to assign to this job

start_build(**kwargs)[source]¶

Forces a build of this job

Synonymous with a manual trigger. A new instance of the job (ie: a build) will be added to the appropriate build queue where it will be scheduled for execution on the next available agent + executor.

Parameters: kwargs – 0 or more named arguments to pass as build parameters to the job when triggering the build.