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.