pyjen.jenkins module¶

Primitives for interacting with the main Jenkins dashboard

class pyjen.jenkins.Jenkins(url, credentials=None, ssl_cert=True)[source]¶

Bases: object

Python wrapper managing the Jenkins primary dashboard

Generally you should use this class as the primary entry point to the PyJen APIs. Finer grained control of each aspect of the Jenkins dashboard is then provided by the objects exposed by this class including:

View - abstraction for a view on the dashboard, allowing jobs to be filtered based on different criteria like job name.
Job - abstraction for a Jenkins job, allowing manipulation of job settings and controlling builds of those jobs
Build - abstraction for an instance of a build of a
particular job

Example: finding a job

j = pyjen.Jenkins('http://localhost:8080')
job = j.find_job('My Job')
if job is None:
    print ('no job by that name found')
else:
    print ('job ' + job.name + ' found')

Example: find the build number of the last good build of the first job: on the default view

j = pyjen.Jenkins(‘http://localhost:8080/’) v = j.get_default_view() jobs = v.get_jobs() lgb = jobs[0].last_good_build print (‘last good build of the first job in the default view is ‘ +

lgb.get_build_number())

Parameters

url (str) – Full HTTP URL to the main Jenkins dashboard
credentials (tuple) – Optional 2-tuple containing the username and password / api key to authenticate with. If not provided, anonymous access will be assumed
ssl_cert – Passed directly to the requests library when authenticating to the remote server. Maybe be a boolean indicating whether SSL verification is enabled or disabled, or may be a path to a certificate authority bundle.

all_jobs¶

Gets all jobs managed by this Jenkins instance, recursively

Unlike the jobs() method, this method attempts to expose jobs which are managed by custom jobs created from third party plugins which support nesting jobs under sub-folders / sub-paths. Any job which exposes a custom ‘jobs’ property.

Return type: list of Job objects

build_queue¶

object that describes / manages the queued builds

Return type: Queue

cancel_shutdown()[source]¶

Cancels a previous scheduled shutdown sequence

Cancels a shutdown operation initiated by the prepare_shutdown() method

connected¶

make sure the connection to the Jenkins REST API was successful

Returns: True if connected, false if not
Return type: bool

create_job(job_name, job_class)[source]¶

Creates a new job on the Jenkins dashboard

Parameters

job_name (str) – the name for this new job This name should be unique, different from any other jobs currently managed by the Jenkins instance
job_class – PyJen plugin class associated with the type of job to be created

Returns

An object to manage the newly created job

Return type

Job

create_view(view_name, view_class)[source]¶

Creates a new view on the Jenkins dashboard

Parameters

view_name (str) – the name for this new view This name should be unique, different from any other views currently managed by the Jenkins instance
view_class – PyJen plugin class associated with the type of view to be created

Returns

An object to manage the newly created view

Return type

View

default_view¶

returns a reference to the primary / default Jenkins view

The default view is the one displayed when navigating to the main URL. Typically this will be the “All” view.

Returns: object that manages the default Jenkins view
Return type: View

find_job(job_name)[source]¶

Searches all jobs managed by this Jenkins instance for a specific job

Parameters: job_name (str) – the name of the job to search for
Returns: If a job with the specified name can be found, and object to manage the job will be returned, otherwise None
Return type: Job

find_node(nodename)[source]¶

Locates a Jenkins build agent with the given name

Parameters: nodename (str) – name of node to locate
Returns: reference to Jenkins object that manages this node’s information.
Return type: Node or None if node not found

find_user(username)[source]¶

Locates a user with the given username on this Jenkins instance

Parameters: username (str) – name of user to locate
Returns: reference to Jenkins object that manages this users information.
Return type: User or None if user not found

find_view(view_name)[source]¶

Searches views for a specific one

Parameters: view_name (str) – the name of the view to search for
Returns: If a view with the specified name can be found, an object to manage the view will be returned, otherwise None
Return type: View

is_shutting_down¶

Is the Jenkins master is in the process of shutting down.

Returns: If the Jenkins master is preparing to shutdown (ie: in quiet down state), return True, otherwise returns False.
Return type: bool

jobs¶

Gets all jobs managed by this Jenkins instance

Return type: list of Job objects

nodes¶

gets the list of nodes (aka: agents) managed by this Jenkins master

Returns: list of 0 or more Node objects managed by this Jenkins master
Return type: list of Node objects

plugin_manager¶

object which manages the plugins installed on this Jenkins

Returns: reference to Jenkins object that manages plugins on this instance
Return type: PluginManager

prepare_shutdown()[source]¶

Starts a “quiet down” and prevents new builds from executing

Analogous to the “Prepare for Shutdown” link on the Manage Jenkins configuration page

You can cancel a previous requested shutdown using the cancel_shutdown() method

version¶

Gets the version of Jenkins pointed to by this object

Returns: Version number of the currently running Jenkins instance
Return type: tuple

views¶

Gets a list of all views directly managed by the Jenkins dashboard

To retrieve all views managed by this Jenkins instance, including recursing into views that support sub-views, see the all_views() property

Returns: list of one or more views defined on this Jenkins instance.
Return type: list of View objects