Merge pull request #1343 from docker/2.0.0-release

2.0.0 release

Author: shin-

.gitignore

@@ -10,7 +10,7 @@ dist
 html/*
 
 # Compiled Documentation
-site/
+_build/
 README.rst
 
 env/

.travis.yml

@@ -3,7 +3,6 @@ language: python
 python:
   - "3.5"
 env:
-    - TOX_ENV=py26
     - TOX_ENV=py27
     - TOX_ENV=py33
     - TOX_ENV=py34

CONTRIBUTING.md

@@ -1,34 +1,38 @@
 # Contributing guidelines
 
+See the [Docker contributing guidelines](https://github.com/docker/docker/blob/master/CONTRIBUTING.md).
+The following is specific to Docker SDK for Python.
+
 Thank you for your interest in the project. We look forward to your
 contribution. In order to make the process as fast and streamlined as possible,
 here is a set of guidelines we recommend you follow.
 
 ## Reporting issues
 
 We do our best to ensure bugs don't creep up in our releases, but some may
-still slip through. If you encounter one while using docker-py, please create
-an issue [in the tracker](https://github.com/docker/docker-py/issues/new) with
+still slip through. If you encounter one while using the SDK, please
+create an issue
+[in the tracker](https://github.com/docker/docker-py/issues/new) with
 the following information:
 
-- docker-py version, docker version and python version
+- SDK version, Docker version and python version
 ```
-pip freeze | grep docker-py && python --version && docker version
+pip freeze | grep docker && python --version && docker version
 ```
 - OS, distribution and OS version
 - The issue you're encountering including a stacktrace if applicable
 - If possible, steps or a code snippet to reproduce the issue
 
 To save yourself time, please be sure to check our
 [documentation](https://docker-py.readthedocs.io/) and use the
-[search function](https://github.com/docker/docker-py/search) to find out if
-it has already been addressed, or is currently being looked at.
+[search function](https://github.com/docker/docker-py/search) to find
+out if it has already been addressed, or is currently being looked at.
 
 ## Submitting pull requests
 
 Do you have a fix for an existing issue, or want to add a new functionality
-to docker-py? We happily welcome pull requests. Here are a few tips to make
-the review process easier on both the maintainers and yourself.
+to the SDK? We happily welcome pull requests. Here are a few tips to
+make the review process easier on both the maintainers and yourself.
 
 ### 1. Sign your commits
 
@@ -84,11 +88,10 @@ to reach out and ask questions. We will do our best to answer and help out.
 
 ## Development environment
 
-If you're looking contribute to docker-py but are new to the project or Python,
-here are the steps to get you started.
+If you're looking contribute to Docker SDK for Python but are new to the
+project or Python, here are the steps to get you started.
 
-1. Fork [https://github.com/docker/docker-py](https://github.com/docker/docker-py)
-   to your username.
+1. Fork https://github.com/docker/docker-py to your username.
 2. Clone your forked repository locally with
   `git clone [email protected]:yourusername/docker-py.git`.
 3. Configure a
@@ -100,3 +103,33 @@ here are the steps to get you started.
 5. Run `python setup.py develop` to install the dev version of the project
   and required dependencies. We recommend you do so inside a
   [virtual environment](http://docs.python-guide.org/en/latest/dev/virtualenvs)
+
+## Running the tests & Code Quality
+
+To get the source source code and run the unit tests, run:
+```
+$ git clone git://github.com/docker/docker-py.git
+$ cd docker-py
+$ make test
+```
+
+## Building the docs
+
+```
+$ make docs
+$ open _build/index.html
+```
+
+## Release Checklist
+
+Before a new release, please go through the following checklist:
+
+* Bump version in docker/version.py
+* Add a release note in docs/change_log.md
+* Git tag the version
+* Upload to pypi
+
+## Vulnerability Reporting
+For any security issues, please do NOT file an issue or pull request on github!
+Please contact [[email protected]](mailto:[email protected]) or read [the
+Docker security page](https://www.docker.com/resources/security/).

Dockerfile

@@ -1,14 +1,13 @@
 FROM python:2.7
-MAINTAINER Joffrey F <[email protected]>
 
-RUN mkdir /home/docker-py
-WORKDIR /home/docker-py
+RUN mkdir /src
+WORKDIR /src
 
-COPY requirements.txt /home/docker-py/requirements.txt
+COPY requirements.txt /src/requirements.txt
 RUN pip install -r requirements.txt
 
-COPY test-requirements.txt /home/docker-py/test-requirements.txt
+COPY test-requirements.txt /src/test-requirements.txt
 RUN pip install -r test-requirements.txt
 
-COPY . /home/docker-py
+COPY . /src
 RUN pip install .

Dockerfile-docs

@@ -1,9 +1,12 @@
-FROM python:2.7
+FROM python:3.5
 
-RUN mkdir /home/docker-py
-WORKDIR /home/docker-py
+RUN mkdir /src
+WORKDIR /src
 
-COPY docs-requirements.txt /home/docker-py/docs-requirements.txt
+COPY requirements.txt /src/requirements.txt
+RUN pip install -r requirements.txt
+
+COPY docs-requirements.txt /src/docs-requirements.txt
 RUN pip install -r docs-requirements.txt
 
-COPY . /home/docker-py
+COPY . /src

Dockerfile-py3

@@ -1,14 +1,13 @@
 FROM python:3.5
-MAINTAINER Joffrey F <[email protected]>
 
-RUN mkdir /home/docker-py
-WORKDIR /home/docker-py
+RUN mkdir /src
+WORKDIR /src
 
-COPY requirements.txt /home/docker-py/requirements.txt
+COPY requirements.txt /src/requirements.txt
 RUN pip install -r requirements.txt
 
-COPY test-requirements.txt /home/docker-py/test-requirements.txt
+COPY test-requirements.txt /src/test-requirements.txt
 RUN pip install -r test-requirements.txt
 
-COPY . /home/docker-py
+COPY . /src
 RUN pip install .

MAINTAINERS

@@ -1,4 +1,4 @@
-# Docker-py maintainers file
+# Docker SDK for Python maintainers file
 #
 # This file describes who runs the docker/docker-py project and how.
 # This is a living document - if you see something out of date or missing, speak up!
@@ -12,6 +12,7 @@
 	[Org."Core maintainers"]
 		people = [
 			"aanand",
+			"bfirsh",
 			"dnephin",
 			"mnowster",
 			"mpetazzoni",
@@ -31,6 +32,11 @@
 	Email = "[email protected]"
 	GitHub = "aanand"
 
+	[people.bfirsh]
+	Name = "Ben Firshman"
+	Email = "[email protected]"
+	GitHub = "bfirsh"
+
 	[people.dnephin]
 	Name = "Daniel Nephin"
 	Email = "[email protected]"

Makefile

@@ -8,15 +8,15 @@ clean:
 
 .PHONY: build
 build:
-	docker build -t docker-py .
+	docker build -t docker-sdk-python .
 
 .PHONY: build-py3
 build-py3:
-	docker build -t docker-py3 -f Dockerfile-py3 .
+	docker build -t docker-sdk-python3 -f Dockerfile-py3 .
 
 .PHONY: build-docs
 build-docs:
-	docker build -t docker-py-docs -f Dockerfile-docs .
+	docker build -t docker-sdk-python-docs -f Dockerfile-docs .
 
 .PHONY: build-dind-certs
 build-dind-certs:
@@ -27,28 +27,28 @@ test: flake8 unit-test unit-test-py3 integration-dind integration-dind-ssl
 
 .PHONY: unit-test
 unit-test: build
-	docker run docker-py py.test tests/unit
+	docker run --rm docker-sdk-python py.test tests/unit
 
 .PHONY: unit-test-py3
 unit-test-py3: build-py3
-	docker run docker-py3 py.test tests/unit
+	docker run --rm docker-sdk-python3 py.test tests/unit
 
 .PHONY: integration-test
 integration-test: build
-	docker run -v /var/run/docker.sock:/var/run/docker.sock docker-py py.test tests/integration
+	docker run --rm -v /var/run/docker.sock:/var/run/docker.sock docker-sdk-python py.test tests/integration/${file}
 
 .PHONY: integration-test-py3
 integration-test-py3: build-py3
-	docker run -v /var/run/docker.sock:/var/run/docker.sock docker-py3 py.test tests/integration
+	docker run --rm -v /var/run/docker.sock:/var/run/docker.sock docker-sdk-python3 py.test tests/integration/${file}
 
 .PHONY: integration-dind
 integration-dind: build build-py3
 	docker rm -vf dpy-dind || :
-	docker run -d --name dpy-dind --privileged dockerswarm/dind:1.12.0 docker daemon\
+	docker run -d --name dpy-dind --privileged dockerswarm/dind:1.13.0-rc3 docker daemon\
 		-H tcp://0.0.0.0:2375
-	docker run --env="DOCKER_HOST=tcp://docker:2375" --link=dpy-dind:docker docker-py\
+	docker run --rm --env="DOCKER_HOST=tcp://docker:2375" --link=dpy-dind:docker docker-sdk-python\
 		py.test tests/integration
-	docker run --env="DOCKER_HOST=tcp://docker:2375" --link=dpy-dind:docker docker-py3\
+	docker run --rm --env="DOCKER_HOST=tcp://docker:2375" --link=dpy-dind:docker docker-sdk-python3\
 		py.test tests/integration
 	docker rm -vf dpy-dind
 
@@ -57,21 +57,25 @@ integration-dind-ssl: build-dind-certs build build-py3
 	docker run -d --name dpy-dind-certs dpy-dind-certs
 	docker run -d --env="DOCKER_HOST=tcp://localhost:2375" --env="DOCKER_TLS_VERIFY=1"\
 		--env="DOCKER_CERT_PATH=/certs" --volumes-from dpy-dind-certs --name dpy-dind-ssl\
-		-v /tmp --privileged dockerswarm/dind:1.12.0 docker daemon --tlsverify\
+		-v /tmp --privileged dockerswarm/dind:1.13.0-rc3 docker daemon --tlsverify\
 		--tlscacert=/certs/ca.pem --tlscert=/certs/server-cert.pem\
 		--tlskey=/certs/server-key.pem -H tcp://0.0.0.0:2375
-	docker run --volumes-from dpy-dind-ssl --env="DOCKER_HOST=tcp://docker:2375"\
+	docker run --rm --volumes-from dpy-dind-ssl --env="DOCKER_HOST=tcp://docker:2375"\
 		--env="DOCKER_TLS_VERIFY=1" --env="DOCKER_CERT_PATH=/certs"\
-		--link=dpy-dind-ssl:docker docker-py py.test tests/integration
-	docker run --volumes-from dpy-dind-ssl --env="DOCKER_HOST=tcp://docker:2375"\
+		--link=dpy-dind-ssl:docker docker-sdk-python py.test tests/integration
+	docker run --rm --volumes-from dpy-dind-ssl --env="DOCKER_HOST=tcp://docker:2375"\
 		--env="DOCKER_TLS_VERIFY=1" --env="DOCKER_CERT_PATH=/certs"\
-		--link=dpy-dind-ssl:docker docker-py3 py.test tests/integration
+		--link=dpy-dind-ssl:docker docker-sdk-python3 py.test tests/integration
 	docker rm -vf dpy-dind-ssl dpy-dind-certs
 
 .PHONY: flake8
 flake8: build
-	docker run docker-py flake8 docker tests
+	docker run --rm docker-sdk-python flake8 docker tests
 
 .PHONY: docs
 docs: build-docs
-	docker run -v `pwd`/docs:/home/docker-py/docs/ -p 8000:8000 docker-py-docs mkdocs serve -a 0.0.0.0:8000
+	docker run --rm -it -v `pwd`:/code docker-sdk-python-docs sphinx-build docs ./_build
+
+.PHONY: shell
+shell: build
+	docker run -it -v /var/run/docker.sock:/var/run/docker.sock docker-sdk-python python

README.md

@@ -1,26 +1,77 @@
-docker-py
-=========
+# Docker SDK for Python
 
-[![Build Status](https://travis-ci.org/docker/docker-py.png)](https://travis-ci.org/docker/docker-py)
+[![Build Status](https://travis-ci.org/docker/docker-py.svg?branch=master)](https://travis-ci.org/docker/docker-py)
 
-A Python library for the Docker Remote API. It does everything the `docker` command does, but from within Python – run containers, manage them, pull/push images, etc.
+**Warning:** This README is for the development version of the Docker SDK for
+Python, which is significantly different to the stable version.
+[Documentation for the stable version is here.](https://docker-py.readthedocs.io/)
 
-Installation
-------------
+A Python library for the Docker Engine API. It lets you do anything the `docker` command does, but from within Python apps – run containers, manage containers, manage Swarms, etc.
 
-The latest stable version is always available on PyPi.
+## Installation
 
-    pip install docker-py
+The latest stable version [is available on PyPi](https://pypi.python.org/pypi/docker/). Either add `docker` to your `requirements.txt` file or install with pip:
 
-Documentation
--------------
+    pip install docker
 
-[![Documentation Status](https://readthedocs.org/projects/docker-py/badge/?version=latest)](https://readthedocs.org/projects/docker-py/?badge=latest)
+## Usage
 
-[Read the full documentation here](https://docker-py.readthedocs.io/en/latest/).
-The source is available in the `docs/` directory.
+Connect to Docker using the default socket or the configuration in your environment:
 
+```python
+import docker
+client = docker.from_env()
+```
 
-License
--------
-Docker is licensed under the Apache License, Version 2.0. See LICENSE for full license text
+You can run containers:
+
+```python
+>>> client.containers.run("ubuntu", "echo hello world")
+'hello world\n'
+```
+
+You can run containers in the background:
+
+```python
+>>> client.containers.run("bfirsh/reticulate-splines", detach=True)
+<Container '45e6d2de7c54'>
+```
+
+You can manage containers:
+
+```python
+>>> client.containers.list()
+[<Container '45e6d2de7c54'>, <Container 'db18e4f20eaa'>, ...]
+
+>>> container = client.containers.get('45e6d2de7c54')
+
+>>> container.attrs['Config']['Image']
+"bfirsh/reticulate-splines"
+
+>>> container.logs()
+"Reticulating spline 1...\n"
+
+>>> container.stop()
+```
+
+You can stream logs:
+
+```python
+>>> for line in container.logs(stream=True):
+...   print line.strip()
+Reticulating spline 2...
+Reticulating spline 3...
+...
+```
+
+You can manage images:
+
+```python
+>>> client.images.pull('nginx')
+<Image 'nginx'>
+
+>>> client.images.list()
+[<Image 'ubuntu'>, <Image 'nginx'>, ...]
+```
+
+[Read the full documentation](https://docker-py.readthedocs.io) to see everything you can do.

docker/__init__.py

@@ -1,6 +1,7 @@
+# flake8: noqa
+from .api import APIClient
+from .client import DockerClient, from_env
 from .version import version, version_info
 
 __version__ = version
-__title__ = 'docker-py'
-
-from .client import Client, AutoVersionClient, from_env # flake8: noqa
+__title__ = 'docker'