3a3d84f5ec
AQMP is a library, and ideally it should not print error diagnostics unless a user opts into seeing them. By default, Python will print all WARNING, ERROR or CRITICAL messages to screen if no logging configuration has been created by a client application. In AQMP's case, ERROR logging statements are used to report additional detail about runtime failures that will also eventually be reported to the client library via an Exception, so these messages should not be rendered by default. (Why bother to have them at all, then? In async contexts, there may be multiple Exceptions and we are only able to report one of them back to the client application. It is not reasonably easy to predict ahead of time if one or more of these Exceptions will be squelched. Therefore, it's useful to log intermediate failures to help make sense of the ultimate, resulting failure.) Add a NullHandler that will suppress these messages until a client application opts into logging via logging.basicConfig or similar. Note that upon calling basicConfig(), this handler will *not* suppress these messages from being displayed by the client's configuration. Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Paolo Bonzini <pbonzini@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Message-id: 20210923004938.3999963-8-jsnow@redhat.com Signed-off-by: John Snow <jsnow@redhat.com>
64 lines
1.7 KiB
Python
64 lines
1.7 KiB
Python
"""
|
|
QEMU Monitor Protocol (QMP) development library & tooling.
|
|
|
|
This package provides a fairly low-level class for communicating
|
|
asynchronously with QMP protocol servers, as implemented by QEMU, the
|
|
QEMU Guest Agent, and the QEMU Storage Daemon.
|
|
|
|
`QMPClient` provides the main functionality of this package. All errors
|
|
raised by this library dervive from `AQMPError`, see `aqmp.error` for
|
|
additional detail. See `aqmp.events` for an in-depth tutorial on
|
|
managing QMP events.
|
|
"""
|
|
|
|
# Copyright (C) 2020, 2021 John Snow for Red Hat, Inc.
|
|
#
|
|
# Authors:
|
|
# John Snow <jsnow@redhat.com>
|
|
#
|
|
# Based on earlier work by Luiz Capitulino <lcapitulino@redhat.com>.
|
|
#
|
|
# This work is licensed under the terms of the GNU GPL, version 2. See
|
|
# the COPYING file in the top-level directory.
|
|
|
|
import logging
|
|
import warnings
|
|
|
|
from .error import AQMPError
|
|
from .events import EventListener
|
|
from .message import Message
|
|
from .protocol import ConnectError, Runstate, StateError
|
|
from .qmp_client import ExecInterruptedError, ExecuteError, QMPClient
|
|
|
|
|
|
_WMSG = """
|
|
|
|
The Asynchronous QMP library is currently in development and its API
|
|
should be considered highly fluid and subject to change. It should
|
|
not be used by any other scripts checked into the QEMU tree.
|
|
|
|
Proceed with caution!
|
|
"""
|
|
|
|
warnings.warn(_WMSG, FutureWarning)
|
|
|
|
# Suppress logging unless an application engages it.
|
|
logging.getLogger('qemu.aqmp').addHandler(logging.NullHandler())
|
|
|
|
|
|
# The order of these fields impact the Sphinx documentation order.
|
|
__all__ = (
|
|
# Classes, most to least important
|
|
'QMPClient',
|
|
'Message',
|
|
'EventListener',
|
|
'Runstate',
|
|
|
|
# Exceptions, most generic to most explicit
|
|
'AQMPError',
|
|
'StateError',
|
|
'ConnectError',
|
|
'ExecuteError',
|
|
'ExecInterruptedError',
|
|
)
|