Proposal: A new user-focused API

[bfirsh]

Problem

The current API is a great wrapper around the REST API, but many common tasks that users want to do don't necessarily map directly to REST API calls. For example, simply running a container is a rather convoluted process.

Proposal

I am proposing we add a higher-level API focused on what users want to do. It should be the default, recommended way of using docker-py.

It could look something like this:

>>> import docker
>>> client = docker.from_env()

>>> client.containers.run("ubuntu", "echo hello world")
'hello world\n'

>>> client.containers.run("ubuntu", "tasks/reticulate-splines", detach=True)
<Container '45e6d2de7c54'>

>>> client.containers.list()
[<Container '45e6d2de7c54'>, <Container 'db18e4f20eaa'>, ...]

>>> container = client.containers.get('45e6d2de7c54')

>>> for line in container.logs(stream=True):
...   print line
Reticulating spline 2...
Reticulating spline 3...

See this sketch of a README for a more examples of how it could work. It intentionally starts with a common thing that users want to do which is complex with the current API: running containers.

Backwards compatibility

This is a good excuse for 2.0. ;)

The new API can be built on top of the current lower-level API. The current API can be made available to users in case they want that extra flexibility and to give them a seamless migration path (client.api.create_container(...) or something like that).

See also

• This is building on top of @shin-'s work in [WIP] Efficiency #788.
• Related issues: OO API? #1049 Add helper API on top of core API #417
• dockerrun, an example of how a run() method could work.

[TomasTomecek]

I agree that having the OO abstraction in docker-py would be great since that's what likely everyone is doing in their python projects using docker-py. (e.g. this is what I have in sen: common base class and object specific classes for container and image -- hence I would love to contribute some of the code back to this new API)

But please, make it backwards compatible. There's so many tools built on top of docker-py already. So I don't see why you would have to remove deprecate the already-used, stable and efficient low-level API.

[bfirsh]

A prototype here, if anyone's interested: https://github.com/bfirsh/docker-sdk-python

[bfirsh]

Implemented in #1186!