Merge upstream branch 'master' into feature/logs_since

Signed-off-by: Viacheslav Boiko <v.e.boyko@gmail.com>

7 files changed, 106 insertions, 24 deletions

diff --git a/docs/api.md b/docs/api.md
index 1b8b1ac..a31aad0 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -4,8 +4,8 @@ To instantiate a `Client` class that will allow you to communicate with a
 Docker daemon, simply do:
 
 ```python
-from docker import Client
-c = Client(base_url='unix://var/run/docker.sock')
+>>> from docker import Client
+>>> cli = Client(base_url='unix://var/run/docker.sock')
 ```
 
 **Params**:
@@ -165,6 +165,8 @@ non-running ones
 
 ## copy
 Identical to the `docker cp` command. Get files/folders from the container.
+**Deprecated for API version >= 1.20** – Consider using
+[`get_archive`](#get_archive) **instead.**
 
 **Params**:
 
@@ -214,7 +216,7 @@ from. Optionally a single string joining container id's with commas
 * network_disabled (bool): Disable networking
 * name (str): A name for the container
 * entrypoint (str or list): An entrypoint
-* cpu_shares (int or float): CPU shares (relative weight)
+* cpu_shares (int): CPU shares (relative weight)
 * working_dir (str): Path to the working directory
 * domainname (str or list): Set custom DNS search domains
 * memswap_limit (int):
@@ -248,9 +250,9 @@ PASSWORD=secret
 The utility can be used as follows:
 
 ```python
->> import docker.utils
->> my_envs = docker.utils.parse_env_file('/path/to/file')
->> docker.utils.create_container_config('1.18', '_mongodb', 'foobar',  environment=my_envs)
+>>> import docker.utils
+>>> my_envs = docker.utils.parse_env_file('/path/to/file')
+>>> docker.utils.create_container_config('1.18', '_mongodb', 'foobar',  environment=my_envs)
 ```
 
 You can now use this with 'environment' for `create_container`.
@@ -377,6 +379,27 @@ Export the contents of a filesystem as a tar archive to STDOUT.
 
 **Returns** (str): The filesystem tar archive as a str
 
+## get_archive
+
+Retrieve a file or folder from a container in the form of a tar archive.
+
+**Params**:
+
+* container (str): The container where the file is located
+* path (str): Path to the file or folder to retrieve
+
+**Returns** (tuple): First element is a raw tar data stream. Second element is
+a dict containing `stat` information on the specified `path`.
+
+```python
+>>> import docker
+>>> cli = docker.Client()
+>>> ctnr = cli.create_container('busybox', 'true')
+>>> strm, stat = cli.get_archive(ctnr, '/bin/sh')
+>>> print(stat)
+{u'linkTarget': u'', u'mode': 493, u'mtime': u'2015-09-16T12:34:23-07:00', u'name': u'sh', u'size': 962860}
+```
+
 ## get_image
 
 Get an image from the docker daemon. Similar to the `docker save` command.
@@ -713,6 +736,20 @@ command.
     yourname/app/tags/latest}"}\\n']
 ```
 
+## put_archive
+
+Insert a file or folder in an existing container using a tar archive as source.
+
+**Params**:
+
+* container (str): The container where the file(s) will be extracted
+* path (str): Path inside the container where the file(s) will be extracted.
+  Must exist.
+* data (bytes): tar data to be extracted
+
+**Returns** (bool): True if the call succeeds. `docker.errors.APIError` will
+be raised if an error occurs.
+
 ## remove_container
 
 Remove a container. Similar to the `docker rm` command.
diff --git a/docs/boot2docker.md b/docs/boot2docker.md
index 43aa558..4854e41 100644
--- a/docs/boot2docker.md
+++ b/docs/boot2docker.md
@@ -15,8 +15,8 @@ You can then instantiate `docker.Client` like this:
 from docker.client import Client
 from docker.utils import kwargs_from_env
 
-client = Client(**kwargs_from_env())
-print client.version()
+cli = Client(**kwargs_from_env())
+print cli.version()
 ```
 
 If you're encountering the following error:
@@ -33,6 +33,6 @@ from docker.utils import kwargs_from_env
 kwargs = kwargs_from_env()
 kwargs['tls'].assert_hostname = False
 
-client = Client(**kwargs)
-print client.version()
+cli = Client(**kwargs)
+print cli.version()
 ```
\ No newline at end of file
diff --git a/docs/change_log.md b/docs/change_log.md
index da3a9b0..f2b272a 100644
--- a/docs/change_log.md
+++ b/docs/change_log.md
@@ -1,6 +1,43 @@
 Change Log
 ==========
 
+1.5.0
+-----
+
+[List of PRs / issues for this release](https://github.com/docker/docker-py/issues?q=milestone%3A1.5.0+is%3Aclosed)
+
+### Features
+
+* Added support for the networking API introduced in Docker 1.9.0
+  (`Client.networks`, `Client.create_network`, `Client.remove_network`,
+  `Client.inspect_network`, `Client.connect_container_to_network`,
+  `Client.disconnect_container_from_network`).
+* Added support for the volumes API introduced in Docker 1.9.0
+  (`Client.volumes`, `Client.create_volume`, `Client.inspect_volume`,
+  `Client.remove_volume`).
+* Added support for the `group_add` parameter in `create_host_config`.
+* Added support for the CPU CFS (`cpu_quota` and `cpu_period`) parameteres
+  in `create_host_config`.
+* Added support for the archive API endpoint (`Client.get_archive`,
+  `Client.put_archive`).
+* Added support for `ps_args` parameter in `Client.top`.
+
+
+### Bugfixes
+
+* Fixed a bug where specifying volume binds with unicode characters would
+  fail.
+* Fixed a bug where providing an explicit protocol in `Client.port` would fail
+  to yield the expected result.
+* Fixed a bug where the priority protocol returned by `Client.port` would be UDP
+  instead of the expected TCP.
+
+### Miscellaneous
+
+* Broke up Client code into several files to facilitate maintenance and
+  contribution.
+* Added contributing guidelines to the repository.
+
 1.4.0
 -----
 
diff --git a/docs/host-devices.md b/docs/host-devices.md
index f1ee3e1..a35d340 100644
--- a/docs/host-devices.md
+++ b/docs/host-devices.md
@@ -5,8 +5,8 @@ the devices parameter in the `host_config` param in `Client.create_container`
 as shown below:
 
 ```python
-c.create_container(
-    'busybox', 'true', host_config=docker.utils.create_host_config(devices=[
+cli.create_container(
+    'busybox', 'true', host_config=cli.create_host_config(devices=[
         '/dev/sda:/dev/xvda:rwm'
     ])
 )
diff --git a/docs/hostconfig.md b/docs/hostconfig.md
index 39b7a23..4c17eb3 100644
--- a/docs/hostconfig.md
+++ b/docs/hostconfig.md
@@ -101,12 +101,20 @@ for example:
   allowed to consume.
 * group_add (list): List of additional group names and/or IDs that the
   container process will run as.
+* devices (list): A list of devices to add to the container specified as dicts
+  in the form:
+  ```
+    { "PathOnHost": "/dev/deviceName",
+      "PathInContainer": "/dev/deviceName",
+      "CgroupPermissions": "mrw"
+    }
+  ```
 
 **Returns** (dict) HostConfig dictionary
 
 ```python
 >>> from docker import Client
->>> c = Client()
->>> c.create_host_config(privileged=True, cap_drop=['MKNOD'], volumes_from=['nostalgic_newton'])
+>>> cli = Client()
+>>> cli.create_host_config(privileged=True, cap_drop=['MKNOD'], volumes_from=['nostalgic_newton'])
 {'CapDrop': ['MKNOD'], 'LxcConf': None, 'Privileged': True, 'VolumesFrom': ['nostalgic_newton'], 'PublishAllPorts': False}
 ```
diff --git a/docs/port-bindings.md b/docs/port-bindings.md
index 7456b86..a9ff80e 100644
--- a/docs/port-bindings.md
+++ b/docs/port-bindings.md
@@ -4,9 +4,9 @@ open inside the container in the `Client().create_container()` method.
 Bindings are declared in the `host_config` parameter.
 
 ```python
-container_id = c.create_container(
+container_id = cli.create_container(
     'busybox', 'ls', ports=[1111, 2222],
-    host_config=docker.utils.create_host_config(port_bindings={
+    host_config=cli.create_host_config(port_bindings={
         1111: 4567,
         2222: None
     })
@@ -17,22 +17,22 @@ container_id = c.create_container(
 You can limit the host address on which the port will be exposed like such:
 
 ```python
-docker.utils.create_host_config(port_bindings={1111: ('127.0.0.1', 4567)})
+cli.create_host_config(port_bindings={1111: ('127.0.0.1', 4567)})
 ```
 
 Or without host port assignment:
 
 ```python
-docker.utils.create_host_config(port_bindings={1111: ('127.0.0.1',)})
+cli.create_host_config(port_bindings={1111: ('127.0.0.1',)})
 ```
 
 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(
+container_id = cli.create_container(
 	'busybox', 'ls', ports=[(1111, 'udp'), 2222],
-    host_config=docker.utils.create_host_config(port_bindings={
+    host_config=cli.create_host_config(port_bindings={
         '1111/udp': 4567, 2222: None
     })
 )
diff --git a/docs/volumes.md b/docs/volumes.md
index 16c3228..04273d8 100644
--- a/docs/volumes.md
+++ b/docs/volumes.md
@@ -5,9 +5,9 @@ the `Client().create_container()` method, and declare mappings in the
 `host_config` section.
 
 ```python
-container_id = c.create_container(
+container_id = cli.create_container(
     'busybox', 'ls', volumes=['/mnt/vol1', '/mnt/vol2'],
-    host_config=docker.utils.create_host_config(binds={
+    host_config=cli.create_host_config(binds={
         '/home/user1/': {
             'bind': '/mnt/vol2',
             'mode': 'rw',
@@ -24,9 +24,9 @@ You can alternatively specify binds as a list. This code is equivalent to the
 example above:
 
 ```python
-container_id = c.create_container(
+container_id = cli.create_container(
     'busybox', 'ls', volumes=['/mnt/vol1', '/mnt/vol2'],
-    host_config=docker.utils.create_host_config(binds=[
+    host_config=cli.create_host_config(binds=[
         '/home/user1/:/mnt/vol2',
         '/var/www:/mnt/vol1:ro',
     ])