pyjen.jenkins module

Primitives for interacting with the main Jenkins dashboard

class pyjen.jenkins.Jenkins(url, session)[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, Job and Build.

Parameters

url (str) – URL of the Jenkins service to connect to
session (requests.Session) – pre-configured HTTP session to use for communicating to the Jenkins REST API. This session may be user defined, or built using one of the factory methods associated with this class such as basic_auth().

property all_jobs

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.

Type: list (Job)

classmethod basic_auth(url, credentials=None, ssl_cert=None)[source]

Factory method used to instantiate a connection to a Jenkins server using HTTP basic auth protocol

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 (str) – 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.

Returns

instance of this class, preconfigured to connect to the specified Jenkins service using an HTTP basic auth connection

Return type

Jenkins

property build_queue

interface for managing the Jenkins build queue

Type: Queue

cancel_shutdown()[source]

Cancels a previous scheduled shutdown sequence

Cancels a shutdown operation initiated by the prepare_shutdown() method

property connected

True if API still connected to the service, False if not

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

property default_view

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, but this may be customized by the user at runtime.

Type: View

find_job(job_name)[source]

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

Some plugins allow jobs to be nested within other jobs. To perform a recursive search across all such entities, see all_jobs().

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, or None if no node with the given name can be found
Return type: Node

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, or None if no user with the specified name can be found
Return type: User

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 returns None
Return type: View

property is_shutting_down

True if the Jenkins master is scheduled for a shutdown, False if not

Type: bool

property jobs

all jobs managed by this Jenkins instance

Type: list (Job)

property nodes

list of build agents

Type: list (Node)

property plugin_manager

interface for managing the plugins installed on this Jenkins instance

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

property version

version of Jenkins service, parsed into a tuple of integers

Type: tuple

property views

all views directly managed by this Jenkins instance

Type: list (View)