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 jobsBuild
- abstraction for an instance of a build of aparticular 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
ofJob
objects
-
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
-
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
-
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
-
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
-
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
-
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
-
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
ofNode
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
-
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
ofView
objects