aiodocker
aiodocker copied to clipboard
aio-libs
Introduce typed DTOs in API arguments and responses
Long story short
Currently collections have different return values, containers.list() returns list of container objects whereas all other objects return the raw response from Docker engine as dict.
- Expected behaviour: All object.list() calls return object collections
- Actual behaviour: Return values are different for container and all others objects (volume, image, ...)
Details
As a user I'd expect to get a collection of objects from a .list() call. However, it might make sense to have access to the raw response too.
docker-py has different classes for each object, one api object for low-level stuff and a model object for high-level access. This seems to be a good approach in my opinion.
I'd be willing to provide a PR, but first I'd like to get some input on where to go, maybe there are some things I didn't consider,.
I usually works with things where I prefer to have access to the raw response and I don't use list that much.
But I agree that having some high level objects like docker-py would be nice.
Where would you like to start @wintamute?
Not sure what the best approach would be since the client (currently docker.py) needs to be split. Generally I try to avoid duplicate code, but in order to not break existing code, I'd create new classes for the new client, an api-client and a high-level client. I can add that and add additional examples in my fork in order to show what I mean. I'm using docker-py as a design guide, but there I'm not 100% sure how to do the api-client design (api-client.create_container() vs. api-client.containers.create() for example).
I also agree to have "some" high-level wrappers around the API results — especially I observed an embrassing case: the DockerContainer's attribute read in the result of list API and those read after calling .show() method significantly differ (because currently DockerContainer is a mere proxy of the API's return dictionaries and Docker's return values for those two APIs are not consistent unfortunately).
I think it's the way to go: wrapping API results with consistent interfaces. For compatibility it would be nice to experiment on a separate fork and later we could provide an optional accessor to the underlying low-level API return values.
