new method: create_folder (with tests)

Change-Id: Ib21398c98d853aed4f4eea50270164e501fd18ce

jenkins/__init__.py

@@ -1170,6 +1170,24 @@ class Jenkins(object):
         if not self.job_exists(name):
             raise JenkinsException(exception_message % name)
 
+    def create_folder(self, folder_name, ignore_failures=False):
+        '''Create a new Jenkins folder
+
+        :param folder_name: Name of Jenkins Folder, ``str``
+        :param ignore_failures: if True, don't raise if it was not possible to create the folder, ``bool``
+        '''
+        folder_url, short_name = self._get_job_folder(folder_name)
+        url = self._build_url(CREATE_JOB, locals())
+        data = {
+            "name": folder_name,
+            "mode": "com.cloudbees.hudson.plugins.folder.Folder"
+        }
+        try:
+            response = self.jenkins_request(requests.Request('POST', url, data=data))
+        except requests.exceptions.HTTPError:
+            if not ignore_failures:
+                raise JenkinsException('Error creating folder [%s]. Probably it already exists.' % (folder_name))
+
     def upsert_job(self, name, config_xml):
         '''Create a new Jenkins job or reconfigures it if it exists
 

tests/test_job_folder.py

@@ -2,6 +2,7 @@ from mock import patch
 
 import jenkins
 from tests.base import JenkinsTestBase
+from tests.helper import build_response_mock
 
 
 class JenkinsGetJobFolderTest(JenkinsTestBase):
@@ -23,3 +24,38 @@ class JenkinsGetJobFolderTest(JenkinsTestBase):
         folder, name = self.j._get_job_folder('folder1/folder2/my job')
         self.assertEqual(folder, 'job/folder1/job/folder2/')
         self.assertEqual(name, 'my job')
+
+
+class JenkinsCreateFolderTest(JenkinsTestBase):
+
+    @patch('jenkins.requests.Session.send', autospec=True)
+    def test_create_new_folder(self, session_send_mock):
+        session_send_mock.side_effect = iter([
+            build_response_mock(200, self.crumb_data),  # crumb
+            build_response_mock(200, None),  # request
+        ])
+        self.j.create_folder(u'New-Test-Folder')
+
+    @patch('jenkins.requests.Session.send', autospec=True)
+    def test_create_new_folder_that_already_exists(self, session_send_mock):
+        session_send_mock.side_effect = iter([
+            build_response_mock(200, self.crumb_data),  # crumb
+            build_response_mock(400),  # request
+        ])
+
+        folder_name = u'Folder-that-already-exists'
+
+        with self.assertRaises(jenkins.JenkinsException) as context_manager:
+            self.j.create_folder(folder_name)
+        self.assertEqual(
+            str(context_manager.exception),
+            u'Error creating folder [' + folder_name + ']. Probably it already exists.')
+
+    @patch('jenkins.requests.Session.send', autospec=True)
+    def test_create_new_folder_that_already_exists_ignoring_errors(self, session_send_mock):
+        session_send_mock.side_effect = iter([
+            build_response_mock(200, self.crumb_data),  # crumb
+            build_response_mock(400),  # request
+        ])
+
+        self.j.create_folder(u'Folder-that-already-exists', ignore_failures=True)