volumes,create: support adding labels

Fixes #1102
Signed-off-by: Tomas Tomecek <ttomecek@redhat.com>

docker/api/volume.py

+from .. import errors
 from .. import utils
 
 
@@ -11,7 +12,7 @@ class VolumeApiMixin(object):
         return self._result(self._get(url, params=params), True)
 
     @utils.minimum_version('1.21')
-    def create_volume(self, name, driver=None, driver_opts=None):
+    def create_volume(self, name, driver=None, driver_opts=None, labels=None):
         url = self._url('/volumes/create')
         if driver_opts is not None and not isinstance(driver_opts, dict):
             raise TypeError('driver_opts must be a dictionary')
@@ -21,6 +22,16 @@ class VolumeApiMixin(object):
             'Driver': driver,
             'DriverOpts': driver_opts,
         }
+
+        if labels is not None:
+            if utils.compare_version('1.23', self._version) < 0:
+                raise errors.InvalidVersion(
+                    'volume labels were introduced in API 1.23'
+                )
+            if not isinstance(labels, dict):
+                raise TypeError('labels must be a dictionary')
+            data["Labels"] = labels
+
         return self._result(self._post_json(url, data=data), True)
 
     @utils.minimum_version('1.21')

docs/api.md

@@ -310,6 +310,7 @@ Create and register a named volume
 * name (str): Name of the volume
 * driver (str): Name of the driver used to create the volume
 * driver_opts (dict): Driver options as a key-value dictionary
+* labels (dict): Labels to set on the volume
 
 **Returns** (dict): The created volume reference object
 
@@ -317,10 +318,16 @@ Create and register a named volume
 >>> from docker import Client
 >>> cli = Client()
 >>> volume = cli.create_volume(
-  name='foobar', driver='local', driver_opts={'foo': 'bar', 'baz': 'false'}
+  name='foobar', driver='local', driver_opts={'foo': 'bar', 'baz': 'false'},
+  labels={"key": "value"}
 )
 >>> print(volume)
-{u'Mountpoint': u'/var/lib/docker/volumes/foobar/_data', u'Driver': u'local', u'Name': u'foobar'}
+{
+  u'Mountpoint': u'/var/lib/docker/volumes/foobar/_data',
+  u'Driver': u'local',
+  u'Name': u'foobar',
+  u'Labels': {u'key': u'value'}
+}
 ```
 
 ## diff

tests/unit/fake_api.py

@@ -433,7 +433,10 @@ def get_fake_volume():
     response = {
         'Name': 'perfectcherryblossom',
         'Driver': 'local',
-        'Mountpoint': '/var/lib/docker/volumes/perfectcherryblossom'
+        'Mountpoint': '/var/lib/docker/volumes/perfectcherryblossom',
+        'Labels': {
+            'com.example.some-label': 'some-value'
+        }
     }
     return status_code, response
 

tests/unit/volume_test.py

@@ -43,6 +43,22 @@ class VolumeTest(DockerClientTest):
         self.assertEqual(args[0][1], url_prefix + 'volumes/create')
         self.assertEqual(json.loads(args[1]['data']), {'Name': name})
 
+    @base.requires_api_version('1.23')
+    def test_create_volume_with_labels(self):
+        name = 'perfectcherryblossom'
+        result = self.client.create_volume(name, labels={
+            'com.example.some-label': 'some-value'})
+        self.assertEqual(
+            result["Labels"],
+            {'com.example.some-label': 'some-value'}
+        )
+
+    @base.requires_api_version('1.23')
+    def test_create_volume_with_invalid_labels(self):
+        name = 'perfectcherryblossom'
+        with pytest.raises(TypeError):
+            self.client.create_volume(name, labels=1)
+
     @base.requires_api_version('1.21')
     def test_create_volume_with_driver(self):
         name = 'perfectcherryblossom'