jenkins_pysdk package

Submodules

jenkins_pysdk.jenkins module

Bases: Core

This is the main class for interacting with your Jenkins instance.

Parameters:

host (str) – The hostname/IP/DNS of the Jenkins instance.
username (str, optional) – The username for authentication. Defaults to None.
passw (str, optional) – The password for authentication. Defaults to None.
token (str, optional) – The API token for authentication. Defaults to None.
verify (bool, optional) – Enable or disable SSL verification. Defaults to True.
proxies (dict, optional) – Specify a proxy for routing requests. Supports both HTTP and HTTPS. Defaults to None.
port (int, optional) – The port number for connecting to the Jenkins instance. Defaults to 443.
timeout (int, optional) – Specify the connection timeout in seconds. Defaults to 30.

property Folder: Folders

Flag used to create Folder in Folders.create() or Folder.create() method.

Returns:: Flag for creating Folder
Return type:: jenkins_pysdk.objects.Flags.Jobs

property FreeStyle: Jobs

Flag used to create FreeStyle jobs in Jobs.create() method.

Returns:: Flag for creating FreeStyle jobs
Return type:: jenkins_pysdk.objects.Flags.Jobs

property ListView: Views

Flag used to create a ListView View in Views.create() method.

Returns:: Flag for creating a ListView View
Return type:: jenkins_pysdk.objects.Flags.Views

property MultiBranchPipeline: Jobs

Flag used to create MultiBranchPipeline jobs in Jobs.create() method.

Returns:: Flag for creating MultiBranchPipeline jobs
Return type:: jenkins_pysdk.objects.Flags.Jobs

property MultiConfigurationProject: Jobs

Flag used to create multi-configuration project jobs in Jobs.create() method.

Returns:: Flag for creating multi-configuration project jobs
Return type:: jenkins_pysdk.objects.Flags.Jobs

property MyView: Views

Flag used to create a MyView View in Views.create() method.

Returns:: Flag for creating a MyView View
Return type:: jenkins_pysdk.objects.Flags.Views

property OrganizationFolder: Folders

Flag used to create OrganizationFolder in Folders.create() or Folder.create() method.

Returns:: Flag for creating OrganizationFolder
Return type:: jenkins_pysdk.objects.Flags.Jobs

property Pipeline: Jobs

Flag used to create Pipeline jobs in Jobs.create() method.

Returns:: Flag for creating Pipeline jobs
Return type:: jenkins_pysdk.objects.Flags.Jobs

api(query: str)[source]

Run a custom query and return the relevant data objects.

Returns:: Data objects representing the resource requested.

property available_executors: int

View the number of available executors on the instance.

Returns:: Number of available executors
Return type:: int
Raises:: JenkinsGeneralException – If a general exception occurs.

connect() → JenkinsConnectObject[source]

Test the connection to the Jenkins instance.

Returns:

Object containing connection information.

Return type:

jenkins_pysdk.objects.JenkinsConnectObject

Raises:

JenkinsConnectionException – If a connection exception occurs.
JenkinsUnauthorisedException – If the credentials aren’t valid.

property credentials: Credentials

Retrieve information about credentials.

Returns:: A Credentials object representing the credentials on the system.
Return type:: jenkins_pysdk.credentials.Credentials

property executor_info: str

View information about the setup executors on the instance.

Returns:: Information about the setup executors
Return type:: str
Raises:: JenkinsGeneralException – If a general exception occurs.

property executors_in_use: str

View the executors that are currently being used on the instance.

Returns:: Information about the executors in use
Return type:: str
Raises:: JenkinsGeneralException – If a general exception occurs.

property folders: Folders

Retrieve information about folders.

Returns:: A Folders object representing the folders on the system.
Return type:: jenkins_pysdk.jobs.Folders

property idle_executors: int

View the number of idle executors on the instance.

Returns:: Number of idle executors
Return type:: int
Raises:: JenkinsGeneralException – If a general exception occurs.

property jobs: Jobs

Retrieve information about jobs.

Returns:: A Jobs object representing the jobs on the system.
Return type:: jenkins_pysdk.jobs.Jobs

logout(boot: bool = False) → JenkinsActionObject[source]

Terminate the user’s session.

Parameters:: boot (bool) – (Default: False) If True, terminate all the users’ sessions. (Caution if it’s a service account!)
Returns:: Result of the logout request
Return type:: jenkins_pysdk.objects.JenkinsActionObject

property max_executors: int

View the total number of executors on the instance.

Returns:: Total number of executors
Return type:: int
Raises:: JenkinsGeneralException – If a general exception occurs.

property max_queue_size: int

View the maximum queue size on the instance.

Returns:: Maximum queue size
Return type:: int
Raises:: JenkinsGeneralException – If a general exception occurs.

property me: User

Retrieve information about the authenticated user.

Returns:: Information about the authenticated user
Return type:: jenkins_pysdk.users.User

property nodes: Nodes

Retrieve information about nodes.

Returns:: A Nodes object representing the nodes on the system.
Return type:: jenkins_pysdk.nodes.Nodes

property online_executors: int

View the number of executors that are currently online on the instance.

Returns:: Number of online executors
Return type:: int
Raises:: JenkinsGeneralException – If a general exception occurs.

property pending_executors: int

View the number of executors that are about to run on the instance.

Returns:: Number of pending executors
Return type:: int
Raises:: JenkinsGeneralException – If a general exception occurs.

property plugins: Plugins

Retrieve information about plugins.

Returns:: A Plugins object representing the plugins on the system.
Return type:: jenkins_pysdk.plugins.Plugins

property queue: Queue

Retrieve information about the queue.

Returns:: A Queue object representing the queue on the system.
Return type:: jenkins_pysdk.queues.Queue

property queue_size: int

View the current queue size on the instance.

Returns:: Current queue size
Return type:: int
Raises:: JenkinsGeneralException – If a general exception occurs.

quiet_mode(duration: int | None = None, disable: bool = False) → JenkinsActionObject[source]

Enable or disable Quiet Mode on the Jenkins instance.

Parameters:

duration (int) – (optional) Enable Quiet Mode for X seconds
disable (bool) – (optional) If True, disable Quiet Mode, defaults to False

Returns:

Result of the request to enable or disable Quiet Mode

Return type:

jenkins_pysdk.objects.JenkinsActionObject

Raises:

JenkinsGeneralException – If a general exception occurs.

reload() → JenkinsActionObject[source]

Reload configuration from disk.

Returns:: Result of request
Return type:: jenkins_pysdk.objects.JenkinsActionObject

restart(graceful: bool = False) → JenkinsActionObject[source]

Restart the Jenkins instance.

Parameters:: graceful (bool) – (optional) If True, restart after all jobs have finished, defaults to False
Returns:: Restart status
Return type:: jenkins_pysdk.objects.JenkinsActionObject

script_console(commands: str) → str[source]

shutdown(graceful: bool = False) → JenkinsActionObject[source]

Terminate the user’s session.

Parameters:: graceful (bool) – (Default: False) If True, pause new jobs and wait for all jobs to complete.
Returns:: Result of the shutdown request
Return type:: jenkins_pysdk.objects.JenkinsActionObject

property tree

View all jobs in a pretty tree-like structure.

Returns:: Tree-like structure of all jobs.

property users: Users

Retrieve information about users.

Returns:: A Users object representing the users on the system.
Return type:: jenkins_pysdk.users.Users

property version: str

Get the version information of the Jenkins instance.

Returns:: Version information of the Jenkins instance
Return type:: str

property views: Views

Retrieve information about views.

Returns:: A Views object representing the views on the system.
Return type:: jenkins_pysdk.views.Views

jenkins_pysdk.jobs module

class jenkins_pysdk.jobs.Folder(*, jenkins, folder_path, folder_url)[source]

Bases: object

property config: str

Get the XML configuration of the folder.

Returns:: The XML configuration of the folder.
Return type:: str
Raises:: JenkinsGeneralException – If a general exception occurs.

copy(new_job_name: str) → JenkinsActionObject[source]

Copy an item into the existing path.

Parameters:: new_job_name (str) – The name of the new job.
Returns:: Result of the copy operation.
Return type:: jenkins_pysdk.objects.JenkinsActionObject
Raises:: JenkinsGeneralException – If a general exception occurs.

create(folder_name: str, xml: str, folder_type=Folders()) → JenkinsActionObject[source]

Creates sub-folders in the current path.

Parameters:

folder_name (str) – The name of the folder to create.
xml (str or Builder.Folder) – The XML configuration for the folder. Can be a string or a Builder.Folder object.
folder_type (jenkins_pysdk.objects.Folders) – (Optional) The type of folder to create

Returns:

The result of the action.

Return type:

jenkins_pysdk.objects.JenkinsActionObject

Raises:

JenkinsGeneralException – If a general exception occurs.

delete() → JenkinsActionObject[source]

Delete the folder.

Returns:: Result of the delete operation.
Return type:: jenkins_pysdk.objects.JenkinsActionObject
Raises:: JenkinsGeneralException – If a general exception occurs.

property path: str

Get the path of the folder.

Returns:: The path of the folder.
Return type:: str

reconfig(xml: str) → JenkinsActionObject[source]

Reconfigure the folder.

Parameters:: xml (str or Builder.Folder) – The XML configuration or Builder.Folder object.
Returns:: Action outcome
Return type:: jenkins_pysdk.objects.JenkinsActionObject
Raises:: JenkinsGeneralException – If a general exception occurs.

property url: str

Get the URL of the folder.

Returns:: The URL of the folder.
Return type:: str

class jenkins_pysdk.jobs.Folders(jenkins)[source]

Bases: object

api()[source]

Run a custom query and return folder data objects.

Returns:: Data objects representing folders.

create(folder_path: str, xml: str, folder_type=Folders()) → JenkinsActionObject[source]

Creates a folder at the specified path with the given XML configuration.

Parameters:

folder_path (str) – The path where the folder will be created.
xml (str or Builder.Folder) – The XML configuration for the folder.
folder_type (jenkins_pysdk.objects.Folders) – (Optional) The type of folder to create

Returns:

The result of the folder creation operation.

Return type:

jenkins_pysdk.objects.JenkinsActionObject

Raises:

JenkinsNotFound – If the folder was not found.
JenkinsGeneralException – If a general exception occurs.

is_folder(path: str) → bool[source]

Checks if the path corresponds to a folder in Jenkins.

Parameters:

path (str) – The path to check.

Returns:

True if the path corresponds to a folder, False otherwise.

Return type:

bool

Raises:

JenkinsNotFound – If the folder was not found.
JenkinsGeneralException – If a general exception occurs.

iter(folder: str | None = None, _paginate: int = 0) → Generator[Folder, None, None][source]

Iterate over folders within the specified folder.

Parameters:

folder (str, optional) – The path of the parent folder. If None, iterate over all folders.
_paginate (int, optional) – Number of items to paginate. Default is 0 (no pagination).

Returns:

A generator yielding Folder objects.

Return type:

Generator[jenkins_pysdk.jobs.Folder]

list(folder=None, _paginate=0) → List[Folder][source]

Retrieve a list of folder from Jenkins.

Parameters:

folder (str or None) – (Optional) The folder from which to retrieve jobs.
_paginate (int) – (Optional) The number of jobs to retrieve per paginated request. Set to 0 to disable pagination.

Returns:

A list of Job objects representing the jobs in the specified folder.

Return type:

List[jenkins_pysdk.jobs.Folder]

search(folder_path: str) → Folder[source]

Search for a folder within the Jenkins instance.

Parameters:

folder_path (str) – The path of the folder to search for.

Returns:

The folder object if found.

Return type:

jenkins_pysdk.jobs.Folder

Raises:

JenkinsNotFound – If the folder was not found.
JenkinsGeneralException – If a general exception occurs.

property tree

Get a hierarchical representation of all folders.

Returns:: A tree-like structure representing all folders.

class jenkins_pysdk.jobs.Job(*, jenkins, job_path, job_url)[source]

Bases: object

Represents a job in Jenkins.

Parameters:

jenkins (jenkins_pysdk.jenkins.Jenkins) – The Jenkins instance associated with the job.
job_path (str) – The path of the job.
job_url (str) – The URL of the job.

property builds: Builds

Access the builds associated with this job.

Returns:: Builds associated with this job.
Return type:: jenkins_pysdk.builds.Builds

property config: str

Get the XML configuration of the job.

Returns:: The XML configuration of the job.
Return type:: str
Raises:: JenkinsGeneralException – If a general exception occurs.

delete() → JenkinsActionObject[source]

Delete the folder.

Returns:: Result of the delete operation.
Return type:: jenkins_pysdk.objects.JenkinsActionObject

disable() → JenkinsActionObject[source]

Disable the job.

Returns:: Result of the request to disable the job.
Return type:: jenkins_pysdk.objects.JenkinsActionObject
Raises:: JenkinsGeneralException – If a general exception occurs.

enable() → JenkinsActionObject[source]

Enable the job.

Returns:: The outcome of enabling the job.
Return type:: jenkins_pysdk.objects.JenkinsActionObject
Raises:: JenkinsGeneralException – If a general exception occurs.

property path: str

Get the path of the job.

Returns:: The path of the job.
Return type:: str

reconfig(xml: str | None = None) → JenkinsActionObject[source]

Reconfigure the job.

Parameters:: xml (str, optional) – The XML configuration to use for reconfiguration.
Returns:: The outcome of reconfiguring the job.
Return type:: jenkins_pysdk.objects.JenkinsActionObject
Raises:: JenkinsGeneralException – If a general exception occurs.

property url: str

Get the URL of the job.

Returns:: The URL of the job.
Return type:: str

property workspace: Workspace

class jenkins_pysdk.jobs.Jobs(jenkins)[source]

Bases: object

api()[source]

Run your own query and return jobs data objects.

Returns:: Jobs data objects.

create(job_path: str, xml: str, job_type: Jobs) → JenkinsActionObject[source]

Create a job on the Jenkins instance.

Parameters:

job_path (str) – The path where the job should be created.
xml (str) – XML configuration for the job.
job_type (jenkins_pysdk.objects.Jobs) – Additional parameters for job creation.

Returns:

Object representing the result of the creation action.

Return type:

jenkins_pysdk.objects.JenkinsActionObject

Raises:

JenkinsGeneralException – If a general exception occurs.

is_job(path: str) → bool[source]

Checks if the path corresponds to a job in Jenkins.

Parameters:

path (str) – The path of the job to check.

Returns:

True if the path corresponds to a job, False otherwise.

Return type:

bool

Raises:

JenkinsGeneralException – If a general exception occurs.
JenkinsNotFound – If the job is not found.

iter(folder=None, _paginate=0) → Generator[Job, None, None][source]

Iterate through jobs in the Jenkins instance.

Parameters:

folder (str, optional) – The folder to iterate through. If None, iterate through all jobs.
_paginate (int, optional) – Pagination flag. Defaults to 0 (disabled).

Returns:

Generator yielding Job objects.

Return type:

Generator[jenkins_pysdk.jobs.Job]

list(folder=None, _paginate=0) → List[Job][source]

Retrieve a list of jobs from Jenkins.

Parameters:

folder (str or None) – (Optional) The folder from which to retrieve jobs.
_paginate (int) – (Optional) The number of jobs to retrieve per paginated request. Set to 0 to disable pagination.

Returns:

A list of Job objects representing the jobs in the specified folder.

Return type:

List[jenkins_pysdk.jobs.Job]

search(job_path: str) → Job[source]

Search for a job within Jenkins.

Parameters:: job_path (str) – The path of the job to search for.
Returns:: The job object.
Return type:: jenkins_pysdk.jobs.Job
Raises:: JenkinsNotFound: If the job wasn’t found.

property tree

View all jobs in a pretty tree-like structure.

Returns:: Tree-like structure of all jobs.

jenkins_pysdk.builds module

class jenkins_pysdk.builds.Build(jenkins, build_url: str)[source]

Bases: object

property artifacts

Get the artifacts of the build.

Returns:: A list of artifacts associated with the build.
Return type:: List[Artifact]

property changes: str

Get the changes associated with the build.

Returns:: The changes associated with the build.
Return type:: str
Raises:: JenkinsGeneralException – If a general exception occurs.

console(**kws) → str | Generator[str, None, None][source]

Retrieve the console output of the build.

Parameters:: kws – Keyword arguments. - progressive (bool, optional): Whether to retrieve progressive console output. - html (bool, optional): Whether to retrieve HTML-formatted console output. - _start (int, optional): Console output bytes offset (Only works with progressive/HTML - use with caution, as you may lose output).
Returns:: The console output of the build.
Return type:: str or Generator[str, None, None]
Raises:: JenkinsGeneralException – If a general exception occurs.

delete() → JenkinsActionObject[source]

Delete the build.

Returns:: Result of the delete request.
Return type:: jenkins_pysdk.objects.JenkinsActionObject

property description: str

Get the build description.

Returns:: The build description.
Return type:: str

property done: bool

Check if the build has completed.

Returns:: True if the build has completed, False otherwise.
Return type:: bool

property duration: int

Get the duration of the build.

Returns:: The duration of the build in milliseconds.
Return type:: int

property next: ...

Get the next build in the build queue.

Returns:: The next build in the build queue.
Return type:: jenkins_pysdk.builds.Build

property number: int

Get the build number.

Returns:: The build number.
Return type:: int

property previous: ...

Get the previous build in the build history.

Returns:: The previous build in the build history.
Return type:: jenkins_pysdk.builds.Build

rebuild() → JenkinsActionObject[source]

Rebuild the build.

Returns:: The result of the rebuild operation.
Return type:: jenkins_pysdk.objects.JenkinsActionObject
Raises:: JenkinsGeneralException – If a general exception occurs.

property result: str

Get the result of the build.

Returns:: The result of the build.
Return type:: str

property timestamp: int

Get the build timestamp.

Returns:: The build timestamp.
Return type:: int

property url: str

Get the URL of the build.

Returns:: The URL of the build.
Return type:: str

class jenkins_pysdk.builds.Builds(jenkins, job_url: str)[source]

Bases: object

build(parameters: dict | None = None, delay: int = 0) → JenkinsActionObject[source]

Trigger a new build for the job with optional parameters.

Parameters:

parameters (dict, optional) – (Optional) parameters to be passed to the build.
delay (int) – (Default: 0) Delay the build by X seconds

Returns:

Result of the build trigger request.

Return type:

jenkins_pysdk.objects.JenkinsActionObject

Raises:

JenkinsGeneralException – If a general exception occurs.

iter() → Generator[Build, None, None][source]

Iterate over builds in the build history of the job.

Yield:: A Build object representing each build in the build history.
Return type:: Generator[jenkins_pysdk.builds.Build]
Raises:: JenkinsGeneralException – If a general exception occurs.

property latest: Build

Retrieve the last build in the build history of the job.

Returns:: The Build object representing the last build.
Return type:: jenkins_pysdk.builds.Build
Raises:: JenkinsGeneralException – If a general exception occurs.

list() → List[Build][source]

Get a list of all builds in the build history of the job.

Returns:: A list of Build objects representing each build in the build history.
Return type:: List[jenkins_pysdk.builds.Build]
Raises:: JenkinsGeneralException – If a general exception occurs.

property oldest: Build

Retrieve the oldest saved build in the build history of the job.

Returns:: The Build object representing the oldest saved build.
Return type:: jenkins_pysdk.builds.Build
Raises:: JenkinsNotFound – If the job has no builds.

rebuild_last() → JenkinsActionObject[source]

Trigger a rebuild of the last build of the job.

Returns:: Result of the rebuild operation.
Return type:: jenkins_pysdk.objects.JenkinsActionObject
Raises:: JenkinsGeneralException – If a general exception occurs.

search(build_number: int = False, **kws) → Build[source]

Fetches a specific build from the build history of the job.

Parameters:

build_number (int) – The number of the build to fetch.
kws (dict) – Additional keyword arguments to specify which build to fetch.
lastStableBuild (bool, optional) – Fetch the last stable build.
lastSuccessfulBuild (bool, optional) – Fetch the last successful build.
lastFailedBuild (bool, optional) – Fetch the last failed build.
lastUnsuccessfulBuild (bool, optional) – Fetch the last unsuccessful build.
lastCompletedBuild (bool, optional) – Fetch the last completed build.

Returns:

The Build object representing the requested build.

Return type:

jenkins_pysdk.builds.Build

property total: int

Get the total number of saved builds for the job.

Returns:: The total number of saved builds.
Return type:: int
Raises:: JenkinsGeneralException – If a general exception occurs.

jenkins_pysdk.workspace module

class jenkins_pysdk.workspace.Workspace(jenkins, job_name: str, job_url: str)[source]

Bases: object

Represents the workspace of a Jenkins job.

Parameters:

jenkins (jenkins_pysdk.jenkins.Jenkins) – Connection to the Jenkins instance.
job_name (str) – Name of the Jenkins job.
job_url (str) – URL of the Jenkins job.

download(path: str, workspace_file: str | None = None) → JenkinsActionObject[source]

Download workspace files from the job.

Parameters:

path (str) – The directory where the workspace files will be saved.
workspace_file (str, optional) – (Optional) Download a specific file in the workspace

Returns:

An object representing the action performed in Jenkins.

Return type:

jenkins_pysdk.objects.JenkinsActionObject

wipe() → JenkinsActionObject[source]

Wipe the workspace of the Jenkins job.

Returns:: An object representing the action performed in Jenkins.
Return type:: jenkins_pysdk.objects.JenkinsActionObject

jenkins_pysdk.queues module

class jenkins_pysdk.queues.Queue(jenkins)[source]

Bases: object

Represents a Jenkins queue.

This class provides functionality to interact with the Jenkins queue.

Parameters:: jenkins (jenkins_pysdk.jenkins.Jenkins) – The Jenkins instance.

iter(_paginate=0) → Generator[QueueItem, None, None][source]

Iterates over the items in the Jenkins queue.

Parameters:: _paginate (int) – The number of items to fetch per page (default is 0, meaning all items).
Returns:: A generator yielding QueueItem objects representing items in the queue.
Return type:: Generator[jenkins_pysdk.queues.QueueItem]
Raises:: JenkinsGeneralException – If a general exception occurs.

list(_paginate=0) → List[QueueItem][source]

Lists items in the Jenkins queue.

Parameters:: _paginate (int) – The number of items to fetch per page (default is 0, meaning all items).
Returns:: A list of QueueItem objects representing items in the queue.
Return type:: List[jenkins_pysdk.queues.QueueItem]

property newest: QueueItem

Returns the newest item in the Jenkins queue.

Returns:: The newest item in the Jenkins queue.
Return type:: jenkins_pysdk.jenkins.QueueItem
Raises:: JenkinsEmptyQueue – If the queue is empty.

property oldest: QueueItem

Returns the oldest item in the Jenkins queue.

Returns:: The oldest item in the Jenkins queue.
Return type:: jenkins_pysdk.jenkins.QueueItem
Raises:: JenkinsEmptyQueue – If the queue is empty.

property total: int

Returns the total number of items in the Jenkins queue.

Returns:: The total number of items in the Jenkins queue.
Return type:: int

class jenkins_pysdk.queues.QueueItem(jenkins, queue_info: dict)[source]

Bases: object

Represents an item in the queue.

Parameters:

jenkins (jenkins_pysdk.jenkins.Jenkins) – The Jenkins instance.
queue_info (dict) – Information about the queue item.

property blocked: bool

Indicates whether the queue item is blocked.

Returns:: True if the queue item is blocked, False otherwise.
Return type:: bool

property build: Build

Returns the build associated with the queue item.

Returns:: The build associated with the queue item.
Return type:: jenkins_pysdk.jenkins.Build

property id: int

Returns the ID of the queue item.

Returns:: The ID of the queue item.
Return type:: int

property job: Job

Returns the job associated with the queue item.

Returns:: The job associated with the queue item.
Return type:: jenkins_pysdk.jobs.Job

property number: int

Returns the Build number of the queue item.

Returns:: The Build number of the queue item.
Return type:: int

property reason: str

Returns the reason for the queue item.

Returns:: The reason for the queue item.
Return type:: str

property scheduled: int

Returns the timestamp when the queue item was scheduled.

Returns:: The timestamp when the queue item was scheduled.
Return type:: int

property stuck: bool

Indicates whether the queue item is stuck.

Returns:: True if the queue item is stuck, False otherwise.
Return type:: bool

property type

Returns the Job type of the queue item.

Returns:: The Job type of the queue item.
Return type:: str

jenkins_pysdk.views module

class jenkins_pysdk.views.View(*, jenkins, name, url)[source]

Bases: object

property config: str

Get the XML configuration of the view.

Returns:: The XML configuration of the view.
Return type:: str
Raises:: JenkinsGeneralException – If a general exception occurs.

delete() → JenkinsActionObject[source]

Delete the view.

Returns:: Jenkins action object indicating the delete status.
Return type:: jenkins_pysdk.objects.JenkinsActionObject

property name: str

Get the name of the view.

Returns:: The name of the view.
Return type:: str

reconfig(xml: str) → JenkinsActionObject[source]

Reconfigure the view with XML configuration or a builder.

Parameters:: xml (str or jenkins_pysdk.builders.Builder, optional) – The XML configuration of the view, defaults to None.
Returns:: Jenkins action object indicating the reconfiguration status.
Return type:: jenkins_pysdk.objects.JenkinsActionObject
Raises:: JenkinsGeneralException – If a general exception occurs.

property url: str

Get the URL of the view.

Returns:: The URL of the view.
Return type:: str

class jenkins_pysdk.views.Views(jenkins)[source]

Bases: object

api()[source]

Run your own query and return views data objects.

Returns:: None
Return type:: None

create(name: str, xml: str) → JenkinsActionObject[source]

Create a new view.

Parameters:

name (str) – The name of the new view.
xml (str or Builder.View) – The XML configuration or Builder.View object for the new view.

Returns:

JenkinsActionObject indicating the result of the creation.

Return type:

jenkins_pysdk.objects.JenkinsActionObject

Raises:

JenkinsGeneralException – If a general exception occurs.

is_view(path: str) → bool[source]

Check if the specified path is a view.

Parameters:

path (str) – The path to check.

Returns:

True if the path corresponds to a view, False otherwise.

Return type:

bool

Raises:

JenkinsNotFound – If the view was not found.
JenkinsGeneralException – If a general exception occurs.

iter(folder: str | None = None, _paginate=0) → Generator[View, None, None][source]

Iterate through views.

Parameters:

folder (str, optional) – Check if folder is in a view. Default is None.
_paginate (int, optional) – Pagination option. Default is 0 (no pagination).

Returns:

A generator yielding View objects.

Return type:

Generator[jenkins_pysdk.views.View]

list(folder: str | None = None, _paginate=0) → List[View][source]

List all views.

Parameters:

folder (str, optional) – Folder to iterate through. Default is None.
_paginate (int, optional) – Pagination option. Default is 0 (no pagination).

Returns:

A list of View objects.

Return type:

List[jenkins_pysdk.views.View]

search(view_path: str) → View[source]

Search for a view within Jenkins.

Parameters:: view_path (str) – The path of the view to search for.
Returns:: The View object representing the found view.
Return type:: jenkins_pysdk.views.View
Raises:: JenkinsNotFound – If the view was not found.

property tree

View all views in a pretty tree-like structure.

Returns:: None
Return type:: None

jenkins_pysdk.credentials module

class jenkins_pysdk.credentials.Credential(*, jenkins, cred_id: str, domain_url: str)[source]

Bases: object

property config: str

Get the configuration of the credential.

Returns:: The configuration of the credential.
Return type:: jenkins_pysdk.objects.JenkinsActionObject
Raises:: JenkinsGeneralException – If a general exception occurs.

delete() → JenkinsActionObject[source]

Delete the credential.

Returns:: Result of the deletion operation.
Return type:: jenkins_pysdk.objects.JenkinsActionObject

property id: str

Get the ID of the credential.

Returns:: The ID of the credential.
Return type:: str

move(dest: str) → JenkinsActionObject[source]

Move the credential to another domain.

Returns:: Result of the move operation.
Return type:: jenkins_pysdk.objects.JenkinsActionObject

reconfig(xml: str) → JenkinsActionObject[source]

Reconfigure the credential with new XML content or using a Credentials builder.

Parameters:: xml (str or Builder.Credentials) – The new XML content or a Credentials builder.
Returns:: Result of the reconfiguration operation.
Return type:: jenkins_pysdk.objects.JenkinsActionObject
Raises:: JenkinsGeneralException – If a general exception occurs.

class jenkins_pysdk.credentials.Credentials(jenkins)[source]

Bases: object

create_domain(name: str, cred: str) → JenkinsActionObject[source]

Create a new domain.

Parameters:

name (str) – The name of the domain
cred (Builder.Credentials.Domain) – The credentials to associate with the domain.

Returns:

Outcome of the domain creation request.

Return type:

jenkins_pysdk.objects.JenkinsActionObject

Raises:

JenkinsAlreadyExists – If the domain already exists.
JenkinsGeneralException – If a general exception occurs.

iter_domains() → Generator[Domain, None, None][source]

Iterate over domains on the Jenkins instance.

Returns:: A generator yielding Domain objects.
Return type:: Generator[jenkins_pysdk.credentials.Domain]
Raises:: JenkinsGeneralException – If a general exception occurs.

list_domains() → List[Domain][source]

List all domains on the Jenkins instance.

Returns:: List of Domain objects.
Return type:: List[jenkins_pysdk.credentials.Domain]

search_domains(domain: str | None = None) → Domain[source]

Search for domains on the Jenkins instance.

Parameters:: domain (str, optional) – The name of the domain to search for. If None, returns all domains.
Returns:: The Domain object representing the found domain.
Return type:: jenkins_pysdk.credentials.Domain
Raises:: JenkinsGeneralException – If a general exception occurs.

class jenkins_pysdk.credentials.Domain(*, jenkins, url: str)[source]

Bases: object

create(name: str, cred: str) → JenkinsActionObject[source]

Create a new credential.

Parameters:

name (str) – The name of the domain
cred (str or Builder.Credentials) – The credential object to create.

Returns:

Result of the deletion operation.

Return type:

jenkins_pysdk.objects.JenkinsActionObject

iter() → Generator[Credential, None, None][source]

Iterate over credentials within the domain.

Returns:: A generator yielding credentials within the specified domain.
Return type:: Generator[jenkins_pysdk.credentials.Credential]
Raises:: JenkinsGeneralException – If a general exception occurs.

list() → List[Credential][source]

List credentials within the domain.

Returns:: A list of credentials within the specified domain.
Return type:: List[jenkins_pysdk.credentials.Credential]

property name: str

The name of the domain.

Returns:: The name of the domain.
Return type:: str

search(cred_id: str) → Credential[source]

Search for a credential within the domain.

Parameters:: cred_id (str) – The ID of the credential to search for.
Returns:: The credential matching the provided ID.
Return type:: jenkins_pysdk.credentials.Credential

property url: str

The domain URL.

Returns:: The domain URL in str format.
Return type:: str

jenkins_pysdk.users module

class jenkins_pysdk.users.User(jenkins, user_url: str)[source]

Bases: object

property builds

Get a list of builds associated with the user.

Returns:: A list of build objects associated with the user.
Return type:: List[jenkins_pysdk.builds.Build]
Raises:: JenkinsGeneralException – If a general exception occurs.

credentials(domain='_') → Domain[source]

Search the users’ personal credential safe.

Parameters:: domain (str, optional) – The domain to search for credentials (default is “_”).
Returns:: A domain object representing the user’s personal credential safe.
Return type:: jenkins_pysdk.credentials.Domain
Raises:: JenkinsNotFound: If the users credentials were not found.

delete() → JenkinsActionObject[source]

Delete the user.

Returns:: Action object representing the result of the deletion operation.
Return type:: jenkins_pysdk.objects.JenkinsActionObject

property description: str

Get the description of the user.

Returns:: The description of the user.
Return type:: str

logout() → JenkinsActionObject[source]

Terminate the user’s session.

Returns:: Result of the logout request
Return type:: jenkins_pysdk.objects.JenkinsActionObject

property name: str

Get the name of the user.

Returns:: The name of the user.
Return type:: str

property url: str

Get the URL of the user.

Returns:: The URL of the user.
Return type:: str

property views: List[View]

Get a list of views associated with the user.

Returns:: A list of view objects associated with the user.
Return type:: List[jenkins_pysdk.views.View]
Raises:: JenkinsGeneralException – If a general exception occurs.

class jenkins_pysdk.users.Users(jenkins)[source]

Bases: object

create(config: User) → JenkinsActionObject[source]

Create a new user.

Parameters:: config (jenkins_pysdk.builders.Builder) – The user to be created.
Returns:: An object representing the action performed in Jenkins.
Return type:: jenkins_pysdk.objects.JenkinsActionObject

iter() → Generator[User, None, None][source]

Iterate over all users.

Returns:: Generator yielding User objects.
Return type:: Generator[jenkins_pysdk.usersUser]

list() → List[User][source]

Get a list of all users.

Returns:: List of User objects.
Return type:: List[jenkins_pysdk.users.User]

search(username: str) → User[source]

Search for a user by username.

Parameters:: username (str) – The username of the user to search for.
Returns:: User object corresponding to the username.
Return type:: jenkins_pysdk.users.User
Raises:: JenkinsGeneralException – If a general exception occurs.

property total: int

Get the total number of users.

Returns:: Total number of users.
Return type:: int

jenkins_pysdk.plugins module

class jenkins_pysdk.plugins.Installed(jenkins, plugin_info)[source]

Bases: object

Represents an installed plugin in Jenkins.

Parameters:

jenkins (Jenkins) – The Jenkins instance this installed plugin belongs to.
plugin_info (dict) – Information about the installed plugin.

property active: bool

Indicates whether the plugin is active.

Returns:: True if the plugin is active, False otherwise.
Return type:: bool

delete() → JenkinsActionObject[source]

Delete the plugin from the Jenkins instance.

Returns:: JenkinsActionObject representing the delete action.
Return type:: jenkins_pysdk.objects.JenkinsActionObject
Raises:: JenkinsGeneralException – If a general exception occurs.

property dependencies: List[Dict]

The dependencies of the installed plugin.

Returns:: A list of dictionaries representing the dependencies, where each dictionary contains the dependency name as key and the dependency version as value.
Return type:: List[Dict]

disable() → JenkinsActionObject[source]

Disable the installed plugin.

Returns:: JenkinsActionObject representing the disable action.
Return type:: jenkins_pysdk.objects.JenkinsActionObject
Raises:: JenkinsGeneralException – If a general exception occurs.

enable() → JenkinsActionObject[source]

Enable the installed plugin.

Returns:: JenkinsActionObject representing the enable action.
Return type:: jenkins_pysdk.objects.JenkinsActionObject
Raises:: JenkinsGeneralException – If a general exception occurs.

property name: str

The name of the installed plugin.

Returns:: The name of the installed plugin.
Return type:: str

property pinned: bool

Indicates whether the installed plugin is pinned.

Returns:: True if the plugin is pinned, False otherwise.
Return type:: bool

property requires: str

The required core version for the installed plugin.

Returns:: The required core version for the installed plugin.
Return type:: str

property url: str

The URL of the installed plugin.

Returns:: The URL of the installed plugin.
Return type:: str

property version: str

The version of the installed plugin.

Returns:: The version of the installed plugin.
Return type:: str

class jenkins_pysdk.plugins.Plugin(jenkins, plugin_info)[source]

Bases: object

Represents a plugin in Jenkins.

Parameters:

jenkins (jenkins_pysdk.jenkins.Jenkins) – The Jenkins instance this plugin belongs to.
plugin_info (dict) – Information about the plugin.

property compatible: bool

Indicates whether the plugin is compatible.

Returns:: True if the plugin is compatible, False otherwise.
Return type:: bool

property dependencies: List[dict]

The dependencies of the plugin.

Returns:: A list of dictionaries representing the dependencies, where each dictionary contains the dependency name as key and the dependency version as value.
Return type:: List[dict]

property docs: str

The documentation URL for the plugin.

Returns:: The documentation URL for the plugin.
Return type:: str

property name: str

The name of the plugin.

Returns:: The name of the plugin.
Return type:: str

property requires: str

The required core version for the plugin.

Returns:: The required core version for the plugin.
Return type:: str

property site: Site

The site associated with the plugin.

Returns:: The Site object representing the site associated with the plugin.
Return type:: Site

property url: str

The URL of the plugin.

Returns:: The URL of the plugin.
Return type:: str

property version: str

The version of the plugin.

Returns:: The version of the plugin.
Return type:: str

class jenkins_pysdk.plugins.PluginGroup(jenkins, p_type: str)[source]

Bases: object

Represents a group of plugins in Jenkins.

Parameters:

jenkins (jenkins_pysdk.jenkins.Jenkins) – The Jenkins instance this plugin group belongs to.
p_type (str) – The type of the plugin group.

iter(site: str = 'default', _paginate: int = 0) → Generator[Plugin | Installed, None, None][source]

Iterate over the plugins or installed plugins within the plugin group.

Parameters:

site (str, optional) – The site to iterate over. Default is “default”.
_paginate (int, optional) – The number of items to paginate. Default is 0.

Returns:

A generator that yields Plugin or Installed objects.

Return type:

Generator[Union[jenkins_pysdk.plugins.Plugin, jenkins_pysdk.plugins.Installed]]

Raises:

JenkinsGeneralException – If a general exception occurs.

list(_paginate: int = 0) → List[Plugin | Installed][source]

List the plugins or installed plugins within the plugin group.

Parameters:: _paginate (int, optional) – The number of items to paginate. Default is 0.
Returns:: A list of Plugin or Installed objects.
Return type:: List[Union[jenkins_pysdk.plugins.Plugin, jenkins_pysdk.plugins.Installed]]

search(id: str, site: str = 'default', _paginate=500) → Plugin | Installed[source]

Search for a plugin or an installed plugin within the plugin group.

Parameters:

id (str) – The ID of the plugin to search for.
site (str, optional) – The site to search for the plugin. Default is “default”.
_paginate (int, optional) – The number of items to paginate. Default is 500.

Returns:

A Plugin or Installed object representing the found plugin.

Return type:

Union[jenkins_pysdk.plugins.Plugin, jenkins_pysdk.plugins.Installed]

Raises:

JenkinsNotFound – If the plugin with the specified name is not found.

class jenkins_pysdk.plugins.Plugins(jenkins)[source]

Bases: object

Represents a collection of plugins in Jenkins.

Parameters:: jenkins (jenkins_pysdk.jenkins.Jenkins) – The Jenkins instance containing the plugins.

property availables: PluginGroup

Represents a group of available plugins in Jenkins.

Returns:: A PluginGroup instance representing the available plugins.
Return type:: jenkins_pysdk.plugins.PluginGroup

install(name: str, version: str = 'latest', restart: bool = False) → JenkinsActionObject[source]

Installs a plugin in Jenkins.

Parameters:

name (str) – The name of the plugin to install.
version (Union[str, int, float], optional) – The version of the plugin to install. Default is “latest”.
restart (bool, optional) – Whether to restart Jenkins after installation. Default is False.

Returns:

A JenkinsActionObject representing the installation action.

Return type:

jenkins_pysdk.objects.JenkinsActionObject

Raises:

JenkinsGeneralException – If a general exception occurs.

property installed: PluginGroup

Represents a group of installed plugins in Jenkins.

Returns:: A PluginGroup instance representing the installed plugins.
Return type:: jenkins_pysdk.plugins.PluginGroup

property sites: UpdateCenter

Represents the update centers for managing plugin sites in Jenkins.

Returns:: An UpdateCenter instance representing the update centers.
Return type:: jenkins_pysdk.plugins.UpdateCenter

property updates: PluginGroup

Represents a group of plugins with available updates in Jenkins.

Returns:: A PluginGroup instance representing the plugins with available updates.
Return type:: jenkins_pysdk.plugins.PluginGroup

upload(filename: str, file_content: BinaryIO) → JenkinsActionObject[source]

Uploads a plugin to Jenkins.

Parameters:

filename (str) – The name of the plugin file.
file_content (bytes or BinaryIO) – The content of the plugin file as bytes.

Returns:

A JenkinsActionObject representing the upload action.

Return type:

jenkins_pysdk.objects.JenkinsActionObject

Raises:

JenkinsGeneralException – If a general exception occurs.

class jenkins_pysdk.plugins.Site(jenkins, site_id: str)[source]

Bases: object

Represents a site in Jenkins.

Parameters:

jenkins (jenkins_pysdk.jenkins.Jenkins) – The Jenkins instance this site belongs to.
site_id (str) – The ID of the site.

property connection_check_url: str

The URL for checking the connection of the site.

Returns:: The URL for connection check.
Return type:: str

property has_updates: bool

Indicates whether the site has updates available.

Returns:: True if updates are available, False otherwise.
Return type:: bool

property id: str

The ID of the site.

Returns:: The ID of the site.
Return type:: str

property suggested_plugins_url: str

The URL for suggested plugins for the site.

Returns:: The URL for suggested plugins.
Return type:: str

property timestamp: int

The timestamp of the site data.

Returns:: The timestamp of the site data.
Return type:: int

property url: str

The URL of the site.

Returns:: The URL of the site.
Return type:: str

class jenkins_pysdk.plugins.UpdateCenter(jenkins)[source]

Bases: object

Represents the update center in Jenkins.

Parameters:: jenkins (jenkins_pysdk.jenkins.Jenkins) – The Jenkins instance this update center belongs to.

create(site_url: str) → JenkinsActionObject[source]

Create a new site in the update center.

Returns:: JenkinsActionObject representing the create update center operation.
Return type:: jenkins_pysdk.objects.JenkinsActionObject
Raises:: JenkinsGeneralException – If a general exception occurs.

iter() → Generator[Site, None, None][source]

Iterate over the sites in the update center.

Returns:: A generator yielding Site objects.
Return type:: Generator[jenkins_pysdk.plugins.Site]
Raises:: JenkinsGeneralException – If a general exception occurs.

list() → List[Site][source]

Get a list of all sites in the update center.

Returns:: A list of Site objects.
Return type:: List[jenkins_pysdk.plugins.Site]

search(name: str) → Site[source]

Search for a site by name.

Parameters:: name (str) – The name of the site to search for.
Returns:: The Site object if found, otherwise raise an exception.
Return type:: jenkins_pysdk.plugins.Site
Raises:: JenkinsNotFound – If the site with the specified name is not found.

jenkins_pysdk.nodes module

class jenkins_pysdk.nodes.Node(jenkins, name: str, node_url: str)[source]

Bases: object

Represents a node in Jenkins.

Parameters:

jenkins (jenkins_pysdk.jenkins.Jenkins) – The Jenkins instance this node belongs to.
name (str) – The name of the node.
node_url (str) – The URL of the node.

property config: str

Get the configuration of the node.

Returns:: The configuration of the node as a string.
Return type:: str
Raises:: JenkinsGeneralException – If a general exception occurs.

delete() → JenkinsActionObject[source]

Delete action for the node.

Returns:: JenkinsActionObject representing the delete action.
Return type:: jenkins_pysdk.objects.JenkinsActionObject

disable(message: str) → JenkinsActionObject[source]

Disable the node with an optional message.

Parameters:: message (str) – Optional message explaining the reason for disabling the node.
Returns:: JenkinsActionObject representing the disable action.
Return type:: jenkins_pysdk.objects.JenkinsActionObject
Raises:: JenkinsGeneralException – If a general exception occurs.

enable() → JenkinsActionObject[source]

Enable action for the node.

Returns:: JenkinsActionObject representing the delete action.
Return type:: jenkins_pysdk.objects.JenkinsActionObject
Raises:: JenkinsGeneralException – If a general exception occurs.

property idle: int

Whether the node is idle or not.

Returns:: 1 if the node is idle, 0 otherwise.
Return type:: int

property name: str

The name of the node.

Returns:: The name of the node.
Return type:: str

reconfig(xml: str) → JenkinsActionObject[source]

Reconfigure the node with the provided XML configuration.

Parameters:: xml (str) – The XML configuration to apply to the node.
Returns:: JenkinsActionObject representing the reconfiguration action.
Return type:: jenkins_pysdk.objects.JenkinsActionObject

property url: str

The URL of the node.

Returns:: The URL of the node.
Return type:: str

class jenkins_pysdk.nodes.Nodes(jenkins)[source]

Bases: object

Represents a collection of nodes in Jenkins.

Parameters:: jenkins (Jenkins) – The Jenkins instance managing the nodes.

create(name: str, json: dict) → JenkinsActionObject[source]

Create a new node with the given name and configuration.

Parameters:

name (str) – The name of the node to create.
json (dict or json or Builder.Node) – The JSON configuration of the node, either as a dictionary, an json object, or a Builder.Node object.

Returns:

JenkinsActionObject representing the create action.

Return type:

jenkins_pysdk.objects.JenkinsActionObject

Raises:

JenkinsGeneralException – If a general exception occurs.

iter() → Generator[Node, None, None][source]

Iterate over the nodes.

Returns:: A generator yielding Node objects.
Return type:: Generator[jenkins_pysdk.nodes.Node]
Raises:: JenkinsGeneralException – If a general exception occurs.

list() → List[Node][source]

Get a list of all nodes.

Returns:: A list of Node objects.
Return type:: List[jenkins_pysdk.nodes.Node]

search(name: str) → Node[source]

Search for a node by name.

Parameters:: name (str) – The name of the node to search for.
Returns:: The Node object if found, otherwise raise an exception.
Return type:: Node
Raises:: JenkinsNotFound – If the node with the specified name is not found.