Docker modules: improve documentation on docker vs. docker-py Python package requirements (#42457)

* Make sure all docker-py/docker requirements are listed, and clarify about docker vs. docker-py.

* Adjusting changes made in #40839.

lib/ansible/module_utils/docker_common.py

@@ -167,14 +167,15 @@ class AnsibleDockerClient(Client):
 
         if HAS_DOCKER_MODELS and HAS_DOCKER_SSLADAPTER:
             self.fail("Cannot have both the docker-py and docker python modules installed together as they use the same namespace and "
-                      "cause a corrupt installation. Please uninstall both packages, and re-install only the docker-py or docker python module")
+                      "cause a corrupt installation. Please uninstall both packages, and re-install only the docker-py or docker python "
+                      "module. It is recommended to install the docker module if no support for Python 2.6 is required.")
 
         if not HAS_DOCKER_PY:
-            self.fail("Failed to import docker-py - %s. Try `pip install docker-py`" % HAS_DOCKER_ERROR)
+            self.fail("Failed to import docker or docker-py - %s. Try `pip install docker` or `pip install docker-py` (Python 2.6)" % HAS_DOCKER_ERROR)
 
         if LooseVersion(docker_version) < LooseVersion(MIN_DOCKER_VERSION):
-            self.fail("Error: docker-py version is %s. Minimum version required is %s." % (docker_version,
+            self.fail("Error: docker / docker-py version is %s. Minimum version required is %s." % (docker_version,
-                                                                                           MIN_DOCKER_VERSION))
+                                                                                                    MIN_DOCKER_VERSION))
 
         self.debug = self.module.params.get('debug')
         self.check_mode = self.module.check_mode

lib/ansible/modules/cloud/docker/docker_container.py

@@ -96,7 +96,6 @@ options:
     description:
       - Path to a file containing environment variables I(FOO=BAR).
       - If variable also present in C(env), then C(env) value will override.
-      - Requires docker >= 2.3.0.
   entrypoint:
     description:
       - Command that overwrites the default ENTRYPOINT of the image.
@@ -421,7 +420,13 @@ author:
 
 requirements:
     - "python >= 2.6"
-    - "docker >= 2.3.0"
+    - "docker-py >= 1.7.0"
+    - "Please note that the L(docker-py,https://pypi.org/project/docker-py/) Python
+       module has been superseded by L(docker,https://pypi.org/project/docker/)
+       (see L(here,https://github.com/docker/docker-py/issues/1310) for details).
+       For Python 2.6, C(docker-py) must be used. Otherwise, it is recommended to
+       install the C(docker) Python module. Note that both modules should I(not)
+       be installed at the same time."
     - "Docker API >= 1.20"
 '''
 
@@ -619,7 +624,7 @@ try:
         from docker.utils.types import Ulimit, LogConfig
     from ansible.module_utils.docker_common import docker_version
 except:
-    # missing docker handled in ansible.module_utils.docker
+    # missing docker-py handled in ansible.module_utils.docker
     pass
 
 
@@ -2016,7 +2021,8 @@ class AnsibleDockerClientContainer(AnsibleDockerClient):
 
         init_supported = init_supported and LooseVersion(docker_version) >= LooseVersion('2.2')
         if self.module.params.get("init") and not init_supported:
-            self.fail('docker-py version is %s. Minimum version required is 2.2 to set init option.' % (docker_version,))
+            self.fail("docker or docker-py version is %s. Minimum version required is 2.2 to set init option. "
+                      "If you use the 'docker-py' module, you have to switch to the docker 'Python' package." % (docker_version,))
 
         self.HAS_INIT_OPT = init_supported
         self.HAS_AUTO_REMOVE_OPT = HAS_DOCKER_PY_2 or HAS_DOCKER_PY_3

lib/ansible/modules/cloud/docker/docker_image.py

@@ -168,6 +168,12 @@ extends_documentation_fragment:
 requirements:
   - "python >= 2.6"
   - "docker-py >= 1.7.0"
+  - "Please note that the L(docker-py,https://pypi.org/project/docker-py/) Python
+     module has been superseded by L(docker,https://pypi.org/project/docker/)
+     (see L(here,https://github.com/docker/docker-py/issues/1310) for details).
+     For Python 2.6, C(docker-py) must be used. Otherwise, it is recommended to
+     install the C(docker) Python module. Note that both modules should I(not)
+     be installed at the same time."
   - "Docker API >= 1.20"
 
 author:

lib/ansible/modules/cloud/docker/docker_image_facts.py

@@ -36,6 +36,12 @@ extends_documentation_fragment:
 requirements:
   - "python >= 2.6"
   - "docker-py >= 1.7.0"
+  - "Please note that the L(docker-py,https://pypi.org/project/docker-py/) Python
+     module has been superseded by L(docker,https://pypi.org/project/docker/)
+     (see L(here,https://github.com/docker/docker-py/issues/1310) for details).
+     For Python 2.6, C(docker-py) must be used. Otherwise, it is recommended to
+     install the C(docker) Python module. Note that both modules should I(not)
+     be installed at the same time."
   - "Docker API >= 1.20"
 
 author:
@@ -152,7 +158,7 @@ images:
 try:
     from docker import utils
 except ImportError:
-    # missing docker-py handled in docker_common
+    # missing docker-py handled in ansible.module_utils.docker_common
     pass
 
 from ansible.module_utils.docker_common import AnsibleDockerClient, DockerBaseClass

lib/ansible/modules/cloud/docker/docker_login.py

@@ -77,6 +77,12 @@ extends_documentation_fragment:
 requirements:
     - "python >= 2.6"
     - "docker-py >= 1.7.0"
+    - "Please note that the L(docker-py,https://pypi.org/project/docker-py/) Python
+       module has been superseded by L(docker,https://pypi.org/project/docker/)
+       (see L(here,https://github.com/docker/docker-py/issues/1310) for details).
+       For Python 2.6, C(docker-py) must be used. Otherwise, it is recommended to
+       install the C(docker) Python module. Note that both modules should I(not)
+       be installed at the same time."
     - "Docker API >= 1.20"
     - 'Only to be able to logout (state=absent): the docker command line utility'
 author:

lib/ansible/modules/cloud/docker/docker_network.py

@@ -96,6 +96,12 @@ author:
 requirements:
     - "python >= 2.6"
     - "docker-py >= 1.7.0"
+    - "Please note that the L(docker-py,https://pypi.org/project/docker-py/) Python
+       module has been superseded by L(docker,https://pypi.org/project/docker/)
+       (see L(here,https://github.com/docker/docker-py/issues/1310) for details).
+       For Python 2.6, C(docker-py) must be used. Otherwise, it is recommended to
+       install the C(docker) Python module. Note that both modules should I(not)
+       be installed at the same time."
     - "The docker server >= 1.9.0"
 '''
 
@@ -156,7 +162,7 @@ try:
     if HAS_DOCKER_PY_2 or HAS_DOCKER_PY_3:
         from docker.types import IPAMPool, IPAMConfig
 except:
-    # missing docker-py handled in ansible.module_utils.docker
+    # missing docker-py handled in ansible.module_utils.docker_common
     pass
 
 

lib/ansible/modules/cloud/docker/docker_secret.py

@@ -60,6 +60,10 @@ extends_documentation_fragment:
 
 requirements:
   - "docker-py >= 2.1.0"
+  - "Please note that the L(docker-py,https://pypi.org/project/docker-py/) Python
+     module has been superseded by L(docker,https://pypi.org/project/docker/)
+     (see L(here,https://github.com/docker/docker-py/issues/1310) for details).
+     Version 2.1.0 or newer is only available with the C(docker) module."
   - "Docker API >= 1.25"
 
 author:
@@ -140,7 +144,7 @@ import hashlib
 try:
     from docker.errors import APIError
 except ImportError:
-    # missing docker-py handled in ansible.module_utils.docker
+    # missing docker-py handled in ansible.module_utils.docker_common
     pass
 
 from ansible.module_utils.docker_common import AnsibleDockerClient, DockerBaseClass

lib/ansible/modules/cloud/docker/docker_service.py

@@ -143,6 +143,13 @@ extends_documentation_fragment:
 
 requirements:
     - "python >= 2.6"
+    - "docker-py >= 1.8.0"
+    - "Please note that the L(docker-py,https://pypi.org/project/docker-py/) Python
+       module has been superseded by L(docker,https://pypi.org/project/docker/)
+       (see L(here,https://github.com/docker/docker-py/issues/1310) for details).
+       For Python 2.6, C(docker-py) must be used. Otherwise, it is recommended to
+       install the C(docker) Python module. Note that both modules should I(not)
+       be installed at the same time."
     - "docker-compose >= 1.7.0"
     - "Docker API >= 1.20"
     - "PyYAML >= 3.11"

lib/ansible/modules/cloud/docker/docker_swarm.py

@@ -136,6 +136,11 @@ extends_documentation_fragment:
     - docker
 requirements:
     - python >= 2.7
+    - "docker-py >= 2.6.0"
+    - "Please note that the L(docker-py,https://pypi.org/project/docker-py/) Python
+       module has been superseded by L(docker,https://pypi.org/project/docker/)
+       (see L(here,https://github.com/docker/docker-py/issues/1310) for details).
+       Version 2.1.0 or newer is only available with the C(docker) module."
     - Docker API >= 1.35
 author:
   - Thierry Bouvet (@tbouvet)
@@ -214,7 +219,7 @@ from time import sleep
 try:
     from docker.errors import APIError
 except ImportError:
-    # missing docker-py handled in ansible.module_utils.docker
+    # missing docker-py handled in ansible.module_utils.docker_common
     pass
 
 from ansible.module_utils.docker_common import AnsibleDockerClient, DockerBaseClass

lib/ansible/modules/cloud/docker/docker_volume.py

@@ -68,6 +68,12 @@ author:
 requirements:
     - "python >= 2.6"
     - "docker-py >= 1.10.0"
+    - "Please note that the L(docker-py,https://pypi.org/project/docker-py/) Python
+       module has been superseded by L(docker,https://pypi.org/project/docker/)
+       (see L(here,https://github.com/docker/docker-py/issues/1310) for details).
+       For Python 2.6, C(docker-py) must be used. Otherwise, it is recommended to
+       install the C(docker) Python module. Note that both modules should I(not)
+       be installed at the same time."
     - "The docker server >= 1.9.0"
 '''
 
@@ -100,7 +106,7 @@ facts:
 try:
     from docker.errors import APIError
 except ImportError:
-    # missing docker-py handled in ansible.module_utils.docker
+    # missing docker-py handled in ansible.module_utils.docker_common
     pass
 
 from ansible.module_utils.docker_common import DockerBaseClass, AnsibleDockerClient