Re: [PATCH 06/10] python/aqmp: copy qmp docstrings to qemu.aqmp.legacy

[Hanna Reitz]

On 21.03.22 22:08, John Snow wrote:
> Copy the docstrings out of qemu.qmp, adjusting them as necessary to
> more accurately reflect the current state of this class.
>
> (Licensing: This is copying and modifying GPLv2-only licensed docstrings
> into a GPLv2-only file.)
>
> Signed-off-by: John Snow <jsnow@redhat.com>
> Reviewed-by: Vladimir Sementsov-Ogievskiy <vsementsov@virtuozzo.com>
> Reviewed-by: Beraldo Leal <bleal@redhat.com>
> ---
>   python/qemu/aqmp/legacy.py | 102 ++++++++++++++++++++++++++++++++++---
>   1 file changed, 94 insertions(+), 8 deletions(-)
>
> diff --git a/python/qemu/aqmp/legacy.py b/python/qemu/aqmp/legacy.py
> index 10c7c99c4f..20ffdd8956 100644
> --- a/python/qemu/aqmp/legacy.py
> +++ b/python/qemu/aqmp/legacy.py

[...]

> @@ -60,6 +63,21 @@ class QMPBadPortError(QMPError):
>   
>   
>   class QEMUMonitorProtocol:
> +    """
> +    Provide an API to connect to QEMU via QEMU Monitor Protocol (QMP)
> +    and then allow to handle commands and events.
> +
> +    :param address:  QEMU address, can be either a unix socket path (string)
> +                     or a tuple in the form ( address, port ) for a TCP
> +                     connection
> +    :param server:   Deprecated, ignored. (See 'accept')

Can’t help but notice that this is (technically) just wrong, because it 
isn’t ignored.  Are you afraid people might not be sufficiently 
dissuaded by the “deprecated” keyword?  (I mean, if that were the case, 
I’d suggest you write “Deprecated, because setting this to true might 
make your computer explode” instead.)

Hanna

> +    :param nickname: Optional nickname used for logging.
> +
> +    ..note::
> +        No connection is established during `__init__`, this is done by
> +        the `connect()` or `accept()` methods.
> +    """
> +
>       def __init__(self, address: SocketAddrT,
>                    server: bool = False,
>                    nickname: Optional[str] = None):