Improve documentation on SSH connections / use of docker.DockerClient()

Here is my suggestion: Improve the documentation:

• docker.from_env() should state its return type: docker.DockerClient
• Add an example to connect to a Docker Daemon via SSH / ssh:// in the documentation of docker.DockerClient. Currently there isn't much about it (only hits: Change log: Bugfixes / Features).

As the documentation about SSH was scarce, I was searching the code for ssh on Github and found the tests/unit/utils_test.py, where APIClient is used directly and (for your amusement) the following happened:

Observed behaviour:

>>> client_ssh = docker.APIClient(base_url='ssh://127.0.0.1')
>>> client_ssh.containers.list()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
AttributeError: 'function' object has no attribute 'list'

What I expected at first:

>>> client_ssh = docker.APIClient(base_url='ssh://127.0.0.1')
>>> client_ssh.containers.list()
[]

So what's wrong? Let's compare the objects when docker.from_env() via local socket and APIClient() via SSH:

>>> client_local = docker.from_env()
>>> client_local
<docker.client.DockerClient object at 0x10a73bcd0>
>>> client_local.containers
<docker.models.containers.ContainerCollection object at 0x105ab7370>

>>> # vs.

>>> client_ssh = docker.APIClient(base_url='ssh://127.0.0.1')
>>> client_ssh
<docker.api.client.APIClient object at 0x10a6d34c0>
>>> client_ssh.containers
<bound method ContainerApiMixin.containers of <docker.api.client.APIClient object at 0x105a810a0>>

So they are different objects:

• docker.client.DockerClient vs docker.api.client.APIClient or
• docker.models.containers.ContainerCollection vs ContainerApiMixin.containers

So in the end, the problem was once again in front of the screen. I directly instantiated the low-level APIClient instead of the higher-level DockerClient (which is being instantiated identically and owns an APIClient instance as .api property, see here).

(Indeed, ContainerApiMixin.containers() is documented to be a function resulting in the exception from the first code example.)

Now this works as expected:

>>> client_ssh = docker.DockerClient(base_url='ssh://192.168.2.2')
>>> client_ssh.containers.list()
[]
>>>

BTW: I guess, the problem in #2599 is related, as the error is almost the same:

AttributeError: 'function' object has no attribute 'run'

In that bug report too, the client.containers is of kind other than expected, I'd say.

My setting:

Python 3.8.3 (default, May 27 2020, 20:54:22) 
[Clang 11.0.3 (clang-1103.0.32.59)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> from pprint import pprint
>>> 
>>> import docker
>>> 
>>> client_local = docker.from_env()
>>> 
>>> pprint(client_local.version())
{'ApiVersion': '1.40',
 'Arch': 'amd64',
 'BuildTime': '2020-03-11T01:29:16.000000000+00:00',
 'Components': [{'Details': {'ApiVersion': '1.40',
                             'Arch': 'amd64',
                             'BuildTime': '2020-03-11T01:29:16.000000000+00:00',
                             'Experimental': 'false',
                             'GitCommit': 'afacb8b',
                             'GoVersion': 'go1.12.17',
                             'KernelVersion': '4.19.76-linuxkit',
                             'MinAPIVersion': '1.12',
                             'Os': 'linux'},
                 'Name': 'Engine',
                 'Version': '19.03.8'},
                {'Details': {'GitCommit': '7ad184331fa3e55e52b890ea95e65ba581ae3429'},
                 'Name': 'containerd',
                 'Version': 'v1.2.13'},
                {'Details': {'GitCommit': 'dc9208a3303feef5b3839f4323d9beb36df0a9dd'},
                 'Name': 'runc',
                 'Version': '1.0.0-rc10'},
                {'Details': {'GitCommit': 'fec3683'},
                 'Name': 'docker-init',
                 'Version': '0.18.0'}],
 'GitCommit': 'afacb8b',
 'GoVersion': 'go1.12.17',
 'KernelVersion': '4.19.76-linuxkit',
 'MinAPIVersion': '1.12',
 'Os': 'linux',
 'Platform': {'Name': 'Docker Engine - Community'},
 'Version': '19.03.8'}
>>> 

Start with the linked DockerClient and from_env documentation, then read tests/unit/utils_test.py and the docker/client.py entry point referenced in the issue. Done means the return type is documented and the DockerClient SSH connection has a clear working example that distinguishes it from APIClient.