Utilities

Miscellaneous Utilities

This module provides asyncio and various logging and debugging utilities, such as exception_summary() and pretty_traceback(), used primarily for adding information into the logging stream.

async qemu.qmp.util.flush(writer: StreamWriter) → None

Utility function to ensure an asyncio.StreamWriter is fully drained.

asyncio.StreamWriter.drain only promises we will return to below the “high-water mark”. This function ensures we flush the entire buffer – by setting the high water mark to 0 and then calling drain. The flow control limits are restored after the call is completed.

qemu.qmp.util.upper_half(func: T) → T

Do-nothing decorator that annotates a method as an “upper-half” method.

These methods must not call bottom-half functions directly, but can schedule them to run.

qemu.qmp.util.bottom_half(func: T) → T

Do-nothing decorator that annotates a method as a “bottom-half” method.

These methods must take great care to handle their own exceptions whenever possible. If they go unhandled, they will cause termination of the loop.

These methods do not, in general, have the ability to directly report information to a caller’s context and will usually be collected as an asyncio.Task result instead.

They must not call upper-half functions directly.

qemu.qmp.util.exception_summary(exc: BaseException) → str

Return a summary string of an arbitrary exception.

It will be of the form “ExceptionType: Error Message” if the error string is non-empty, and just “ExceptionType” otherwise.

This code is based on CPython’s implementation of traceback.TracebackException.format_exception_only.

qemu.qmp.util.pretty_traceback(prefix: str = '  | ') → str

Formats the current traceback, indented to provide visual distinction.

This is useful for printing a traceback within a traceback for debugging purposes when encapsulating errors to deliver them up the stack; when those errors are printed, this helps provide a nice visual grouping to quickly identify the parts of the error that belong to the inner exception.

Parameters:

prefix – The prefix to append to each line of the traceback.

Returns:

A string, formatted something like the following:

| Traceback (most recent call last):
|   File "foobar.py", line 42, in arbitrary_example
|     foo.baz()
| ArbitraryError: [Errno 42] Something bad happened!