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.
2024-09-14 20:13:21 +02:00 · 2018-07-11 23:57:39 +02:00 · 2018-07-11 23:57:39 +02:00 · 765a5130d5
commit 765a5130d5
parent 27f540ac5c
10 changed files with 66 additions and 13 deletions
--- a/lib/ansible/module_utils/docker_common.py
+++ b/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,
-                                                                                           MIN_DOCKER_VERSION))
+            self.fail("Error: docker / docker-py version is %s. Minimum version required is %s." % (docker_version,
+                                                                                                    MIN_DOCKER_VERSION))

        self.debug = self.module.params.get('debug')
        self.check_mode = self.module.check_mode
--- a/lib/ansible/modules/cloud/docker/docker_container.py
+++ b/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
--- a/lib/ansible/modules/cloud/docker/docker_image.py
+++ b/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:
--- a/lib/ansible/modules/cloud/docker/docker_image_facts.py
+++ b/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
--- a/lib/ansible/modules/cloud/docker/docker_login.py
+++ b/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:
--- a/lib/ansible/modules/cloud/docker/docker_network.py
+++ b/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


--- a/lib/ansible/modules/cloud/docker/docker_secret.py
+++ b/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
--- a/lib/ansible/modules/cloud/docker/docker_service.py
+++ b/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"
--- a/lib/ansible/modules/cloud/docker/docker_swarm.py
+++ b/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
--- a/lib/ansible/modules/cloud/docker/docker_volume.py
+++ b/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