diff options
author | Joffrey F <f.joffrey@gmail.com> | 2018-12-11 08:41:33 -0800 |
---|---|---|
committer | GitHub <noreply@github.com> | 2018-12-11 08:41:33 -0800 |
commit | d77d4256d7eca17c72af81f636f45ebf1e6c6681 (patch) | |
tree | 326cdf5c6bbafad6af970fc2df326d7234e9ba85 | |
parent | f39b1df407fcc695de6871710a9688222f5e0193 (diff) | |
parent | b297b837df511178a69f29a9f8461aee0193e278 (diff) | |
download | docker-py-d77d4256d7eca17c72af81f636f45ebf1e6c6681.tar.gz |
Merge pull request #2197 from docker/2185-placement-prefs
Improve handling of placement preferences and associated docs
-rw-r--r-- | docker/models/services.py | 10 | ||||
-rw-r--r-- | docker/types/__init__.py | 5 | ||||
-rw-r--r-- | docker/types/services.py | 41 | ||||
-rw-r--r-- | docs/api.rst | 1 | ||||
-rw-r--r-- | docs/conf.py | 8 |
5 files changed, 49 insertions, 16 deletions
diff --git a/docker/models/services.py b/docker/models/services.py index a2a3ed0..5d2bd9b 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 6451233..f3cac1b 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 c66d41a..79794d7 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 1682128..edb8fff 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 diff --git a/docs/conf.py b/docs/conf.py index 3e17678..f46d1f7 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. |