Improve handling of placement preferences; improve docs

Signed-off-by: Joffrey F <joffrey@docker.com>

docker/models/services.py

@@ -153,10 +153,12 @@ class ServiceCollection(Collection):
             image (str): The image name to use for the containers.
             command (list of str or str): Command to run.
             args (list of str): Arguments to the command.
-            constraints (list of str): Placement constraints.
-            preferences (list of str): Placement preferences.
-            platforms (list of tuple): A list of platforms constraints
-                expressed as ``(arch, os)`` tuples
+            constraints (list of str): :py:class:`~docker.types.Placement`
+                constraints.
+            preferences (list of tuple): :py:class:`~docker.types.Placement`
+                preferences.
+            platforms (list of tuple): A list of platform constraints
+                expressed as ``(arch, os)`` tuples.
             container_labels (dict): Labels to apply to the container.
             endpoint_spec (EndpointSpec): Properties that can be configured to
                 access and load balance a service. Default: ``None``.

docker/types/__init__.py

@@ -5,7 +5,8 @@ from .healthcheck import Healthcheck
 from .networks import EndpointConfig, IPAMConfig, IPAMPool, NetworkingConfig
 from .services import (
     ConfigReference, ContainerSpec, DNSConfig, DriverConfig, EndpointSpec,
-    Mount, Placement, Privileges, Resources, RestartPolicy, RollbackConfig,
-    SecretReference, ServiceMode, TaskTemplate, UpdateConfig
+    Mount, Placement, PlacementPreference, Privileges, Resources,
+    RestartPolicy, RollbackConfig, SecretReference, ServiceMode, TaskTemplate,
+    UpdateConfig
 )
 from .swarm import SwarmSpec, SwarmExternalCA

docker/types/services.py

@@ -648,18 +648,24 @@ class Placement(dict):
         Placement constraints to be used as part of a :py:class:`TaskTemplate`
 
         Args:
-            constraints (:py:class:`list`): A list of constraints
-            preferences (:py:class:`list`): Preferences provide a way to make
-                the scheduler aware of factors such as topology. They are
-                provided in order from highest to lowest precedence.
-            platforms (:py:class:`list`): A list of platforms expressed as
-                ``(arch, os)`` tuples
+            constraints (:py:class:`list` of str): A list of constraints
+            preferences (:py:class:`list` of tuple): Preferences provide a way
+                to make the scheduler aware of factors such as topology. They
+                are provided in order from highest to lowest precedence and
+                are expressed as ``(strategy, descriptor)`` tuples. See
+                :py:class:`PlacementPreference` for details.
+            platforms (:py:class:`list` of tuple): A list of platforms
+                expressed as ``(arch, os)`` tuples
     """
     def __init__(self, constraints=None, preferences=None, platforms=None):
         if constraints is not None:
             self['Constraints'] = constraints
         if preferences is not None:
-            self['Preferences'] = preferences
+            self['Preferences'] = []
+            for pref in preferences:
+                if isinstance(pref, tuple):
+                    pref = PlacementPreference(*pref)
+                self['Preferences'].append(pref)
         if platforms:
             self['Platforms'] = []
             for plat in platforms:
@@ -668,6 +674,27 @@ class Placement(dict):
                 })
 
 
+class PlacementPreference(dict):
+    """
+        Placement preference to be used as an element in the list of
+        preferences for :py:class:`Placement` objects.
+
+        Args:
+            strategy (string): The placement strategy to implement. Currently,
+                the only supported strategy is ``spread``.
+            descriptor (string): A label descriptor. For the spread strategy,
+                the scheduler will try to spread tasks evenly over groups of
+                nodes identified by this label.
+    """
+    def __init__(self, strategy, descriptor):
+        if strategy != 'spread':
+            raise errors.InvalidArgument(
+                'PlacementPreference strategy value is invalid ({}):'
+                ' must be "spread".'.format(strategy)
+            )
+        self['SpreadOver'] = descriptor
+
+
 class DNSConfig(dict):
     """
         Specification for DNS related configurations in resolver configuration

docs/api.rst

@@ -143,6 +143,7 @@ Configuration types
 .. autoclass:: LogConfig
 .. autoclass:: Mount
 .. autoclass:: Placement
+.. autoclass:: PlacementPreference
 .. autoclass:: Privileges
 .. autoclass:: Resources
 .. autoclass:: RestartPolicy