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 (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 (XMLPlugin) – Custom job property to be added. May be any PyJen plugin that supports the Jenkins job property plugin API.

property all_builds

all recorded builds for this job

Type: list (Build)

property build_health

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

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

Job

property config_xml

raw XML configuration for the job

Allows callers to manipulate the raw job configuration definition without relying on the PyJen abstractions.

Warning

For advanced use only.

Type: str

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

disable()[source]

Disables this job to prevent new builds from being executed

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]

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 uid() property.
Returns: reference to the build associated with the specified queue id or None if no such build exists
Return type: Build

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: Reference to the build with the given numeric identifier, or None if no such build exists
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.datetime) – starting time index for range of builds to find
end_time (datetime.datetime) – ending time index for range of builds to find

Returns

list of 0 or more builds of this job that began during the time range provided

Return type

list (Build)

classmethod get_supported_plugins()[source]: list: list of PyJen plugin classes that derive from this class

property has_been_built

True if the job has been built at least once, otherwise False

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 (JenkinsAPI) – PyJen REST API configured for use by the parent container. Will be used to instantiate the PyJen view that is returned.

Returns

PyJen job object wrapping the REST API for the given job

Return type

Job

property is_disabled

True if the job is disabled, otherwise False

Type: bool

property is_failing

True if the latest build of the job is a failure, otherwise False

Type: bool

property is_unstable

True if the latest build of the job is unstable, otherwise False

Type: bool

property jenkins_plugin_name

Extracts the name of the Jenkins plugin providing the features associated with this job. May reference any number of third party plugins supported by the Jenkins instance being managed.

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

Type: str

property last_build

the most recent build of this job

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

Type: Build

property 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

Type: Build

property last_good_build

the most recent successful build of this job

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

Type: Build

property 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

Type: Build

property 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

Type: Build

property name

the name of the Jenkins job

Type: str

property properties

custom properties associated with this job, typically describing features of the job provided by third party plugins

Type: list (XMLPlugin)

property recent_builds

list of the most recent builds of 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.

Type: list (Build)

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 (dict) – 0 or more named arguments to pass as build parameters to the job when triggering the build.
Returns: Reference to the Jenkins queue item that tracks the progress of the triggered build prior to the build actually running.
Return type: QueueItem