Merge branch 'master' of github.com:docker/docker-py

Author: shin-

docker/client.py

@@ -526,7 +526,7 @@ def execute(self, container, cmd, detach=False, stdout=True, stderr=True,
             'exec_start instead', DeprecationWarning
         )
         create_res = self.exec_create(
-            container, cmd, detach, stdout, stderr, tty
+            container, cmd, stdout, stderr, tty
         )
 
         return self.exec_start(create_res, detach, tty, stream)
@@ -730,7 +730,7 @@ def insert(self, image, url, path):
             raise errors.DeprecatedMethod(
                 'insert is not available for API version >=1.12'
             )
-        api_url = self._url("/images/{0}/insert".fornat(image))
+        api_url = self._url("/images/{0}/insert".format(image))
         params = {
             'url': url,
             'path': path
@@ -1059,6 +1059,12 @@ def start(self, container, binds=None, port_bindings=None, lxc_conf=None,
         url = self._url("/containers/{0}/start".format(container))
         if not start_config:
             start_config = None
+        elif utils.compare_version('1.15', self._version) > 0:
+            warnings.warn(
+                'Passing host config parameters in start() is deprecated. '
+                'Please use host_config in create_container instead!',
+                DeprecationWarning
+            )
         res = self._post_json(url, data=start_config)
         self._raise_for_status(res)
 

docker/utils/utils.py

@@ -577,6 +577,7 @@ def create_container_config(
         'Entrypoint': entrypoint,
         'CpuShares': cpu_shares,
         'Cpuset': cpuset,
+        'CpusetCpus': cpuset,
         'WorkingDir': working_dir,
         'MemorySwap': memswap_limit,
         'HostConfig': host_config,

docs/api.md

@@ -188,8 +188,7 @@ character, bytes are assumed as an intended unit.
 `volumes_from` and `dns` arguments raise [TypeError](
 https://docs.python.org/3.4/library/exceptions.html#TypeError) exception if
 they are used against v1.10 and above of the Docker remote API. Those
-arguments should be passed to `start()` instead, or as part of the `host_config`
-dictionary.
+arguments should be passed as part of the `host_config` dictionary.
 
 **Params**:
 
@@ -715,83 +714,9 @@ Identical to the `docker search` command.
 Similar to the `docker start` command, but doesn't support attach options. Use
 `.logs()` to recover `stdout`/`stderr`.
 
-`binds` allows to bind a directory in the host to the container. See [Using
-volumes](volumes.md) for more information.
-
-`port_bindings` exposes container ports to the host.
-See [Port bindings](port-bindings.md) for more information.
-
-`lxc_conf` allows to pass LXC configuration options using a dictionary.
-
-`privileged` starts the container in privileged mode.
-
-[Links](http://docs.docker.io/en/latest/use/working_with_links_names/) can be
-specified with the `links` argument. They can either be specified as a
-dictionary mapping name to alias or as a list of `(name, alias)` tuples.
-
-`dns` and `volumes_from` are only available if they are used with version v1.10
-of docker remote API. Otherwise they are ignored.
-
-`network_mode` is available since v1.11 and sets the Network mode for the
-container ('bridge': creates a new network stack for the container on the
-Docker bridge, 'none': no networking for this container, 'container:[name|id]':
-reuses another container network stack), 'host': use the host network stack
-inside the container.
-
-`restart_policy` is available since v1.2.0 and sets the RestartPolicy for how a
-container should or should not be restarted on exit. By default the policy is
-set to no meaning do not restart the container when it exits. The user may
-specify the restart policy as a dictionary for example:
-```python
-{
-    "MaximumRetryCount": 0,
-    "Name": "always"
-}
-```
-
-For always restarting the container on exit or can specify to restart the
-container to restart on failure and can limit number of restarts. For example:
-```python
-{
-    "MaximumRetryCount": 5,
-    "Name": "on-failure"
-}
-```
-
-`cap_add` and `cap_drop` are available since v1.2.0 and can be used to add or
-drop certain capabilities. The user may specify the capabilities as an array
-for example:
-```python
-[
-    "SYS_ADMIN",
-    "MKNOD"
-]
-```
-
-**Params**:
-
-* container (str): The container to start
-* binds: Volumes to bind
-* port_bindings (dict): Port bindings. See note above
-* lxc_conf (dict): LXC config
-* publish_all_ports (bool): Whether to publish all ports to the host
-* links (dict or list of tuples): See note above
-* privileged (bool): Give extended privileges to this container
-* dns (list): Set custom DNS servers
-* dns_search (list): DNS search  domains
-* volumes_from (str or list): List of container names or Ids to get volumes
-from. Optionally a single string joining container id's with commas
-* network_mode (str): One of `['bridge', None, 'container:<name|id>',
-'host']`
-* restart_policy (dict): See note above. "Name" param must be one of
-`['on-failure', 'always']`
-* cap_add (list of str): See note above
-* cap_drop (list of str): See note above
-* extra_hosts (dict): custom host-to-IP mappings (host:ip)
-* pid_mode (str): if set to "host", use the host PID namespace inside the
-  container
-* security_opt (list): A list of string values to customize labels for MLS systems, such as SELinux.
-* ulimits (list): A list of dicts or `docker.utils.Ulimit` objects.
+**Deprecation warning:** For API version > 1.15, it is highly recommended to
+  provide host config options in the
+  [`host_config` parameter of `create_container`](#create_container)
 
 ```python
 >>> from docker import Client

docs/host-devices.md

@@ -1,10 +1,15 @@
 # Access to devices on the host
 
 If you need to directly expose some host devices to a container, you can use
-the devices parameter in the `Client.start` method as shown below
+the devices parameter in the `host_config` param in `Client.create_container`
+as shown below:
 
 ```python
-c.start(container_id, devices=['/dev/sda:/dev/xvda:rwm'])
+c.create_container(
+    'busybox', 'true', host_config=docker.utils.create_host_config(devices=[
+        '/dev/sda:/dev/xvda:rwm'
+    ])
+)
 ```
 
 Each string is a single mapping using the colon (':') as the separator. So the

docs/hostconfig.md

@@ -1,6 +1,8 @@
 # HostConfig object
 
-The Docker Remote API introduced [support for HostConfig in version 1.15](http://docs.docker.com/reference/api/docker_remote_api_v1.15/#create-a-container). This object contains all the parameters you can pass to `Client.start`.
+The Docker Remote API introduced [support for HostConfig in version 1.15](http://docs.docker.com/reference/api/docker_remote_api_v1.15/#create-a-container). This object contains all the parameters you could previously pass to `Client.start`.
+*It is highly recommended that users pass the HostConfig in the `host_config`*
+*param of `Client.create_container` instead of `Client.start`*
 
 ## HostConfig helper
 

docs/port-bindings.md

@@ -1,38 +1,39 @@
 # Port bindings
 Port bindings is done in two parts. Firstly, by providing a list of ports to
 open inside the container in the `Client().create_container()` method.
+Bindings are declared in the `host_config` parameter.
 
 ```python
-container_id = c.create_container('busybox', 'ls', ports=[1111, 2222])
+container_id = c.create_container(
+    'busybox', 'ls', ports=[1111, 2222],
+    host_config=docker.utils.create_host_config(port_bindings={
+        1111: 4567,
+        2222: None
+    })
+)
 ```
 
-Bindings are then declared in the `Client.start` method.
-
-```python
-c.start(container_id, port_bindings={1111: 4567, 2222: None})
-```
 
 You can limit the host address on which the port will be exposed like such:
 
 ```python
-c.start(container_id, port_bindings={1111: ('127.0.0.1', 4567)})
+docker.utils.create_host_config(port_bindings={1111: ('127.0.0.1', 4567)})
 ```
 
 Or without host port assignment:
 
 ```python
-c.start(container_id, port_bindings={1111: ('127.0.0.1',)})
+docker.utils.create_host_config(port_bindings={1111: ('127.0.0.1',)})
 ```
 
-If you wish to use UDP instead of TCP (default), you need to declare it
-like such in both the `create_container()` and `start()` calls:
+If you wish to use UDP instead of TCP (default), you need to declare ports
+as such in both the config and host config:
 
 ```python
 container_id = c.create_container(
-	'busybox',
-	'ls',
-	ports=[(1111, 'udp'), 2222]
+	'busybox', 'ls', ports=[(1111, 'udp'), 2222],
+    host_config=docker.utils.create_host_config(port_bindings={
+        '1111/udp': 4567, 2222: None
+    })
 )
-c.start(container_id, port_bindings={'1111/udp': 4567, 2222: None})
 ```
-

docs/volumes.md

@@ -1,25 +1,21 @@
 # Using volumes
 
-Volume declaration is done in two parts. First, you have to provide
-a list of mountpoints to the `Client().create_container()` method.
+Volume declaration is done in two parts.  Provide a list of mountpoints to
+the `Client().create_container()` method, and declare mappings in the
+`host_config` section.
 
 ```python
-container_id = c.create_container('busybox', 'ls', volumes=['/mnt/vol1', '/mnt/vol2'])
-```
-
-Volume mappings are then declared inside the `Client.start` method like this:
-
-```python
-c.start(container_id, binds={
-    '/home/user1/':
-        {
+container_id = c.create_container(
+    'busybox', 'ls', volumes=['/mnt/vol1', '/mnt/vol2'],
+    host_config=docker.utils.create_host_config(binds={
+        '/home/user1/': {
             'bind': '/mnt/vol2',
             'ro': False
         },
-    '/var/www':
-        {
+        '/var/www': {
             'bind': '/mnt/vol1',
             'ro': True
         }
-})
+    })
+)
 ```