Enable passing a docker container ID directly.

This makes it possible to target an existing docker container from the
command line without using the `docker_container_id` host data variable.

Additionally this changes the disconnect behaviour to only commit and
stop the container when starting with an image. When executing against
a container we leave it as-is.

Author: Fizzadar

docs/connectors.md

@@ -41,22 +41,27 @@ pyinfra @local ...
 
 ## `@docker`
 
+The `@docker` connector allows you to build Docker images, or modify running Docker containers, using ``pyinfra``. You can pass either an image name or existing container ID:
 
-The `@docker` connector allows you to build Docker containers using pyinfra.
++ Image - will create a container from the image, execute operations and save into a new image
++ Existing container ID - will simply execute operations against the container, leaving it up afterwards
 
 ```sh
 # A Docker base image must be provided
 pyinfra @docker/alpine:3.8 ...
 
 # pyinfra can run on multiple Docker images in parallel
 pyinfra @docker/alpine:3.8,@docker/ubuntu:bionic ...
+
+# Execute against a running container
+pyinfra @docker/2beb8c15a1b1 ...
 ```
 
 **Available Data**:
 
 ```py
 # Provide a specific container ID - prevents pyinfra starting a new container and will instead use
-# whatever is provided in the name.
+# whatever is provided in the name. This is the same as passing container ID via the CLI above.
 docker_container_id = 'abc'
 ```
 

pyinfra/api/connectors/docker.py

@@ -1,3 +1,4 @@
+import json
 import os
 
 from tempfile import mkstemp
@@ -23,25 +24,51 @@ def make_names_data(image=None):
     yield '@docker/{0}'.format(image), {'docker_image': image}, ['@docker']
 
 
-def connect(state, host):
-    if 'docker_container_id' in host.host_data:  # user can provide a docker_container_id
-        return True
+def _find_start_docker_container(container_id):
+    docker_info = local.shell('docker container inspect {0}'.format(container_id))
+    docker_info = json.loads(docker_info)[0]
+    if docker_info['State']['Running'] is False:
+        logger.info('Starting stopped container: {0}'.format(container_id))
+        local.shell('docker container start {0}'.format(container_id))
+
 
+def _start_docker_image(image_name):
     try:
-        with progress_spinner({'docker run'}):
-            container_id = local.shell(
-                'docker run -d {0} tail -f /dev/null'.format(host.data.docker_image),
-                splitlines=True,
-            )[-1]  # last line is the container ID
+        return local.shell(
+            'docker run -d {0} tail -f /dev/null'.format(image_name),
+            splitlines=True,
+        )[-1]  # last line is the container ID
     except PyinfraError as e:
         raise ConnectError(e.args[0])
 
+
+def connect(state, host):
+    if 'docker_container_id' in host.host_data:  # user can provide a docker_container_id
+        host.host_data['docker_container_no_disconnect'] = True
+        return True
+
+    with progress_spinner({'prepare docker container'}):
+        try:
+            # Check if the provided @docker/X is an existing container ID
+            _find_start_docker_container(host.data.docker_image)
+        except PyinfraError:
+            container_id = _start_docker_image(host.data.docker_image)
+        else:
+            container_id = host.data.docker_image
+            host.host_data['docker_container_no_disconnect'] = True
+
     host.host_data['docker_container_id'] = container_id
     return True
 
 
 def disconnect(state, host):
-    container_id = host.host_data['docker_container_id'][:12]
+    container_id = host.host_data['docker_container_id']
+
+    if host.host_data.get('docker_container_no_disconnect'):
+        logger.info('{0}docker build complete, container left running: {1}'.format(
+            host.print_prefix, click.style(container_id, bold=True),
+        ))
+        return
 
     with progress_spinner({'docker commit'}):
         image_id = local.shell(