Document put_archive and get_archive. Add deprecation warning for copy in API docsarchive_endpoint

Signed-off-by: Joffrey F <joffrey@docker.com>

1 files changed, 37 insertions, 0 deletions

diff --git a/docs/api.md b/docs/api.md
index 690fe49..e472927 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -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**:
 
@@ -376,6 +378,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
+>>> c = docker.Client()
+>>> ctnr = c.create_container('busybox', 'true')
+>>> strm, stat = c.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.
@@ -712,6 +735,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.