Support copyartifact build selector param

Allow defining of a build selector build parameter to be used by the
copyartifact plugin.

Change-Id: Iac3a3812354c514936ba89ca04dbd7f9ad193073

jenkins_jobs/modules/builders.py

@@ -45,6 +45,7 @@ from jenkins_jobs.modules.helpers import cloudformation_region_dict
 from jenkins_jobs.modules.helpers import cloudformation_stack
 from jenkins_jobs.modules.helpers import config_file_provider_builder
 from jenkins_jobs.modules.helpers import config_file_provider_settings
+from jenkins_jobs.modules.helpers import copyartifact_build_selector
 from jenkins_jobs.errors import (JenkinsJobsException,
                                  MissingAttributeError,
                                  InvalidAttributeError)
@@ -101,10 +102,30 @@ def copyartifact(parser, xml_parent, data):
         (default: false)
     :arg str which-build: which build to get artifacts from
         (optional, default last-successful)
+
+        :which-build values:
+            * **last-successful**
+            * **last-completed**
+            * **specific-build**
+            * **last-saved**
+            * **upstream-build**
+            * **permalink**
+            * **workspace-latest**
+            * **build-param**
+
     :arg str build-number: specifies the build number to get when
         when specific-build is specified as which-build
     :arg str permalink: specifies the permalink to get when
         permalink is specified as which-build
+
+        :permalink values:
+            * **last**
+            * **last-stable**
+            * **last-successful**
+            * **last-failed**
+            * **last-unstable**
+            * **last-unsuccessful**
+
     :arg bool stable: specifies to get only last stable build when
         last-successful is specified as which-build
     :arg bool fallback-to-last-successful: specifies to fallback to
@@ -113,22 +134,6 @@ def copyartifact(parser, xml_parent, data):
         build-param is specified as which-build
     :arg string parameter-filters: Filter matching jobs based on these
         parameters (optional)
-    :which-build values:
-      * **last-successful**
-      * **last-completed**
-      * **specific-build**
-      * **last-saved**
-      * **upstream-build**
-      * **permalink**
-      * **workspace-latest**
-      * **build-param**
-    :permalink values:
-      * **last**
-      * **last-stable**
-      * **last-successful**
-      * **last-failed**
-      * **last-unstable**
-      * **last-unsuccessful**
 
 
     Example:
@@ -140,7 +145,10 @@ def copyartifact(parser, xml_parent, data):
     # Warning: this only works with copy artifact version 1.26+,
     # for copy artifact version 1.25- the 'projectName' element needs
     # to be used instead of 'project'
-    XML.SubElement(t, 'project').text = data["project"]
+    try:
+        XML.SubElement(t, 'project').text = data["project"]
+    except KeyError:
+        raise MissingAttributeError('project')
     XML.SubElement(t, 'filter').text = data.get("filter", "")
     XML.SubElement(t, 'target').text = data.get("target", "")
     flatten = data.get("flatten", False)
@@ -148,45 +156,7 @@ def copyartifact(parser, xml_parent, data):
     optional = data.get('optional', False)
     XML.SubElement(t, 'optional').text = str(optional).lower()
     XML.SubElement(t, 'parameters').text = data.get("parameter-filters", "")
-    select = data.get('which-build', 'last-successful')
-    selectdict = {'last-successful': 'StatusBuildSelector',
-                  'last-completed': 'LastCompletedBuildSelector',
-                  'specific-build': 'SpecificBuildSelector',
-                  'last-saved': 'SavedBuildSelector',
-                  'upstream-build': 'TriggeredBuildSelector',
-                  'permalink': 'PermalinkBuildSelector',
-                  'workspace-latest': 'WorkspaceSelector',
-                  'build-param': 'ParameterizedBuildSelector'}
-    if select not in selectdict:
-        raise InvalidAttributeError('which-build',
-                                    select,
-                                    selectdict.keys())
-    permalink = data.get('permalink', 'last')
-    permalinkdict = {'last': 'lastBuild',
-                     'last-stable': 'lastStableBuild',
-                     'last-successful': 'lastSuccessfulBuild',
-                     'last-failed': 'lastFailedBuild',
-                     'last-unstable': 'lastUnstableBuild',
-                     'last-unsuccessful': 'lastUnsuccessfulBuild'}
-    if permalink not in permalinkdict:
-        raise InvalidAttributeError('permalink',
-                                    permalink,
-                                    permalinkdict.keys())
-    selector = XML.SubElement(t, 'selector',
-                              {'class': 'hudson.plugins.copyartifact.' +
-                               selectdict[select]})
-    if select == 'specific-build':
-        XML.SubElement(selector, 'buildNumber').text = data['build-number']
-    if select == 'last-successful':
-        XML.SubElement(selector, 'stable').text = str(
-            data.get('stable', False)).lower()
-    if select == 'upstream-build':
-        XML.SubElement(selector, 'fallbackToLastSuccessful').text = str(
-            data.get('fallback-to-last-successful', False)).lower()
-    if select == 'permalink':
-        XML.SubElement(selector, 'id').text = permalinkdict[permalink]
-    if select == 'build-param':
-        XML.SubElement(selector, 'parameterName').text = data['param']
+    copyartifact_build_selector(t, data)
 
 
 def change_assembly_version(parser, xml_parent, data):

jenkins_jobs/modules/helpers.py

@@ -162,6 +162,49 @@ def config_file_provider_settings(xml_parent, data):
                        {'class': settings['default-global-settings']})
 
 
+def copyartifact_build_selector(xml_parent, data, select_tag='selector'):
+
+    select = data.get('which-build', 'last-successful')
+    selectdict = {'last-successful': 'StatusBuildSelector',
+                  'last-completed': 'LastCompletedBuildSelector',
+                  'specific-build': 'SpecificBuildSelector',
+                  'last-saved': 'SavedBuildSelector',
+                  'upstream-build': 'TriggeredBuildSelector',
+                  'permalink': 'PermalinkBuildSelector',
+                  'workspace-latest': 'WorkspaceSelector',
+                  'build-param': 'ParameterizedBuildSelector'}
+    if select not in selectdict:
+        raise InvalidAttributeError('which-build',
+                                    select,
+                                    selectdict.keys())
+    permalink = data.get('permalink', 'last')
+    permalinkdict = {'last': 'lastBuild',
+                     'last-stable': 'lastStableBuild',
+                     'last-successful': 'lastSuccessfulBuild',
+                     'last-failed': 'lastFailedBuild',
+                     'last-unstable': 'lastUnstableBuild',
+                     'last-unsuccessful': 'lastUnsuccessfulBuild'}
+    if permalink not in permalinkdict:
+        raise InvalidAttributeError('permalink',
+                                    permalink,
+                                    permalinkdict.keys())
+    selector = XML.SubElement(xml_parent, select_tag,
+                              {'class': 'hudson.plugins.copyartifact.' +
+                               selectdict[select]})
+    if select == 'specific-build':
+        XML.SubElement(selector, 'buildNumber').text = data['build-number']
+    if select == 'last-successful':
+        XML.SubElement(selector, 'stable').text = str(
+            data.get('stable', False)).lower()
+    if select == 'upstream-build':
+        XML.SubElement(selector, 'fallbackToLastSuccessful').text = str(
+            data.get('fallback-to-last-successful', False)).lower()
+    if select == 'permalink':
+        XML.SubElement(selector, 'id').text = permalinkdict[permalink]
+    if select == 'build-param':
+        XML.SubElement(selector, 'parameterName').text = data['param']
+
+
 def findbugs_settings(xml_parent, data):
     # General Options
     rank_priority = str(data.get('rank-priority', False)).lower()

jenkins_jobs/modules/parameters.py

@@ -36,6 +36,8 @@ Example::
 import xml.etree.ElementTree as XML
 import jenkins_jobs.modules.base
 from jenkins_jobs.errors import JenkinsJobsException
+from jenkins_jobs.errors import MissingAttributeError
+from jenkins_jobs.modules.helpers import copyartifact_build_selector
 
 
 def base_param(parser, xml_parent, data, do_default, ptype):
@@ -617,6 +619,41 @@ def matrix_combinations_param(parser, xml_parent, data):
     return pdef
 
 
+def copyartifact_build_selector_param(parser, xml_parent, data):
+    """yaml: copyartifact-build-selector-param
+
+    Control via a build parameter, which build the copyartifact plugin should
+    copy when it is configured to use 'build-param'. Requires the Jenkins
+    :jenkins-wiki:`Copy Artifact plugin <Copy+Artifact+Plugin>`.
+
+    :arg str name: name of the build parameter to store the selection in
+    :arg str description: a description of the parameter (optional)
+    :arg str which-build: which to provide as the default value in the UI. See
+        ``which-build`` param of :py:mod:`~builders.copyartifact` from the
+        builders module for the available values as well as options available
+        that control additional behaviour for the selected value.
+
+    Example:
+
+    .. literalinclude::
+        /../../tests/parameters/fixtures/copyartifact-build-selector001.yaml
+       :language: yaml
+
+    """
+
+    t = XML.SubElement(xml_parent, 'hudson.plugins.copyartifact.'
+                       'BuildSelectorParameter')
+    try:
+        name = data['name']
+    except KeyError:
+        raise MissingAttributeError('name')
+
+    XML.SubElement(t, 'name').text = name
+    XML.SubElement(t, 'description').text = data.get('description', '')
+
+    copyartifact_build_selector(t, data, 'defaultSelector')
+
+
 class Parameters(jenkins_jobs.modules.base.Base):
     sequence = 21
 

setup.cfg

@@ -109,6 +109,7 @@ jenkins_jobs.properties =
 jenkins_jobs.parameters =
     bool=jenkins_jobs.modules.parameters:bool_param
     choice=jenkins_jobs.modules.parameters:choice_param
+    copyartifact-build-selector=jenkins_jobs.modules.parameters:copyartifact_build_selector_param
     dynamic-choice=jenkins_jobs.modules.parameters:dynamic_choice_param
     dynamic-choice-scriptler=jenkins_jobs.modules.parameters:dynamic_choice_scriptler_param
     dynamic-string=jenkins_jobs.modules.parameters:dynamic_string_param

tests/parameters/fixtures/copyartifact-build-selector001.xml

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="utf-8"?>
+<project>
+  <properties>
+    <hudson.model.ParametersDefinitionProperty>
+      <parameterDefinitions>
+        <hudson.plugins.copyartifact.BuildSelectorParameter>
+          <name>BUILD_SELECTOR</name>
+          <description>Which build from upstream to copy artifacts from</description>
+          <defaultSelector class="hudson.plugins.copyartifact.WorkspaceSelector"/>
+        </hudson.plugins.copyartifact.BuildSelectorParameter>
+      </parameterDefinitions>
+    </hudson.model.ParametersDefinitionProperty>
+  </properties>
+</project>

tests/parameters/fixtures/copyartifact-build-selector001.yaml

@@ -0,0 +1,5 @@
+parameters:
+  - copyartifact-build-selector:
+      name: BUILD_SELECTOR
+      which-build: workspace-latest
+      description: 'Which build from upstream to copy artifacts from'