Merge pull request #1319 from docker/config_types

Move config type creation from docker.utils functions to classes in docker.types

docker/api/container.py

@@ -4,7 +4,9 @@ from datetime import datetime
 
 from .. import errors
 from .. import utils
-from ..utils.utils import create_networking_config, create_endpoint_config
+from ..types import (
+    ContainerConfig, EndpointConfig, HostConfig, NetworkingConfig
+)
 
 
 class ContainerApiMixin(object):
@@ -430,8 +432,8 @@ class ContainerApiMixin(object):
             )
 
         config = self.create_container_config(
-            image, command, hostname, user, detach, stdin_open,
-            tty, mem_limit, ports, environment, dns, volumes, volumes_from,
+            image, command, hostname, user, detach, stdin_open, tty, mem_limit,
+            ports, dns, environment, volumes, volumes_from,
             network_disabled, entrypoint, cpu_shares, working_dir, domainname,
             memswap_limit, cpuset, host_config, mac_address, labels,
             volume_driver, stop_signal, networking_config, healthcheck,
@@ -439,7 +441,7 @@ class ContainerApiMixin(object):
         return self.create_container_from_config(config, name)
 
     def create_container_config(self, *args, **kwargs):
-        return utils.create_container_config(self._version, *args, **kwargs)
+        return ContainerConfig(self._version, *args, **kwargs)
 
     def create_container_from_config(self, config, name=None):
         u = self._url("/containers/create")
@@ -582,7 +584,7 @@ class ContainerApiMixin(object):
                 "keyword argument 'version'"
             )
         kwargs['version'] = self._version
-        return utils.create_host_config(*args, **kwargs)
+        return HostConfig(*args, **kwargs)
 
     def create_networking_config(self, *args, **kwargs):
         """
@@ -608,7 +610,7 @@ class ContainerApiMixin(object):
             )
 
         """
-        return create_networking_config(*args, **kwargs)
+        return NetworkingConfig(*args, **kwargs)
 
     def create_endpoint_config(self, *args, **kwargs):
         """
@@ -641,7 +643,7 @@ class ContainerApiMixin(object):
             )
 
         """
-        return create_endpoint_config(self._version, *args, **kwargs)
+        return EndpointConfig(self._version, *args, **kwargs)
 
     @utils.check_resource
     def diff(self, container):

docker/api/network.py

@@ -46,8 +46,7 @@ class NetworkApiMixin(object):
             name (str): Name of the network
             driver (str): Name of the driver used to create the network
             options (dict): Driver options as a key-value dictionary
-            ipam (dict): Optional custom IP scheme for the network.
-                Created with :py:meth:`~docker.utils.create_ipam_config`.
+            ipam (IPAMConfig): Optional custom IP scheme for the network.
             check_duplicate (bool): Request daemon to check for networks with
                 same name. Default: ``True``.
             internal (bool): Restrict external access to the network. Default
@@ -74,11 +73,11 @@ class NetworkApiMixin(object):
 
             .. code-block:: python
 
-                >>> ipam_pool = docker.utils.create_ipam_pool(
+                >>> ipam_pool = docker.types.IPAMPool(
                     subnet='192.168.52.0/24',
                     gateway='192.168.52.254'
                 )
-                >>> ipam_config = docker.utils.create_ipam_config(
+                >>> ipam_config = docker.types.IPAMConfig(
                     pool_configs=[ipam_pool]
                 )
                 >>> docker_client.create_network("network1", driver="bridge",

docker/api/swarm.py

 import logging
 from six.moves import http_client
+from .. import types
 from .. import utils
 log = logging.getLogger(__name__)
 
@@ -50,7 +51,7 @@ class SwarmApiMixin(object):
               force_new_cluster=False, swarm_spec=spec
             )
         """
-        return utils.SwarmSpec(*args, **kwargs)
+        return types.SwarmSpec(*args, **kwargs)
 
     @utils.minimum_version('1.24')
     def init_swarm(self, advertise_addr=None, listen_addr='0.0.0.0:2377',

docker/models/containers.py

@@ -2,7 +2,7 @@ import copy
 
 from ..errors import (ContainerError, ImageNotFound,
                       create_unexpected_kwargs_error)
-from ..utils import create_host_config
+from ..types import HostConfig
 from .images import Image
 from .resource import Collection, Model
 
@@ -869,7 +869,7 @@ def _create_container_args(kwargs):
     if kwargs:
         raise create_unexpected_kwargs_error('run', kwargs)
 
-    create_kwargs['host_config'] = create_host_config(**host_config_kwargs)
+    create_kwargs['host_config'] = HostConfig(**host_config_kwargs)
 
     # Fill in any kwargs which need processing by create_host_config first
     port_bindings = create_kwargs['host_config'].get('PortBindings')

docker/models/networks.py

@@ -98,7 +98,7 @@ class NetworkCollection(Collection):
             driver (str): Name of the driver used to create the network
             options (dict): Driver options as a key-value dictionary
             ipam (dict): Optional custom IP scheme for the network.
-                Created with :py:meth:`~docker.utils.create_ipam_config`.
+                Created with :py:class:`~docker.types.IPAMConfig`.
             check_duplicate (bool): Request daemon to check for networks with
                 same name. Default: ``True``.
             internal (bool): Restrict external access to the network. Default
@@ -125,11 +125,11 @@ class NetworkCollection(Collection):
 
             .. code-block:: python
 
-                >>> ipam_pool = docker.utils.create_ipam_pool(
+                >>> ipam_pool = docker.types.IPAMPool(
                     subnet='192.168.52.0/24',
                     gateway='192.168.52.254'
                 )
-                >>> ipam_config = docker.utils.create_ipam_config(
+                >>> ipam_config = docker.types.IPAMConfig(
                     pool_configs=[ipam_pool]
                 )
                 >>> client.networks.create(

docker/types/__init__.py

 # flake8: noqa
-from .containers import LogConfig, Ulimit
+from .containers import ContainerConfig, HostConfig, LogConfig, Ulimit
+from .healthcheck import Healthcheck
+from .networks import EndpointConfig, IPAMConfig, IPAMPool, NetworkingConfig
 from .services import (
     ContainerSpec, DriverConfig, EndpointSpec, Mount, Resources, RestartPolicy,
     TaskTemplate, UpdateConfig
 )
-from .healthcheck import Healthcheck
 from .swarm import SwarmSpec, SwarmExternalCA

docker/types/networks.py

+from .. import errors
+from ..utils import normalize_links, version_lt
+
+
+class EndpointConfig(dict):
+    def __init__(self, version, aliases=None, links=None, ipv4_address=None,
+                 ipv6_address=None, link_local_ips=None):
+        if version_lt(version, '1.22'):
+            raise errors.InvalidVersion(
+                'Endpoint config is not supported for API version < 1.22'
+            )
+
+        if aliases:
+            self["Aliases"] = aliases
+
+        if links:
+            self["Links"] = normalize_links(links)
+
+        ipam_config = {}
+        if ipv4_address:
+            ipam_config['IPv4Address'] = ipv4_address
+
+        if ipv6_address:
+            ipam_config['IPv6Address'] = ipv6_address
+
+        if link_local_ips is not None:
+            if version_lt(version, '1.24'):
+                raise errors.InvalidVersion(
+                    'link_local_ips is not supported for API version < 1.24'
+                )
+            ipam_config['LinkLocalIPs'] = link_local_ips
+
+        if ipam_config:
+            self['IPAMConfig'] = ipam_config
+
+
+class NetworkingConfig(dict):
+    def __init__(self, endpoints_config=None):
+        if endpoints_config:
+            self["EndpointsConfig"] = endpoints_config
+
+
+class IPAMConfig(dict):
+    """
+    Create an IPAM (IP Address Management) config dictionary to be used with
+    :py:meth:`~docker.api.network.NetworkApiMixin.create_network`.
+
+    Args:
+
+        driver (str): The IPAM driver to use. Defaults to ``default``.
+        pool_configs (list): A list of pool configurations
+          (:py:class:`~docker.types.IPAMPool`). Defaults to empty list.
+
+    Example:
+
+        >>> ipam_config = docker.types.IPAMConfig(driver='default')
+        >>> network = client.create_network('network1', ipam=ipam_config)
+
+    """
+    def __init__(self, driver='default', pool_configs=None):
+        self.update({
+            'Driver': driver,
+            'Config': pool_configs or []
+        })
+
+
+class IPAMPool(dict):
+    """
+    Create an IPAM pool config dictionary to be added to the
+    ``pool_configs`` parameter of
+    :py:class:`~docker.types.IPAMConfig`.
+
+    Args:
+
+        subnet (str): Custom subnet for this IPAM pool using the CIDR
+            notation. Defaults to ``None``.
+        iprange (str): Custom IP range for endpoints in this IPAM pool using
+            the CIDR notation. Defaults to ``None``.
+        gateway (str): Custom IP address for the pool's gateway.
+        aux_addresses (dict): A dictionary of ``key -> ip_address``
+            relationships specifying auxiliary addresses that need to be
+            allocated by the IPAM driver.
+
+    Example:
+
+        >>> ipam_pool = docker.types.IPAMPool(
+            subnet='124.42.0.0/16',
+            iprange='124.42.0.0/24',
+            gateway='124.42.0.254',
+            aux_addresses={
+                'reserved1': '124.42.1.1'
+            }
+        )
+        >>> ipam_config = docker.types.IPAMConfig(
+                pool_configs=[ipam_pool])
+    """
+    def __init__(self, subnet=None, iprange=None, gateway=None,
+                 aux_addresses=None):
+        self.update({
+            'Subnet': subnet,
+            'IPRange': iprange,
+            'Gateway': gateway,
+            'AuxiliaryAddresses': aux_addresses
+        })

docker/utils/__init__.py

@@ -3,12 +3,9 @@ from .utils import (
     compare_version, convert_port_bindings, convert_volume_binds,
     mkbuildcontext, tar, exclude_paths, parse_repository_tag, parse_host,
     kwargs_from_env, convert_filters, datetime_to_timestamp,
-    create_host_config, create_container_config, parse_bytes, ping_registry,
-    parse_env_file, version_lt, version_gte, decode_json_header, split_command,
-    create_ipam_config, create_ipam_pool, parse_devices, normalize_links,
-    convert_service_networks,
+    create_host_config, parse_bytes, ping_registry, parse_env_file, version_lt,
+    version_gte, decode_json_header, split_command, create_ipam_config,
+    create_ipam_pool, parse_devices, normalize_links, convert_service_networks,
 )
 
-from ..types import LogConfig, Ulimit
-from ..types import SwarmExternalCA, SwarmSpec
 from .decorators import check_resource, minimum_version, update_headers

docker/utils/types.py

-# Compatibility module. See https://github.com/docker/docker-py/issues/1196
-
-import warnings
-
-from ..types import Ulimit, LogConfig  # flake8: noqa
-
-warnings.warn('docker.utils.types is now docker.types', ImportWarning)

docs/api.rst

@@ -49,15 +49,6 @@ Networks
   :members:
   :undoc-members:
 
-Utilities
-~~~~~~~~~
-
-These functions are available under ``docker.utils`` to create arguments
-for :py:meth:`create_network`:
-
-.. autofunction:: docker.utils.create_ipam_config
-.. autofunction:: docker.utils.create_ipam_pool
-
 Volumes
 -------
 
@@ -107,3 +98,19 @@ The Docker daemon
 .. autoclass:: DaemonApiMixin
   :members:
   :undoc-members:
+
+Configuration types
+-------------------
+
+.. py:module:: docker.types
+
+.. autoclass:: IPAMConfig
+.. autoclass:: IPAMPool
+.. autoclass:: ContainerSpec
+.. autoclass:: DriverConfig
+.. autoclass:: EndpointSpec
+.. autoclass:: Mount
+.. autoclass:: Resources
+.. autoclass:: RestartPolicy
+.. autoclass:: TaskTemplate
+.. autoclass:: UpdateConfig

tests/integration/api_container_test.py

@@ -255,7 +255,7 @@ class CreateContainerTest(BaseAPIIntegrationTest):
         self.assertIn('1001', groups)
 
     def test_valid_log_driver_and_log_opt(self):
-        log_config = docker.utils.LogConfig(
+        log_config = docker.types.LogConfig(
             type='json-file',
             config={'max-file': '100'}
         )
@@ -274,7 +274,7 @@ class CreateContainerTest(BaseAPIIntegrationTest):
         self.assertEqual(container_log_config['Config'], log_config.config)
 
     def test_invalid_log_driver_raises_exception(self):
-        log_config = docker.utils.LogConfig(
+        log_config = docker.types.LogConfig(
             type='asdf-nope',
             config={}
         )
@@ -292,7 +292,7 @@ class CreateContainerTest(BaseAPIIntegrationTest):
         assert excinfo.value.explanation == expected_msg
 
     def test_valid_no_log_driver_specified(self):
-        log_config = docker.utils.LogConfig(
+        log_config = docker.types.LogConfig(
             type="",
             config={'max-file': '100'}
         )
@@ -311,7 +311,7 @@ class CreateContainerTest(BaseAPIIntegrationTest):
         self.assertEqual(container_log_config['Config'], log_config.config)
 
     def test_valid_no_config_specified(self):
-        log_config = docker.utils.LogConfig(
+        log_config = docker.types.LogConfig(
             type="json-file",
             config=None
         )

tests/integration/api_network_test.py

 import docker
-from docker.utils import create_ipam_config
-from docker.utils import create_ipam_pool
+from docker.types import IPAMConfig, IPAMPool
 import pytest
 
 from ..helpers import random_name, requires_api_version
@@ -45,10 +44,10 @@ class TestNetworks(BaseAPIIntegrationTest):
     @requires_api_version('1.21')
     def test_create_network_with_ipam_config(self):
         _, net_id = self.create_network(
-            ipam=create_ipam_config(
+            ipam=IPAMConfig(
                 driver='default',
                 pool_configs=[
-                    create_ipam_pool(
+                    IPAMPool(
                         subnet="172.28.0.0/16",
                         iprange="172.28.5.0/24",
                         gateway="172.28.5.254",
@@ -217,9 +216,9 @@ class TestNetworks(BaseAPIIntegrationTest):
     @requires_api_version('1.22')
     def test_create_with_ipv4_address(self):
         net_name, net_id = self.create_network(
-            ipam=create_ipam_config(
+            ipam=IPAMConfig(
                 driver='default',
-                pool_configs=[create_ipam_pool(subnet="132.124.0.0/16")],
+                pool_configs=[IPAMPool(subnet="132.124.0.0/16")],
             ),
         )
         container = self.client.create_container(
@@ -246,9 +245,9 @@ class TestNetworks(BaseAPIIntegrationTest):
     @requires_api_version('1.22')
     def test_create_with_ipv6_address(self):
         net_name, net_id = self.create_network(
-            ipam=create_ipam_config(
+            ipam=IPAMConfig(
                 driver='default',
-                pool_configs=[create_ipam_pool(subnet="2001:389::1/64")],
+                pool_configs=[IPAMPool(subnet="2001:389::1/64")],
             ),
         )
         container = self.client.create_container(
@@ -353,10 +352,10 @@ class TestNetworks(BaseAPIIntegrationTest):
     @requires_api_version('1.22')
     def test_connect_with_ipv4_address(self):
         net_name, net_id = self.create_network(
-            ipam=create_ipam_config(
+            ipam=IPAMConfig(
                 driver='default',
                 pool_configs=[
-                    create_ipam_pool(
+                    IPAMPool(
                         subnet="172.28.0.0/16", iprange="172.28.5.0/24",
                         gateway="172.28.5.254"
                     )
@@ -381,10 +380,10 @@ class TestNetworks(BaseAPIIntegrationTest):
     @requires_api_version('1.22')
     def test_connect_with_ipv6_address(self):
         net_name, net_id = self.create_network(
-            ipam=create_ipam_config(
+            ipam=IPAMConfig(
                 driver='default',
                 pool_configs=[
-                    create_ipam_pool(
+                    IPAMPool(
                         subnet="2001:389::1/64", iprange="2001:389::0/96",
                         gateway="2001:389::ffff"
                     )

tests/unit/api_network_test.py

@@ -4,7 +4,7 @@ import six
 
 from .api_test import BaseAPIClientTest, url_prefix, response
 from ..helpers import requires_api_version
-from docker.utils import create_ipam_config, create_ipam_pool
+from docker.types import IPAMConfig, IPAMPool
 
 try:
     from unittest import mock
@@ -81,9 +81,9 @@ class NetworkTest(BaseAPIClientTest):
                 json.loads(post.call_args[1]['data']),
                 {"Name": "foo", "Driver": "bridge", "Options": opts})
 
-            ipam_pool_config = create_ipam_pool(subnet="192.168.52.0/24",
-                                                gateway="192.168.52.254")
-            ipam_config = create_ipam_config(pool_configs=[ipam_pool_config])
+            ipam_pool_config = IPAMPool(subnet="192.168.52.0/24",
+                                        gateway="192.168.52.254")
+            ipam_config = IPAMConfig(pool_configs=[ipam_pool_config])
 
             self.client.create_network("bar", driver="bridge",
                                        ipam=ipam_config)