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.
5 years ago · 0c2bb3da04
parent 88df4e22d3
commit 0c2bb3da04
25 changed files with 178 additions and 274 deletions
--- a/.github/BOTMETA.yml
+++ b/.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_swarm.py: *docker
+  $module_utils/docker/: *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
--- a/lib/ansible/module_utils/docker/init.py
+++ b/lib/ansible/module_utils/docker/init.py
--- a/lib/ansible/module_utils/docker/common.py
+++ b/lib/ansible/module_utils/docker/common.py
--- a/lib/ansible/module_utils/docker/swarm.py
+++ b/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):
--- a/lib/ansible/modules/cloud/docker/docker_compose.py
+++ b/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"
-    - "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-compose >= 1.7.0"
-    - "Docker API >= 1.20"
-    - "PyYAML >= 3.11"
+  - "docker-py >= 1.8.0"
+  - "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 = {
--- a/lib/ansible/modules/cloud/docker/docker_config.py
+++ b/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


--- a/lib/ansible/modules/cloud/docker/docker_container.py
+++ b/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)"
-    - "Joshua Conner (@joshuaconner)"
-    - "Pavel Antonov (@softzilla)"
-    - "Thomas Steinbach (@ThomasSteinbach)"
-    - "Philippe Jandot (@zfil)"
-    - "Daan Oosterveld (@dusdanig)"
-    - "Chris Houseknecht (@chouseknecht)"
-    - "Kassian Sun (@kassiansun)"
+  - "Cove Schneider (@cove)"
+  - "Joshua Conner (@joshuaconner)"
+  - "Pavel Antonov (@softzilla)"
+  - "Thomas Steinbach (@ThomasSteinbach)"
+  - "Philippe Jandot (@zfil)"
+  - "Daan Oosterveld (@dusdanig)"
+  - "Chris Houseknecht (@chouseknecht)"
+  - "Kassian Sun (@kassiansun)"

 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"
+  - "docker-py >= 1.8.0"
+  - "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:
--- a/lib/ansible/modules/cloud/docker/docker_container_facts.py
+++ b/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"
-    - "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"
+  - "docker-py >= 1.8.0"
+  - "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():
--- a/lib/ansible/modules/cloud/docker/docker_host_facts.py
+++ b/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"
-    - "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"
+  - "docker-py >= 1.10.0"
+  - "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 docker_version, clean_dict_booleans_for_docker_api
-except Exception as dummy:
-    # missing docker-py handled in ansible.module_utils.docker
-    pass
+from ansible.module_utils.docker.common import clean_dict_booleans_for_docker_api


 class DockerHostManager(DockerBaseClass):
--- a/lib/ansible/modules/cloud/docker/docker_image.py
+++ b/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
--- a/lib/ansible/modules/cloud/docker/docker_image_facts.py
+++ b/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):
--- a/lib/ansible/modules/cloud/docker/docker_login.py
+++ b/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"
-    - "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"
-    - 'Only to be able to logout (state=absent): the docker command line utility'
+  - "docker-py >= 1.8.0"
+  - "Docker API >= 1.20"
+  - "Only to be able to logout, that is for I(state) = C(absent): the C(docker) command line utility"
 author:
-    - Olaf Kilian (@olsaki) <olaf.kilian@symanex.com>
-    - Chris Houseknecht (@chouseknecht)
+  - Olaf Kilian (@olsaki) <olaf.kilian@symanex.com>
+  - 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):
--- a/lib/ansible/modules/cloud/docker/docker_network.py
+++ b/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)"
-    - "Chris Houseknecht (@chouseknecht)"
-    - "Dave Bendit (@DBendit)"
+  - "Ben Keith (@keitwb)"
+  - "Chris Houseknecht (@chouseknecht)"
+  - "Dave Bendit (@DBendit)"

 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. 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"
+  - "docker-py >= 1.10.0"
+  - "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


--- a/lib/ansible/modules/cloud/docker/docker_network_facts.py
+++ b/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"
-    - "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"
+  - "docker-py >= 1.8.0"
+  - "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():
--- a/lib/ansible/modules/cloud/docker/docker_node.py
+++ b/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"
-    - "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
+  - "docker-py >= 1.10.0"
+  - 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):
--- a/lib/ansible/modules/cloud/docker/docker_node_facts.py
+++ b/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"
-    - "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"
+  - "docker-py >= 1.10.0"
+  - "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


--- a/lib/ansible/modules/cloud/docker/docker_prune.py
+++ b/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"
-    - "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"
+  - "docker >= 2.1.0"
+  - "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


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


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

--- a/lib/ansible/modules/cloud/docker/docker_swarm_service.py
+++ b/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"
- "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.24"
+  - "docker >= 2.0"
+  - "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


--- a/lib/ansible/modules/cloud/docker/docker_volume.py
+++ b/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"
-    - "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"
+  - "docker-py >= 1.10.0"
+  - "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,
--- a/lib/ansible/modules/cloud/docker/docker_volume_facts.py
+++ b/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"
-    - "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"
+  - "docker-py >= 1.8.0"
+  - "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):
--- a/lib/ansible/plugins/doc_fragments/docker.py
+++ b/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.
-      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
-      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.
-    - 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).
-    - 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,
-      and use C($DOCKER_CONFIG/config.json) otherwise.
+  - 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),
+    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
+    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.
+    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.
+    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.
+'''
+
+    # 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."
 '''
--- a/test/units/module_utils/docker/test_common.py
+++ b/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,
 )
--- a/test/units/modules/cloud/docker/test_docker_volume.py
+++ b/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(docker_common, 'docker_version', '1.8.0')
+    mocker.patch.object(common, 'HAS_DOCKER_PY', True)
+    mocker.patch.object(common, 'docker_version', '1.8.0')

    with pytest.raises(SystemExit):
        docker_volume.main()