Add docker.from_env() shortcut

A much neater way of getting started with docker-py.

Signed-off-by: Ben Firshman <ben@firshman.co.uk>

5 files changed, 55 insertions, 40 deletions

diff --git a/docker/__init__.py b/docker/__init__.py
index 3844c81..84d0734 100644
--- a/docker/__init__.py
+++ b/docker/__init__.py
@@ -17,4 +17,4 @@ from .version import version, version_info
 __version__ = version
 __title__ = 'docker-py'
 
-from .client import Client, AutoVersionClient # flake8: noqa
+from .client import Client, AutoVersionClient, from_env # flake8: noqa
diff --git a/docker/client.py b/docker/client.py
index 7d1f7c4..5f60a32 100644
--- a/docker/client.py
+++ b/docker/client.py
@@ -28,10 +28,14 @@ from . import errors
 from .auth import auth
 from .unixconn import unixconn
 from .ssladapter import ssladapter
-from .utils import utils, check_resource, update_headers
+from .utils import utils, check_resource, update_headers, kwargs_from_env
 from .tls import TLSConfig
 
 
+def from_env(**kwargs):
+    return Client.from_env(**kwargs)
+
+
 class Client(
         requests.Session,
         api.BuildApiMixin,
@@ -84,6 +88,10 @@ class Client(
                 )
             )
 
+    @classmethod
+    def from_env(cls, **kwargs):
+        return cls(**kwargs_from_env(**kwargs))
+
     def _retrieve_server_version(self):
         try:
             return self.version(api_version=False)["ApiVersion"]
diff --git a/docs/boot2docker.md b/docs/boot2docker.md
deleted file mode 100644
index 4854e41..0000000
--- a/docs/boot2docker.md
+++ /dev/null
@@ -1,38 +0,0 @@
-# Using with Boot2docker
-
-For usage with boot2docker, there is a helper function in the utils package named `kwargs_from_env`, it will pass any environment variables from Boot2docker to the Client.
-
-First run boot2docker in your shell:
-```bash
-$ eval "$(boot2docker shellinit)"
-Writing /Users/you/.boot2docker/certs/boot2docker-vm/ca.pem
-Writing /Users/you/.boot2docker/certs/boot2docker-vm/cert.pem
-Writing /Users/you/.boot2docker/certs/boot2docker-vm/key.pem
-```
-
-You can then instantiate `docker.Client` like this:
-```python
-from docker.client import Client
-from docker.utils import kwargs_from_env
-
-cli = Client(**kwargs_from_env())
-print cli.version()
-```
-
-If you're encountering the following error:
-`SSLError: hostname '192.168.59.103' doesn't match 'boot2docker'`, you can:
-
-1. Add an entry to your /etc/hosts file matching boot2docker to the daemon's IP
-1. disable hostname validation (but please consider the security implications
-   in doing this)
-
-```python
-from docker.client import Client
-from docker.utils import kwargs_from_env
-
-kwargs = kwargs_from_env()
-kwargs['tls'].assert_hostname = False
-
-cli = Client(**kwargs)
-print cli.version()
-```
\ No newline at end of file
diff --git a/docs/machine.md b/docs/machine.md
new file mode 100644
index 0000000..d38316e
--- /dev/null
+++ b/docs/machine.md
@@ -0,0 +1,19 @@
+# Using with Docker Toolbox and Machine
+
+In development, we recommend using [Docker Toolbox](https://www.docker.com/products/docker-toolbox) to set up Docker. It includes a tool called Machine which will create a VM running Docker Engine and point your shell at it using environment variables.
+
+To configure docker-py with these environment variables
+
+First use Machine to set up the environment variables:
+```bash
+$ eval "$(docker-machine env)"
+```
+
+You can then use docker-py like this:
+```python
+import docker
+client = docker.from_env(assert_hostname=False)
+print client.version()
+```
+
+**Note:** We are disabling TLS hostname checking with `assert\_hostname=False`. Machine provides us with the exact certificate the server is using so this is safe. If you are not using Machine and verifying the host against a certificate authority, you'll want to enable this.
diff --git a/tests/unit/client_test.py b/tests/unit/client_test.py
new file mode 100644
index 0000000..1a173b5
--- /dev/null
+++ b/tests/unit/client_test.py
@@ -0,0 +1,26 @@
+import os
+from docker.client import Client
+from .. import base
+
+TEST_CERT_DIR = os.path.join(
+    os.path.dirname(__file__),
+    'testdata/certs',
+)
+
+
+class ClientTest(base.BaseTestCase):
+    def setUp(self):
+        self.os_environ = os.environ.copy()
+
+    def tearDown(self):
+        os.environ = self.os_environ
+
+    def test_from_env(self):
+        """Test that environment variables are passed through to
+        utils.kwargs_from_env(). KwargsFromEnvTest tests that environment
+        variables are parsed correctly."""
+        os.environ.update(DOCKER_HOST='tcp://192.168.59.103:2376',
+                          DOCKER_CERT_PATH=TEST_CERT_DIR,
+                          DOCKER_TLS_VERIFY='1')
+        client = Client.from_env()
+        self.assertEqual(client.base_url, "https://192.168.59.103:2376")