pyjen.jenkins module

Primitives for interacting with the main Jenkins dashboard

class pyjen.jenkins.Jenkins(data_io_controller)

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 = Jenkins.easy_connect('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.easy_connect('http://localhost:8080/')
v = j.get_default_view()
jobs = v.get_jobs()
lgb = jobs[0].get_last_good_build()
print ('last good build of the first job in the default view is ' + lgb.get_build_number())

To instantiate an instance of this class using auto-generated configuration parameters, see the easy_connect() method

Parameters:data_io_controller (DataRequester) – class capable of handling common HTTP IO requests sent by this object to the Jenkins REST API

all_job_names

Gets list of all jobs found on this server

cancel_shutdown()

Cancels a previous scheduled shutdown sequence

Cancels a shutdown operation initiated by the prepare_shutdown() method

create_job(job_name, job_type)

Creates a new job on this Jenkins instance

Parameters:

• job_name (str) – The name for the job to be created. expected to be universally unique on this instance of Jenkins
• job_type (str) – descriptive type for the base configuration of this new job for a list of currently supported job types see job_types()

create_view(view_name, view_type)

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_type (str) – type of view to create must match one or more of the available view types supported by this Jenkins instance. See view_types() for a list of supported view types.

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

static easy_connect(url, credentials=None)

Factory method to simplify creating connections to Jenkins servers

Parameters:

• url (str) – Full URL of the Jenkins instance to connect to. Must be a valid running Jenkins instance.
• credentials (tuple) – A 2-element tuple with the username and password for authenticating to the URL If omitted, credentials will be loaded from any pyjen config files found on the system If no credentials can be found, anonymous access will be used

Returns:

Jenkins object, pre-configured with the appropriate credentials and connection parameters for the given URL.

Return type:

Jenkins

find_job(job_name)

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)

Locates a Jenkins build agent with the given name on this Jenkins instance

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)

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)

Searches views directly managed by this Jenkins instance for a specific view

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

flush_cache()

Flushes any pending writes to the remote Jenkins server

WARNING: This method interacts with a new, crude prototype caching system being tested and should not be used in production

get_job(url)

Establishes a connection to a Job based on an absolute URL

This method may be a bit less convenient to use in certain situations but it has better performance than find_job()

Parameters:url (str) – absolute URL of the job to load Returns:an instance of the appropriate Job subclass for the given job Return type:Job

get_node(url)

Loads data for a Jenkins build agent based on an absolute URL

This method may be a bit less convenient to use in certain situations but it has better performance than find_node()

Parameters:url (str) – absolute URL of the node data to load Returns:A node object allowing interaction with the given node’s settings and information Return type:Node

get_user(url)

Establishes a connection to a Jenkins User based on an absolute URL

This method may be a bit less convenient to use in certain situations but it has better performance than find_user()

Parameters:url (str) – absolute URL of the user to load Returns:A user object allowing interaction with the given user’s settings and information Return type:User

get_view(url)

Establishes a connection to a View based on an absolute URL

This method may be a bit less convenient to use in certain situations but it has better performance than find_view()

Parameters:url (str) – absolute URL of the view to load Returns:an instance of the appropriate View subclass for the given view Return type:View

is_shutting_down

checks to see whether 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

job_types

Returns:a list of Jenkins job types currently supported by this instance of PyJen Elements from this list may be used when creating new jobs on this Jenkins instance, so long as the accompanying job type is supported by the live Jenkins server Return type:list of str

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

prepare_shutdown()

Sends a shutdown signal to the Jenkins master preventing 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

reset_cache()

Resets all cached data

WARNING: Any unwritten changes to the cache will be lost if not flushed previously using the flush_cache() method

WARNING: This method interacts with a new, crude prototype caching system being tested and should not be used in production

version

Gets the version of Jenkins pointed to by this object

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

view_names

Gets a list of the names of the views managed by this Jenkins instance

Return type:list of View objects

view_types

Returns:a list of Jenkins view types currently supported by this instance of PyJen Elements from this list may be used when creating new views on this Jenkins instance, so long as the accompanying view type is supported by the live Jenkins server Return type:list of str

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