Specialized DockerExceptions
See original GitHub issueHello again!
while I’m working on the integration of python on whales into my applications, I found the error management mostly thought for a human use.
Currently all errors raise a DockerException that contains the exact error output produced by the CLI. That’s great when using the package by a human and provides enough information to debug the problem. But when the package is used to automate processes this approach is not very helpful and to be able to properly react, a parser of the exception is needed.
Just a practical example:
docker.service.inspect("my_service")
This command can fail for a number of reasons, for example:
the swarm is not initialized:
python_on_whales.utils.DockerException: The docker command executed was `/usr/local/bin/docker service inspect myservice`.
It returned with code 1
The content of stdout is '[]
'
The content of stderr is 'Status: Error response from daemon: This node is not a swarm manager. Use "docker swarm init" or "docker swarm join" to connect this node to swarm and try again., Code: 1
'
or the service does not exist:
python_on_whales.utils.DockerException: The docker command executed was `/usr/local/bin/docker service inspect myservice`.
It returned with code 1
The content of stdout is '[]
'
The content of stderr is 'Status: Error: no such service: myservice, Code: 1
'
Probably there are much more possible reasons, but two are enough for the example
To implement specific reactions to the different problems a parser of the exception is needed:
try:
docker.service.inspect("my_service")
except python_on_whales.utils.DockerException as e:
if "This node is not a swarm manager" is str(e):
initialized_my_node()
elif "no such service" in str(e):
log.error("This service does not exist")
else:
log.critical("Unexpected error")
I think that raise specific exceptions (that would extend the parent DockerException, of course) would be very very useful for the user experience:
try:
docker.service.inspect("my_service")
except python_on_whales.utils.SwarmNotInitialized:
initialized_my_node()
except python_on_whales.utis.NoSuchService:
log.error("This service does not exist")
except Exception:
log.critical("Unexpected error")
That means, in a practical way, move the parsing directly into the package to centralized that operation and make it transparent to the final user.
I understand that is a very boring issue but I’m pretty sure that would greatly improve the adoption… and of course I’m 100% available to ease this task as much as I can
Issue Analytics
- State:
- Created 2 years ago
- Comments:12 (12 by maintainers)
Top GitHub Comments
My plan is
raise different exceptions for different errors quickly, so by parsing the error message. Currently, with python-on-whales, it’s impossible to answer the question “does that image/container/network/volume exists?”, by calling the engine api, we can do that. So we need to fix it quicky. I would like a function
exists()
. So that we can dodocker.container.exists("my_container_name")
ormy_container.exists()
. This function would return a bool. We should also have an exception for different objects that don’t exists.Ask the docker team for different error codes from the CLI. It’s not only useful for python-on-whales, it may be also useful for people doing bash scripting. From a bash script, knowing if an image exists or not is only possible by parsing stderr. So not great. The CLI has some progress to do there.
I’m going to do the first step, but if you want to help and contribute, I’d be happy to review any pull request I can get 😃
Unfortunately still no activity from the issue about standardising exit-codes in docker-cli, but it was somehow expected.
In the meanwhile can I ask you some additional exceptions?
I’m working with local docker registries (with self signed certificates) and remote engines and I found some exceptions in case of untrusted certificates and invalid remote hosts
Invalid remote hosts are quite easy to be reproduced:
On the other side to raise errors for untrusted certificates it is need to spawn a docker registry with https enabled and a self signed certificate. This is a bit tricky so feel free to decline my request 😃
First, create a self signed certificate (note: the docker registry requires a specific format for the registry or the TLS certificate will not be accepted… after many tries I found the following workflow to produce a valid self signed certificate (in particular to create a certificate containing an IP SAN)
Please note that 192.168.1.7 is the local IP address of my network adapter, adjust with your own IP
If you want to extract the IP from python, I use the following code:
After creating the config.ini you can create the self signed certificate with:
Now you can spawn the registry:
And finally the exception:
as usual, thank you very much for you support!