Folders

Interact with a folder

jobs.Folders.search()

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.

from jenkins_pysdk.jenkins import Jenkins
jenkins = Jenkins(host="JenkinsDNS", username="admin", token="11e8e294cee85ee88b60d99328284d7608")
print(jenkins.folders.search("my_new_folder_name"))

The above code will output:

<jenkins_pysdk.jobs.Folder object at 0x00000295B24B4AF0>

List all folders

jobs.Folders.list()

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]

from jenkins_pysdk.jenkins import Jenkins
jenkins = Jenkins(host="JenkinsDNS", username="admin", token="11e8e294cee85ee88b60d99328284d7608")
for folder in jenkins.folders.list():
    print(folder.path, folder.url)

The above code will output:

builder_1 https://JenkinsDNS/job/builder_1/
builder_2 https://JenkinsDNS/job/builder_2/
builder_4 https://JenkinsDNS/job/builder_4/
builder_d https://JenkinsDNS/job/builder_d/
builder_e https://JenkinsDNS/job/builder_e/
builder_folder https://JenkinsDNS/job/builder_folder/
builder_w https://JenkinsDNS/job/builder_w/
new_folder/new_job23 https://JenkinsDNS/job/new_folder/job/new_job23/
new_folder/test_folder https://JenkinsDNS/job/new_folder/job/test_folder/

Iterate all folders

jobs.Folders.iter()

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]

from jenkins_pysdk.jenkins import Jenkins
jenkins = Jenkins(host="JenkinsDNS", username="admin", token="11e8e294cee85ee88b60d99328284d7608")
for folder in jenkins.folders.iter():
    print(folder.path, folder.url)

The above code will output:

builder_1 https://JenkinsDNS/job/builder_1/
builder_2 https://JenkinsDNS/job/builder_2/
builder_4 https://JenkinsDNS/job/builder_4/
builder_d https://JenkinsDNS/job/builder_d/
builder_e https://JenkinsDNS/job/builder_e/
builder_folder https://JenkinsDNS/job/builder_folder/
builder_w https://JenkinsDNS/job/builder_w/
new_folder/new_job23 https://JenkinsDNS/job/new_folder/job/new_job23/
new_folder/test_folder https://JenkinsDNS/job/new_folder/job/test_folder/

jobs.Folders.create()

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.

from jenkins_pysdk.jenkins import Jenkins
from jenkins_pysdk.builders import Builder
jenkins = Jenkins(host="JenkinsDNS", username="admin", token="11e8e294cee85ee88b60d99328284d7608")
my_folder = Builder.Folder(name="my_new_folder_name", description="my description is pretty simple.")
print(jenkins.folders.create("my_new_folder_name", my_folder))

The above code will output:

request=<Request object at 1935978150336> content='[200] Successfully created my_new_folder_name.' status_code=200

Check if the path is a folder

jobs.Folders.is_folder()

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.

from jenkins_pysdk.jenkins import Jenkins
jenkins = Jenkins(host="JenkinsDNS", username="admin", token="11e8e294cee85ee88b60d99328284d7608")
print(jenkins.folders.is_folder("folder3/sub_folder"))

The above code will output:

True

Folder

Reconfigure a folder

jobs.Folder.reconfig()

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.

from jenkins_pysdk.jenkins import Jenkins
from builders.builder import Builder
jenkins = Jenkins(host="JenkinsDNS", username="admin", token="11e8e294cee85ee88b60d99328284d7608")
new_folder = Builder.Folder(name="my_new_folder_name", description="Reconfigured")
print(jenkins.folders.search("my_new_folder_name").reconfig(new_folder))

The above code will output:

request=<Request object at 2282610093216> content='[200] Successfully reconfigured my_new_folder_name.' status_code=200

Get the first folder URL

jobs.Folder.url()

Get the URL of the folder.

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

from jenkins_pysdk.jenkins import Jenkins
from builders.builder import Builder
jenkins = Jenkins(host="JenkinsDNS", username="admin", token="11e8e294cee85ee88b60d99328284d7608")
print(jenkins.folders.list()[0].url)

The above code will output:

https://JenkinsDNS/job/builder_1/

Get the first folder Path

jobs.Folder.path()

Get the path of the folder.

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

from jenkins_pysdk.jenkins import Jenkins
jenkins = Jenkins(host="JenkinsDNS", username="admin", token="11e8e294cee85ee88b60d99328284d7608")
print(jenkins.folders.list()[0].path)

The above code will output:

builder_1

Copy a folder (You are interacting with a specific folder location, so you can’t copy a folder up a level)

jobs.Folder.copy()

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.

from jenkins_pysdk.jenkins import Jenkins
jenkins = Jenkins(host="JenkinsDNS", username="admin", token="11e8e294cee85ee88b60d99328284d7608")
my_folder = jenkins.folders.search("folder3")
print(my_folder.copy(new_job_name="another_sub_folder")

The above code will output:

request=<Request object at 1480728865872> content='[200] Successfully copied sub_folder to another_sub_folder.' status_code=200

Delete the current folder

jobs.Folder.delete()

Delete the folder.

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

from jenkins_pysdk.jenkins import Jenkins
jenkins = Jenkins(host="JenkinsDNS", username="admin", token="11e8e294cee85ee88b60d99328284d7608")
print(jenkins.folders.search("folder3/another_sub_folder").delete())

The above code will output:

request=<Request object at 2309917207952> content='[204] Successfully deleted folder.' status_code=204

Create a folder (You are interacting with a specific folder location, so you can only create sub-folders)

jobs.Folder.create()

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.

from jenkins_pysdk.jenkins import Jenkins
from jenkins_pysdk.builders import Builder
jenkins = Jenkins(host="JenkinsDNS", username="admin", token="11e8e294cee85ee88b60d99328284d7608")
my_folder = Builder.Folder(name="my_new_folder_name", description="my description is pretty simple.")
print(jenkins.folders.search("folder3/sub_folder").create("another_sub_folder", my_folder))

The above code will output:

request=<Request object at 1660448175456> content='[200] Successfully created another_sub_folder.' status_code=200

Get the folder config

jobs.Folder.config()

Get the XML configuration of the folder.

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

from jenkins_pysdk.jenkins import Jenkins
jenkins = Jenkins(host="JenkinsDNS", username="admin", token="11e8e294cee85ee88b60d99328284d7608")
print(jenkins.folders.search("folder3/another_sub_folder").config)

The above code will output:

<?xml version='1.1' encoding='UTF-8'?>
<com.cloudbees.hudson.plugins.folder.Folder plugin="cloudbees-folder@6.928.v7c780211d66e">
  <description></description>
  <properties/>
  <folderViews class="com.cloudbees.hudson.plugins.folder.views.DefaultFolderViewHolder">
    <views>
      <hudson.model.AllView>
        <owner class="com.cloudbees.hudson.plugins.folder.Folder" reference="../../../.."/>
        <name>All</name>
        <filterExecutors>false</filterExecutors>
        <filterQueue>false</filterQueue>
        <properties class="hudson.model.View$PropertyList"/>
      </hudson.model.AllView>
    </views>
    <tabBar class="hudson.views.DefaultViewsTabBar"/>
  </folderViews>
  <healthMetrics/>
  <icon class="com.cloudbees.hudson.plugins.folder.icons.StockFolderIcon"/>
</com.cloudbees.hudson.plugins.folder.Folder>