Allow setting the next build number

We can discover the next build number Jenkins will use for a particular
job using get_job_info(), but there's currently no way through
python-jenkins to set the next build number.  This change introduces
the set_next_build_number() method which, given a job name and a
desired number, sets the next build number of the named job to the
given number.

Limitations: Jenkins enforces that build numbers must be monotonically
increasing, but gives no indication of an error; it simply ignores the
offending value.

Change-Id: I23b5a84b7ea37d66bf778a89343e3c81ffa9ceb6

README.rst

@@ -24,6 +24,7 @@ the things you can use it for:
 * Put server in shutdown mode (quiet down)
 * List running builds
 * Create/delete/update folders [#f1]_
+* Set the next build number [#f2]_
 * and many more..
 
 To install::
@@ -85,3 +86,7 @@ Then install the required python packages using pip_::
     <https://wiki.jenkins-ci.org/display/JENKINS/CloudBees+Folders+Plugin>`_
     provides support for a subset of the full folders functionality. For the
     complete capabilities you will need the paid for version of the plugin.
+
+.. [#f2] The `Next Build Number Plugin
+   <https://wiki.jenkins-ci.org/display/JENKINS/Next+Build+Number+Plugin>`_
+   provides support for setting the next build number.

doc/source/examples.rst

@@ -134,3 +134,19 @@ This is an example showing how to create, configure and delete Jenkins folders.
     server.copy_job('folder/empty', 'folder/empty_copy')
     server.delete_job('folder/empty_copy')
     server.delete_job('folder')
+
+
+Example 8: Updating Next Build Number
+-------------------------------------
+
+Requires the `Next Build Number Plugin
+<https://wiki.jenkins-ci.org/display/JENKINS/Next+Build+Number+Plugin>`_
+for Jenkins.
+
+This is an example showing how to update the next build number for a
+Jenkins job.
+
+::
+
+    next_bn = server.get_job_info('job_name')['nextBuildNumber']
+    server.set_next_build_number('job_name', next_bn + 50)

jenkins/__init__.py

@@ -84,6 +84,7 @@ CONFIG_JOB = '%(folder_url)sjob/%(short_name)s/config.xml'
 DELETE_JOB = '%(folder_url)sjob/%(short_name)s/doDelete'
 ENABLE_JOB = '%(folder_url)sjob/%(short_name)s/enable'
 DISABLE_JOB = '%(folder_url)sjob/%(short_name)s/disable'
+SET_JOB_BUILD_NUMBER = '%(folder_url)sjob/%(short_name)s/nextbuildnumber/submit'
 COPY_JOB = '%(from_folder_url)screateItem?name=%(to_short_name)s&mode=copy&from=%(from_short_name)s'
 RENAME_JOB = '%(from_folder_url)sjob/%(from_short_name)s/doRename?newName=%(to_short_name)s'
 BUILD_JOB = '%(folder_url)sjob/%(short_name)s/build'
@@ -716,6 +717,31 @@ class Jenkins(object):
         self.jenkins_open(Request(
             self._build_url(DISABLE_JOB, locals()), b''))
 
+    def set_next_build_number(self, name, number):
+        '''Set a job's next build number.
+
+        The current next build number is contained within the job
+        information retrieved using :meth:`Jenkins.get_job_info`.  If
+        the specified next build number is less than the last build
+        number, Jenkins will ignore the request.
+
+        Note that the `Next Build Number Plugin
+        <https://wiki.jenkins-ci.org/display/JENKINS/Next+Build+Number+Plugin>`_
+        must be installed to enable this functionality.
+
+        :param name: Name of Jenkins job, ``str``
+        :param number: Next build number to set, ``int``
+
+        Example::
+
+            >>> next_bn = server.get_job_info('job_name')['nextBuildNumber']
+            >>> server.set_next_build_number('job_name', next_bn + 50)
+        '''
+        folder_url, short_name = self._get_job_folder(name)
+        self.jenkins_open(
+            Request(self._build_url(SET_JOB_BUILD_NUMBER, locals()),
+                    ("nextBuildNumber=%d" % number).encode('utf-8')))
+
     def job_exists(self, name):
         '''Check whether a job exists
 

tests/jobs/test_set_next_build_number.py

@@ -0,0 +1,19 @@
+from mock import patch
+
+import jenkins
+from tests.jobs.base import JenkinsJobsTestBase
+
+
+class JenkinsSetNextBuildNumberTest(JenkinsJobsTestBase):
+
+    @patch.object(jenkins.Jenkins, 'jenkins_open')
+    def test_simple(self, jenkins_mock):
+        self.j.set_next_build_number('TestJob', 1234)
+
+        self.assertEqual(
+            jenkins_mock.call_args[0][0].get_full_url(),
+            u'http://example.com/job/TestJob/nextbuildnumber/submit')
+        self.assertEqual(
+            jenkins_mock.call_args[0][0].data,
+            b'nextBuildNumber=1234')
+        self._check_requests(jenkins_mock.call_args_list)