From e15db4cb20b22c97e5df5f4fc2fdb54c18e785e9 Mon Sep 17 00:00:00 2001 From: Joffrey F Date: Fri, 7 Dec 2018 16:56:45 -0800 Subject: [PATCH 1/2] Improve handling of placement preferences; improve docs Signed-off-by: Joffrey F --- docker/models/services.py | 10 ++++++---- docker/types/__init__.py | 5 +++-- docker/types/services.py | 41 ++++++++++++++++++++++++++++++++------- docs/api.rst | 1 + 4 files changed, 44 insertions(+), 13 deletions(-) diff --git a/docker/models/services.py b/docker/models/services.py index a2a3ed01..5d2bd9b3 100644 --- a/docker/models/services.py +++ b/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``. diff --git a/docker/types/__init__.py b/docker/types/__init__.py index 64512333..f3cac1bc 100644 --- a/docker/types/__init__.py +++ b/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 diff --git a/docker/types/services.py b/docker/types/services.py index c66d41a1..79794d7e 100644 --- a/docker/types/services.py +++ b/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 diff --git a/docs/api.rst b/docs/api.rst index 16821289..edb8fffa 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -143,6 +143,7 @@ Configuration types .. autoclass:: LogConfig .. autoclass:: Mount .. autoclass:: Placement +.. autoclass:: PlacementPreference .. autoclass:: Privileges .. autoclass:: Resources .. autoclass:: RestartPolicy From b297b837df511178a69f29a9f8461aee0193e278 Mon Sep 17 00:00:00 2001 From: Joffrey F Date: Fri, 7 Dec 2018 16:57:40 -0800 Subject: [PATCH 2/2] Dynamically retrieve version information for generated docs Signed-off-by: Joffrey F --- docs/conf.py | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 3e17678a..f46d1f76 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -69,10 +69,12 @@ author = u'Docker Inc' # |version| and |release|, also used in various other places throughout the # built documents. # -# The short X.Y version. -version = u'2.0' +with open('../docker/version.py', 'r') as vfile: + exec(vfile.read()) # The full version, including alpha/beta/rc tags. -release = u'2.0' +release = version +# The short X.Y version. +version = '{}.{}'.format(version_info[0], version_info[1]) # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages.