pyjen.jenkins module¶
Primitives for interacting with the main Jenkins dashboard
- class pyjen.jenkins.Jenkins(data_io_controller)[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 = 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 - cancel_shutdown()[source]¶
Cancels a previous scheduled shutdown sequence
Cancels a shutdown operation initiated by the prepare_shutdown() method
- create_view(view_name, view_type)[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_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:
- default_view[source]¶
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)[source]¶
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:
- 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 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)[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 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()[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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)[source]¶
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[source]¶
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[source]¶
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[source]¶
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()[source]¶
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()[source]¶
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[source]¶
Gets the version of Jenkins pointed to by this object
Returns: Version number of the currently running Jenkins instance Return type: str
- view_names[source]¶
Gets a list of the names of the views managed by this Jenkins instance
Return type: list of View objects
- view_types[source]¶
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[source]¶
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