pyjen.job module

Primitives for interacting with Jenkins jobs

class pyjen.job.Job(controller, jenkins_master)

Bases: pyjen.utils.plugin_base.PluginBase

‘Abstract’ base class used by all job classes, providing functionality common to them all

Parameters:

• controller (DataRequester) – IO interface which manages interaction with the live Jenkins job
• jenkins_master (Jenkins) – Jenkins instance containing this job

all_builds

Gets all recorded builds for this job

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

all_downstream_jobs

Gets the list of all jobs that depend on this job, including all indirect descendants

Includes jobs triggered by this job, and all jobs triggered by those jobs, recursively for all downstream dependencies

Returns:A list of 0 or more jobs which depend on this one Return type:list of Job objects

all_upstream_jobs

Gets the list of all jobs that this job depends on, including all indirect descendants

Includes jobs that trigger this job, and all jobs trigger those jobs, recursively for all upstream dependencies

Returns:A list of 0 or more jobs this job depend on Return type:list of Job objects

builders

Gets all plugins configured as ‘builders’ for this job

clone(new_job_name)

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

Parameters:new_job_name (str) – Name of the new job to be created

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

static create(controller, jenkins_master)

Factory method used to instantiate the appropriate job type for a given configuration

Parameters:

• controller (DataRequester) – IO interface to the Jenkins API. This object is expected to be pre-initialized with the connection parameters for the job to be processed.
• jenkins_master (Jenkins) – Jenkins instance containing this job

Returns:

An instance of the appropriate derived type for the given job

Return type:

Job

delete()

Deletes this job from the Jenkins dashboard

disable()

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.

downstream_jobs

Gets the list of jobs to be triggered after this job completes

Returns:A list of 0 or more jobs which depend on this one Return type:list of Job objects

enable()

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

get_build_by_number(build_number)

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)

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

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

is_disabled

Indicates whether this job is disabled or not

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

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

Returns a reference to 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

Returns a reference to 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

Returns a reference to 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

Gets all plugins configured as extra configuration properties for this job

publishers

Gets all plugins configured as ‘publishers’ for this job

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

start_build()

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.

static supported_types()

Returns a list of all job types supported by this instance of PyJen

These job types can be used in such methods as create_job(), which take as input a job type classifier

Returns:list of all job types supported by this instance of PyJen, including those supported by plugins Return type:str

static template_config_xml(job_type)

Generates a generic configuration file for use when creating a new job on the live Jenkins instance

Parameters:job_type (str) – the type descriptor of the job being created For valid values see the supported_types() method Returns:XML configuration data for the specified job type Return type:str

upstream_jobs

Gets the list of upstream dependencies for this job

Returns:A list of 0 or more jobs that this job depends on Return type:list of Job objects

url

Returns the URL to the job

Returns:The URL of the job Return type::class:’str’