qubes.exc
– Exceptions¶
As most of the modern programming languages, Python has exceptions, which can be
thrown (raise
d) when something goes bad. What exactly means “bad” depends
on several circumstances.
One of those circumstances is who exactly is to blame: programmer or user? Some errors are commited by programmer and will most probably result it program failure. But most errors are caused by the user, notably by specifying invalid commands or data input. Those errors should not result in failure, but fault and be handled gracefuly. One more time, what “gracefuly” means depends on specific program and its interface (for example GUI programs should most likely display some admonition, but will not crash).
In Qubes we have special exception class, qubes.exc.QubesException
,
which is dedicated to handling user-caused problems. Programmer errors should
not result in raising QubesException, but it should instead result in one of the
standard Python exception. QubesExceptions should have a nice message that can
be shown to the user. On the other hand, some children classes of QubesException
also inherit from children of StandardException
to allow uniform
except
clauses.
Often the error relates to some domain, because we expect it to be in certain
state, but it is not. For example to start a machine, it should be halted. For
that we have the children of the qubes.exc.QubesVMError
class. They
all take the domain in question as their first argument and an (optional)
message as the second. If not specified, there is stock message which is
generally informative enough.
On writing error messages¶
As a general rule, error messages should be short but precise. They should not blame user for error, but the user should know, what had been done wrong and what to do next.
If possible, write the message that is stating the fact, for example “Domain is not running” instead of “You forgot to start the domain” (you fool!). Avoid commanding user, like “Start the domain first” (user is not a function you can call for effect). Instead consider writing in negative form, implying expected state: “Domain is not running” instead of “Domain is paused” (yeah, what’s wrong with that?).
Also avoid implying the personhood of the computer, including adressing user in second person. For example, write “Sending message failed” instead of “I failed to send the message”.
Inheritance diagram¶

Module contents¶
Qubes OS exception hierarchy
-
exception
qubes.exc.
BackupAlreadyRunningError
(msg=None)[source]¶ Bases:
qubes.exc.QubesException
Thrown at user when they try to run the same backup twice at the same time
-
exception
qubes.exc.
BackupCancelledError
(msg=None)[source]¶ Bases:
qubes.exc.QubesException
Thrown at user when backup was manually cancelled
-
exception
qubes.exc.
QubesException
[source]¶ Bases:
Exception
Exception that can be shown to the user
-
exception
qubes.exc.
QubesFeatureNotFoundError
(domain, feature)[source]¶ Bases:
qubes.exc.QubesException
,KeyError
Feature not set for a given domain
-
exception
qubes.exc.
QubesLabelNotFoundError
(label)[source]¶ Bases:
qubes.exc.QubesException
,KeyError
Label does not exists
-
exception
qubes.exc.
QubesMemoryError
(vm, msg=None)[source]¶ Bases:
qubes.exc.QubesVMError
,MemoryError
Cannot start domain, because not enough memory is available
-
exception
qubes.exc.
QubesNoSuchPropertyError
(holder, prop_name, msg=None)[source]¶ Bases:
qubes.exc.QubesException
,AttributeError
Requested property does not exist
-
exception
qubes.exc.
QubesNoTemplateError
(vm, msg=None)[source]¶ Bases:
qubes.exc.QubesVMError
Cannot start domain, because there is no template
-
exception
qubes.exc.
QubesNotImplementedError
(msg=None)[source]¶ Bases:
qubes.exc.QubesException
,NotImplementedError
Thrown at user when some feature is not implemented
-
exception
qubes.exc.
QubesPoolInUseError
(pool, msg=None)[source]¶ Bases:
qubes.exc.QubesException
VM is in use, cannot remove.
-
exception
qubes.exc.
QubesPropertyValueError
(holder, prop, value, msg=None)[source]¶ Bases:
qubes.exc.QubesValueError
Cannot set value of qubes.property, because user-supplied value is wrong.
-
exception
qubes.exc.
QubesTagNotFoundError
(domain, tag)[source]¶ Bases:
qubes.exc.QubesException
,KeyError
Tag not set for a given domain
-
exception
qubes.exc.
QubesVMError
(vm, msg)[source]¶ Bases:
qubes.exc.QubesException
Some problem with domain state.
-
exception
qubes.exc.
QubesVMInUseError
(vm, msg=None)[source]¶ Bases:
qubes.exc.QubesVMError
VM is in use, cannot remove.
-
exception
qubes.exc.
QubesVMNotFoundError
(vmname)[source]¶ Bases:
qubes.exc.QubesException
,KeyError
Domain cannot be found in the system
-
exception
qubes.exc.
QubesVMNotHaltedError
(vm, msg=None)[source]¶ Bases:
qubes.exc.QubesVMError
Domain is not halted.
This exception is thrown when machine should be halted, but is not (either running or paused).
-
exception
qubes.exc.
QubesVMNotPausedError
(vm, msg=None)[source]¶ Bases:
qubes.exc.QubesVMNotStartedError
Domain is not paused.
This exception is thrown when machine should be paused, but is not.
-
exception
qubes.exc.
QubesVMNotRunningError
(vm, msg=None)[source]¶ Bases:
qubes.exc.QubesVMNotStartedError
Domain is not running.
This exception is thrown when machine should be running but is either halted or paused.
-
exception
qubes.exc.
QubesVMNotStartedError
(vm, msg=None)[source]¶ Bases:
qubes.exc.QubesVMError
Domain is not started.
This exception is thrown when machine is halted, but should be started (that is, either running or paused).
-
exception
qubes.exc.
QubesVMNotSuspendedError
(vm, msg=None)[source]¶ Bases:
qubes.exc.QubesVMError
Domain is not suspended.
This exception is thrown when machine should be suspended but is either halted or running.
-
exception
qubes.exc.
QubesVMShutdownTimeoutError
(vm, msg=None)[source]¶ Bases:
qubes.exc.QubesVMError
Domain shutdown timed out.
-
exception
qubes.exc.
QubesValueError
[source]¶ Bases:
qubes.exc.QubesException
,ValueError
Cannot set some value, because it is invalid, out of bounds, etc.