docker modules: various adjustments (#51700)

* Move docker_ module_utils into subpackage.

* Remove docker_ prefix from module_utils.docker modules.

* Adding jurisdiction for module_utils/docker to $team_docker.

* Making docker* unit tests community supported.

* Linting.

* Python < 2.6 is not supported.

* Refactoring docker-py version comments. Moving them to doc fragments. Cleaning up some indentations.

.github/BOTMETA.yml

@@ -582,8 +582,7 @@ files:
     labels: windows
     maintainers: $team_windows_core
     support: core
-  $module_utils/docker_common.py: *docker
+  $module_utils/docker/: *docker
-  $module_utils/docker_swarm.py: *docker
   $module_utils/ec2.py:
     support: core
     labels:
@@ -1289,6 +1288,7 @@ files:
   test/integration/targets/postgresql: *postgresql
   test/integration/targets/setup_acme:
     maintainers: resmo felixfontein
+  test/integration/targets/setup_docker: *docker
   test/integration/targets/setup_mysql_db: *mysql
   test/integration/targets/setup_zabbix:
     maintainers: eikef D3DeFi
@@ -1304,8 +1304,13 @@ files:
   test/legacy/scaleway:
     <<: *scaleway
     support: community
+  test/units/module_utils/docker/:
+    <<: *docker
+    support: community
   test/units/module_utils/facts/network/test_generic_bsd.py: *bsd
-  test/units/modules/cloud/docker: *docker
+  test/units/modules/cloud/docker:
+    <<: *docker
+    support: community
   test/units/modules/network:
     maintainers: $team_networking
     labels: networking

lib/ansible/module_utils/docker/swarm.py

@@ -7,11 +7,11 @@ import json
 try:
     from docker.errors import APIError
 except ImportError:
-    # missing docker-py handled in ansible.module_utils.docker_common
+    # missing docker-py handled in ansible.module_utils.docker.common
     pass
 
 from ansible.module_utils._text import to_native
-from ansible.module_utils.docker_common import AnsibleDockerClient
+from ansible.module_utils.docker.common import AnsibleDockerClient
 
 
 class AnsibleDockerSwarmClient(AnsibleDockerClient):

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

@@ -140,22 +140,14 @@ options:
     default: 10
 
 extends_documentation_fragment:
-    - docker
+  - docker
+  - docker.docker_py_1_documentation
 
 requirements:
-    - "python >= 2.6"
+  - "docker-py >= 1.8.0"
-    - "docker-py >= 1.8.0"
+  - "docker-compose >= 1.7.0"
-    - "Please note that the L(docker-py,https://pypi.org/project/docker-py/) Python
+  - "Docker API >= 1.20"
-       module has been superseded by L(docker,https://pypi.org/project/docker/)
+  - "PyYAML >= 3.11"
-       (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. Also note that when both modules are installed
-       and one of them is uninstalled, the other might no longer function and a
-       reinstall of it is required."
-    - "docker-compose >= 1.7.0"
-    - "Docker API >= 1.20"
-    - "PyYAML >= 3.11"
 '''
 
 EXAMPLES = '''
@@ -468,7 +460,7 @@ except ImportError as exc:
     HAS_COMPOSE_EXC = str(exc)
     DEFAULT_TIMEOUT = 10
 
-from ansible.module_utils.docker_common import AnsibleDockerClient, DockerBaseClass
+from ansible.module_utils.docker.common import AnsibleDockerClient, DockerBaseClass
 
 
 AUTH_PARAM_MAPPING = {

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

@@ -67,15 +67,11 @@ options:
       - present
 
 extends_documentation_fragment:
-    - docker
+  - docker
+  - docker.docker_py_2_documentation
 
 requirements:
-  - "python >= 2.7"
   - "docker >= 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.6.0 or newer is only available with the C(docker) module."
   - "Docker API >= 1.30"
 
 author:
@@ -162,10 +158,10 @@ import hashlib
 try:
     from docker.errors import APIError
 except ImportError:
-    # missing docker-py handled in ansible.module_utils.docker_common
+    # missing docker-py handled in ansible.module_utils.docker.common
     pass
 
-from ansible.module_utils.docker_common import AnsibleDockerClient, DockerBaseClass, compare_generic
+from ansible.module_utils.docker.common import AnsibleDockerClient, DockerBaseClass, compare_generic
 from ansible.module_utils._text import to_native, to_bytes
 
 

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

@@ -586,30 +586,22 @@ options:
       - Path to the working directory.
     version_added: "2.4"
 extends_documentation_fragment:
-    - docker
+  - docker
+  - docker.docker_py_1_documentation
 
 author:
-    - "Cove Schneider (@cove)"
+  - "Cove Schneider (@cove)"
-    - "Joshua Conner (@joshuaconner)"
+  - "Joshua Conner (@joshuaconner)"
-    - "Pavel Antonov (@softzilla)"
+  - "Pavel Antonov (@softzilla)"
-    - "Thomas Steinbach (@ThomasSteinbach)"
+  - "Thomas Steinbach (@ThomasSteinbach)"
-    - "Philippe Jandot (@zfil)"
+  - "Philippe Jandot (@zfil)"
-    - "Daan Oosterveld (@dusdanig)"
+  - "Daan Oosterveld (@dusdanig)"
-    - "Chris Houseknecht (@chouseknecht)"
+  - "Chris Houseknecht (@chouseknecht)"
-    - "Kassian Sun (@kassiansun)"
+  - "Kassian Sun (@kassiansun)"
 
 requirements:
-    - "python >= 2.6"
+  - "docker-py >= 1.8.0"
-    - "docker-py >= 1.8.0"
+  - "Docker API >= 1.20"
-    - "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. Also note that when both modules are installed
-       and one of them is uninstalled, the other might no longer function and a
-       reinstall of it is required."
-    - "Docker API >= 1.20"
 '''
 
 EXAMPLES = '''
@@ -875,7 +867,7 @@ from datetime import timedelta
 from distutils.version import LooseVersion
 
 from ansible.module_utils.basic import human_to_bytes
-from ansible.module_utils.docker_common import (
+from ansible.module_utils.docker.common import (
     AnsibleDockerClient,
     DockerBaseClass, sanitize_result, is_image_name_id,
     compare_generic, DifferenceTracker,
@@ -884,14 +876,14 @@ from ansible.module_utils.six import string_types
 
 try:
     from docker import utils
-    from ansible.module_utils.docker_common import docker_version
+    from ansible.module_utils.docker.common import docker_version
     if LooseVersion(docker_version) >= LooseVersion('1.10.0'):
         from docker.types import Ulimit, LogConfig
     else:
         from docker.utils.types import Ulimit, LogConfig
     from docker.errors import APIError, NotFound
 except Exception:
-    # missing docker-py handled in ansible.module_utils.docker
+    # missing docker-py handled in ansible.module_utils.docker.common
     pass
 
 
@@ -1546,7 +1538,7 @@ class TaskParameters(DockerBaseClass):
                     elif key == 'retries':
                         try:
                             result[key] = int(result[key])
-                        except Exception as e:
+                        except Exception as dummy:
                             self.fail('Cannot parse number of retries for healthcheck. '
                                       'Expected an integer, got "{0}".'.format(result[key]))
 
@@ -2555,7 +2547,7 @@ class ContainerManager(DockerBaseClass):
             while True:
                 try:
                     response = self.client.remove_container(container_id, v=volume_state, link=link, force=force)
-                except NotFound as exc:
+                except NotFound as dummy:
                     pass
                 except APIError as exc:
                     if 'Unpause the container before stopping or killing' in exc.explanation:

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

@@ -32,23 +32,15 @@ options:
       - When identifying an existing container name may be a name or a long or short container ID.
     required: true
 extends_documentation_fragment:
-    - docker
+  - docker
+  - docker.docker_py_1_documentation
 
 author:
-    - "Felix Fontein (@felixfontein)"
+  - "Felix Fontein (@felixfontein)"
 
 requirements:
-    - "python >= 2.6"
+  - "docker-py >= 1.8.0"
-    - "docker-py >= 1.8.0"
+  - "Docker API >= 1.20"
-    - "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. Also note that when both modules are installed
-       and one of them is uninstalled, the other might no longer function and a
-       reinstall of it is required."
-    - "Docker API >= 1.20"
 '''
 
 EXAMPLES = '''
@@ -114,7 +106,7 @@ docker_container:
     }'
 '''
 
-from ansible.module_utils.docker_common import AnsibleDockerClient
+from ansible.module_utils.docker.common import AnsibleDockerClient
 
 
 def main():

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

@@ -91,23 +91,15 @@ options:
     type: bool
     default: no
 extends_documentation_fragment:
-    - docker
+  - docker
+  - docker.docker_py_1_documentation
 
 author:
-    - Piotr Wojciechowski (@WojciechowskiPiotr)
+  - Piotr Wojciechowski (@WojciechowskiPiotr)
 
 requirements:
-    - "python >= 2.6"
+  - "docker-py >= 1.10.0"
-    - "docker-py >= 1.10.0"
+  - "Docker API >= 1.21"
-    - "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. Also note that when both modules are installed
-       and one of them is uninstalled, the other might no longer function and a
-       reinstall of it is required."
-    - "Docker API >= 1.21"
 '''
 
 EXAMPLES = '''
@@ -186,20 +178,16 @@ docker_disk_usage:
 
 '''
 
-from ansible.module_utils.docker_common import AnsibleDockerClient, DockerBaseClass
+from ansible.module_utils.docker.common import AnsibleDockerClient, DockerBaseClass
 from ansible.module_utils._text import to_native
 
 try:
-    from docker.errors import APIError, NotFound
+    from docker.errors import APIError
 except ImportError:
-    # missing docker-py handled in ansible.module_utils.docker_common
+    # missing docker-py handled in ansible.module_utils.docker.common
     pass
 
-try:
+from ansible.module_utils.docker.common import clean_dict_booleans_for_docker_api
-    from ansible.module_utils.docker_common import docker_version, clean_dict_booleans_for_docker_api
-except Exception as dummy:
-    # missing docker-py handled in ansible.module_utils.docker
-    pass
 
 
 class DockerHostManager(DockerBaseClass):

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

@@ -175,19 +175,11 @@ options:
     version_added: "2.0"
 
 extends_documentation_fragment:
-    - docker
+  - docker
+  - docker.docker_py_1_documentation
 
 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. Also note that when both modules are installed
-     and one of them is uninstalled, the other might no longer function and a
-     reinstall of it is required."
   - "Docker API >= 1.20"
 
 author:
@@ -276,7 +268,7 @@ image:
 import os
 import re
 
-from ansible.module_utils.docker_common import (
+from ansible.module_utils.docker.common import (
     HAS_DOCKER_PY_2, HAS_DOCKER_PY_3, AnsibleDockerClient, DockerBaseClass, is_image_name_id,
 )
 from ansible.module_utils._text import to_native

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

@@ -32,19 +32,11 @@ options:
     required: true
 
 extends_documentation_fragment:
-    - docker
+  - docker
+  - docker.docker_py_1_documentation
 
 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. Also note that when both modules are installed
-     and one of them is uninstalled, the other might no longer function and a
-     reinstall of it is required."
   - "Docker API >= 1.20"
 
 author:
@@ -161,10 +153,10 @@ images:
 try:
     from docker import utils
 except ImportError:
-    # missing docker-py handled in ansible.module_utils.docker_common
+    # missing docker-py handled in ansible.module_utils.docker.common
     pass
 
-from ansible.module_utils.docker_common import AnsibleDockerClient, DockerBaseClass, is_image_name_id
+from ansible.module_utils.docker.common import AnsibleDockerClient, DockerBaseClass, is_image_name_id
 
 
 class ImageManager(DockerBaseClass):

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

@@ -72,23 +72,15 @@ options:
     default: 'present'
 
 extends_documentation_fragment:
-    - docker
+  - docker
+  - docker.docker_py_1_documentation
 requirements:
-    - "python >= 2.6"
+  - "docker-py >= 1.8.0"
-    - "docker-py >= 1.8.0"
+  - "Docker API >= 1.20"
-    - "Please note that the L(docker-py,https://pypi.org/project/docker-py/) Python
+  - "Only to be able to logout, that is for I(state) = C(absent): the C(docker) command line utility"
-       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. Also note that when both modules are installed
-       and one of them is uninstalled, the other might no longer function and a
-       reinstall of it is required."
-    - "Docker API >= 1.20"
-    - 'Only to be able to logout (state=absent): the docker command line utility'
 author:
-    - Olaf Kilian (@olsaki) <olaf.kilian@symanex.com>
+  - Olaf Kilian (@olsaki) <olaf.kilian@symanex.com>
-    - Chris Houseknecht (@chouseknecht)
+  - Chris Houseknecht (@chouseknecht)
 '''
 
 EXAMPLES = '''
@@ -134,7 +126,7 @@ import os
 import re
 
 from ansible.module_utils._text import to_bytes, to_text
-from ansible.module_utils.docker_common import AnsibleDockerClient, DEFAULT_DOCKER_REGISTRY, DockerBaseClass, EMAIL_REGEX
+from ansible.module_utils.docker.common import AnsibleDockerClient, DEFAULT_DOCKER_REGISTRY, DockerBaseClass, EMAIL_REGEX
 
 
 class LoginManager(DockerBaseClass):

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

@@ -161,25 +161,17 @@ options:
     required: false
 
 extends_documentation_fragment:
-    - docker
+  - docker
+  - docker.docker_py_1_documentation
 
 author:
-    - "Ben Keith (@keitwb)"
+  - "Ben Keith (@keitwb)"
-    - "Chris Houseknecht (@chouseknecht)"
+  - "Chris Houseknecht (@chouseknecht)"
-    - "Dave Bendit (@DBendit)"
+  - "Dave Bendit (@DBendit)"
 
 requirements:
-    - "python >= 2.6"
+  - "docker-py >= 1.10.0"
-    - "docker-py >= 1.10.0"
+  - "The docker server >= 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. Also note that when both modules are installed
-       and one of them is uninstalled, the other might no longer function and a
-       reinstall of it is required."
-    - "The docker server >= 1.10.0"
 '''
 
 EXAMPLES = '''
@@ -265,7 +257,7 @@ import re
 
 from distutils.version import LooseVersion
 
-from ansible.module_utils.docker_common import (
+from ansible.module_utils.docker.common import (
     AnsibleDockerClient,
     DockerBaseClass,
     docker_version,
@@ -275,11 +267,10 @@ from ansible.module_utils.docker_common import (
 
 try:
     from docker import utils
-    from docker.errors import NotFound
     if LooseVersion(docker_version) >= LooseVersion('2.0.0'):
         from docker.types import IPAMPool, IPAMConfig
 except Exception:
-    # missing docker-py handled in ansible.module_utils.docker_common
+    # missing docker-py handled in ansible.module_utils.docker.common
     pass
 
 

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

@@ -32,23 +32,15 @@ options:
       - When identifying an existing network name may be a name or a long or short network ID.
     required: true
 extends_documentation_fragment:
-    - docker
+  - docker
+  - docker.docker_py_1_documentation
 
 author:
-    - "Dave Bendit (@DBendit)"
+  - "Dave Bendit (@DBendit)"
 
 requirements:
-    - "python >= 2.6"
+  - "docker-py >= 1.8.0"
-    - "docker-py >= 1.8.0"
+  - "Docker API >= 1.21"
-    - "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. Also note that when both modules are installed
-       and one of them is uninstalled, the other might no longer function and a
-       reinstall of it is required."
-    - "Docker API >= 1.21"
 '''
 
 EXAMPLES = '''
@@ -110,7 +102,7 @@ docker_network:
     }'
 '''
 
-from ansible.module_utils.docker_common import AnsibleDockerClient
+from ansible.module_utils.docker.common import AnsibleDockerClient
 
 
 def main():

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

@@ -76,19 +76,11 @@ options:
         required: false
         type: str
 extends_documentation_fragment:
-    - docker
+  - docker
+  - docker.docker_py_1_documentation
 requirements:
-    - "python >= 2.6"
+  - "docker-py >= 1.10.0"
-    - "docker-py >= 1.10.0"
+  - Docker API >= 1.25
-    - "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. Also note that when both modules are installed
-       and one of them is uninstalled, the other might no longer function and a
-       reinstall of it is required."
-    - Docker API >= 1.25
 author:
   - Piotr Wojciechowski (@WojciechowskiPiotr)
   - Thierry Bouvet (@tbouvet)
@@ -143,16 +135,16 @@ node_facts:
 try:
     from docker.errors import APIError
 except ImportError:
-    # missing docker-py handled in ansible.module_utils.docker_common
+    # missing docker-py handled in ansible.module_utils.docker.common
     pass
 
-from ansible.module_utils.docker_common import (
+from ansible.module_utils.docker.common import (
     DockerBaseClass,
 )
 
 from ansible.module_utils._text import to_native
 
-from ansible.module_utils.docker_swarm import AnsibleDockerSwarmClient
+from ansible.module_utils.docker.swarm import AnsibleDockerSwarmClient
 
 
 class TaskParameters(DockerBaseClass):

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

@@ -32,23 +32,15 @@ options:
       - When identifying an existing node name may either the hostname of the node (as registered in Swarm) or node ID.
     required: true
 extends_documentation_fragment:
-    - docker
+  - docker
+  - docker.docker_py_1_documentation
 
 author:
-    - Piotr Wojciechowski (@wojciechowskipiotr)
+  - Piotr Wojciechowski (@wojciechowskipiotr)
 
 requirements:
-    - "python >= 2.6"
+  - "docker-py >= 1.10.0"
-    - "docker-py >= 1.10.0"
+  - "Docker API >= 1.24"
-    - "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. Also note that when both modules are installed
-       and one of them is uninstalled, the other might no longer function and a
-       reinstall of it is required."
-    - "Docker API >= 1.24"
 '''
 
 EXAMPLES = '''
@@ -77,12 +69,12 @@ node_facts:
 
 from ansible.module_utils._text import to_native
 
-from ansible.module_utils.docker_swarm import AnsibleDockerSwarmClient
+from ansible.module_utils.docker.swarm import AnsibleDockerSwarmClient
 
 try:
     from docker.errors import APIError, NotFound
 except ImportError:
-    # missing docker-py handled in ansible.module_utils.docker_common
+    # missing docker-py handled in ansible.module_utils.docker.common
     pass
 
 

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

@@ -79,19 +79,15 @@ options:
     default: no
 
 extends_documentation_fragment:
-    - docker
+  - docker
+  - docker.docker_py_2_documentation
 
 author:
-    - "Felix Fontein (@felixfontein)"
+  - "Felix Fontein (@felixfontein)"
 
 requirements:
-    - "python >= 2.6"
+  - "docker >= 2.1.0"
-    - "docker >= 2.1.0"
+  - "Docker API >= 1.25"
-    - "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"
 '''
 
 EXAMPLES = '''
@@ -173,12 +169,12 @@ builder_cache_space_reclaimed:
 
 from distutils.version import LooseVersion
 
-from ansible.module_utils.docker_common import AnsibleDockerClient
+from ansible.module_utils.docker.common import AnsibleDockerClient
 
 try:
-    from ansible.module_utils.docker_common import docker_version, clean_dict_booleans_for_docker_api
+    from ansible.module_utils.docker.common import docker_version, clean_dict_booleans_for_docker_api
 except Exception as dummy:
-    # 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

@@ -68,14 +68,11 @@ options:
       - present
 
 extends_documentation_fragment:
-    - docker
+  - docker
+  - docker.docker_py_2_documentation
 
 requirements:
-  - "docker-py >= 2.1.0"
+  - "docker >= 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:
@@ -161,10 +158,10 @@ import hashlib
 try:
     from docker.errors import APIError
 except ImportError:
-    # missing docker-py handled in ansible.module_utils.docker_common
+    # missing docker-py handled in ansible.module_utils.docker.common
     pass
 
-from ansible.module_utils.docker_common import AnsibleDockerClient, DockerBaseClass, compare_generic
+from ansible.module_utils.docker.common import AnsibleDockerClient, DockerBaseClass, compare_generic
 from ansible.module_utils._text import to_native, to_bytes
 
 

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

@@ -133,15 +133,11 @@ options:
         type: bool
         default: 'no'
 extends_documentation_fragment:
-    - docker
+  - docker
+  - docker.docker_py_2_documentation
 requirements:
-    - python >= 2.7
+  - "docker >= 2.6.0"
-    - "docker >= 2.6.0"
+  - Docker API >= 1.25
-    - "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:
   - Thierry Bouvet (@tbouvet)
 '''
@@ -214,18 +210,16 @@ actions:
 '''
 
 import json
-from distutils.version import LooseVersion
 from time import sleep
 try:
     from docker.errors import APIError
 except ImportError:
-    # missing docker-py handled in ansible.module_utils.docker_common
+    # missing docker-py handled in ansible.module_utils.docker.common
     pass
 
-from ansible.module_utils.docker_common import (
+from ansible.module_utils.docker.common import (
     AnsibleDockerClient,
     DockerBaseClass,
-    docker_version,
 )
 from ansible.module_utils._text import to_native
 

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

@@ -335,14 +335,11 @@ options:
     - Before Ansible 2.8, the default value for this option was C(root).
       The default has been removed so that the user defined in the image is used if no user is specified here.
 extends_documentation_fragment:
-- docker
+  - docker
+  - docker.docker_py_2_documentation
 requirements:
-- "docker-py >= 2.0"
+  - "docker >= 2.0"
-- "Please note that the L(docker-py,https://pypi.org/project/docker-py/) Python
+  - "Docker API >= 1.24"
-   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.24"
 notes:
   - "Images will only resolve to the latest digest when using Docker API >= 1.30 and docker-py >= 3.2.0.
      When using older versions use C(force_update: true) to trigger the swarm to resolve a new image."
@@ -529,7 +526,7 @@ EXAMPLES = '''
 import time
 import shlex
 import operator
-from ansible.module_utils.docker_common import (
+from ansible.module_utils.docker.common import (
     AnsibleDockerClient,
     DifferenceTracker,
     DockerBaseClass,
@@ -544,7 +541,7 @@ try:
     from docker.utils import parse_repository_tag
     from docker.errors import APIError, DockerException
 except Exception:
-    # 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_volume.py

@@ -83,23 +83,15 @@ options:
       - present
 
 extends_documentation_fragment:
-    - docker
+  - docker
+  - docker.docker_py_1_documentation
 
 author:
-    - Alex Grönholm (@agronholm)
+  - Alex Grönholm (@agronholm)
 
 requirements:
-    - "python >= 2.6"
+  - "docker-py >= 1.10.0"
-    - "docker-py >= 1.10.0"
+  - "The docker server >= 1.9.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. Also note that when both modules are installed
-       and one of them is uninstalled, the other might no longer function and a
-       reinstall of it is required."
-    - "The docker server >= 1.9.0"
 '''
 
 EXAMPLES = '''
@@ -131,10 +123,10 @@ facts:
 try:
     from docker.errors import APIError
 except ImportError:
-    # missing docker-py handled in ansible.module_utils.docker_common
+    # missing docker-py handled in ansible.module_utils.docker.common
     pass
 
-from ansible.module_utils.docker_common import (
+from ansible.module_utils.docker.common import (
     DockerBaseClass,
     AnsibleDockerClient,
     DifferenceTracker,

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

@@ -29,23 +29,15 @@ options:
       - volume_name
 
 extends_documentation_fragment:
-    - docker
+  - docker
+  - docker.docker_py_1_documentation
 
 author:
-    - Felix Fontein (@felixfontein)
+  - Felix Fontein (@felixfontein)
 
 requirements:
-    - "python >= 2.6"
+  - "docker-py >= 1.8.0"
-    - "docker-py >= 1.8.0"
+  - "Docker API >= 1.21"
-    - "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. Also note that when both modules are installed
-       and one of them is uninstalled, the other might no longer function and a
-       reinstall of it is required."
-    - "Docker API >= 1.21"
 '''
 
 EXAMPLES = '''
@@ -91,10 +83,10 @@ docker_volume:
 try:
     from docker.errors import NotFound
 except ImportError:
-    # missing docker-py handled in ansible.module_utils.docker_common
+    # missing docker-py handled in ansible.module_utils.docker.common
     pass
 
-from ansible.module_utils.docker_common import AnsibleDockerClient
+from ansible.module_utils.docker.common import AnsibleDockerClient
 
 
 def get_existing_volume(client, volume_name):

lib/ansible/plugins/doc_fragments/docker.py

@@ -91,14 +91,42 @@ options:
         default: false
 
 notes:
-    - Connect to the Docker daemon by providing parameters with each task or by defining environment variables.
+  - Connect to the Docker daemon by providing parameters with each task or by defining environment variables.
-      You can define C(DOCKER_HOST), C(DOCKER_TLS_HOSTNAME), C(DOCKER_API_VERSION), C(DOCKER_CERT_PATH), C(DOCKER_SSL_VERSION),
+    You can define C(DOCKER_HOST), C(DOCKER_TLS_HOSTNAME), C(DOCKER_API_VERSION), C(DOCKER_CERT_PATH), C(DOCKER_SSL_VERSION),
-      C(DOCKER_TLS), C(DOCKER_TLS_VERIFY) and C(DOCKER_TIMEOUT). If you are using docker machine, run the script shipped
+    C(DOCKER_TLS), C(DOCKER_TLS_VERIFY) and C(DOCKER_TIMEOUT). If you are using docker machine, run the script shipped
-      with the product that sets up the environment. It will set these variables for you. See
+    with the product that sets up the environment. It will set these variables for you. See
-      U(https://docker-py.readthedocs.io/en/stable/machine/) for more details.
+    U(https://docker-py.readthedocs.io/en/stable/machine/) for more details.
-    - When connecting to Docker daemon with TLS, you might need to install additional Python packages.
+  - When connecting to Docker daemon with TLS, you might need to install additional Python packages.
-      For the Docker SDK for Python, version 2.4 or newer, this can be done by installing C(docker[tls]) with M(pip).
+    For the Docker SDK for Python, version 2.4 or newer, this can be done by installing C(docker[tls]) with M(pip).
-    - Note that the Docker SDK for Python only allows to specify the path to the Docker configuration for very few functions.
+  - Note that the Docker SDK for Python only allows to specify the path to the Docker configuration for very few functions.
-      In general, it will use C($HOME/docker/config.json) if the C(DOCKER_CONFIG) environment variable is not specified,
+    In general, it will use C($HOME/docker/config.json) if the C(DOCKER_CONFIG) environment variable is not specified,
-      and use C($DOCKER_CONFIG/config.json) otherwise.
+    and use C($DOCKER_CONFIG/config.json) otherwise.
+'''
+
+    # Additional, more specific stuff for minimal docker-py version < 2.0
+
+    DOCKER_PY_1_DOCUMENTATION = r'''
+options: {}
+requirements:
+  - "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. Also note that when both modules are installed
+     and one of them is uninstalled, the other might no longer function and a
+     reinstall of it is required."
+'''
+
+    # Additional, more specific stuff for minimal docker-py version >= 2.0.
+    # Note that docker-py >= 2.0 requires Python 2.7 or newer.
+
+    DOCKER_PY_2_DOCUMENTATION = r'''
+options: {}
+requirements:
+  - "Python >= 2.7"
+  - "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).
+     This module does I(not) work with docker-py."
 '''

test/units/module_utils/docker/test_common.py

@@ -1,6 +1,6 @@
 import pytest
 
-from ansible.module_utils.docker_common import (
+from ansible.module_utils.docker.common import (
     compare_dict_allow_more_present,
     compare_generic,
 )

test/units/modules/cloud/docker/test_docker_volume.py

@@ -5,7 +5,7 @@ import json
 import pytest
 
 from ansible.modules.cloud.docker import docker_volume
-from ansible.module_utils import docker_common
+from ansible.module_utils.docker import common
 
 pytestmark = pytest.mark.usefixtures('patch_ansible_module')
 
@@ -19,8 +19,8 @@ TESTCASE_DOCKER_VOLUME = [
 
 @pytest.mark.parametrize('patch_ansible_module', TESTCASE_DOCKER_VOLUME, indirect=['patch_ansible_module'])
 def test_create_volume_on_invalid_docker_version(mocker, capfd):
-    mocker.patch.object(docker_common, 'HAS_DOCKER_PY', True)
+    mocker.patch.object(common, 'HAS_DOCKER_PY', True)
-    mocker.patch.object(docker_common, 'docker_version', '1.8.0')
+    mocker.patch.object(common, 'docker_version', '1.8.0')
 
     with pytest.raises(SystemExit):
         docker_volume.main()