On Mon, Jun 06, 2022 at 09:08:26PM -0500, Eric Blake wrote: > PEP257 recommends that doc comments start with a one line summary and > be a complete sentence. Tweak our existing comments to comply. It > also recommends the use of """ strings, and for u""" when a string > contains Unicode; however, for since it is easier to write ' than " in > OCaml pr statements, we stick with ''' and u''' strings rather than > follow the PEP completely. > > Also, enhance the documentation for nbd.Buffer.from_bytearray to match > the semantic changes from commit d477f7c7, before we change those > semantics yet again in an upcoming patch (copying is inefficient, we > are moving towards reusing the underlying buffer directly). > --- > generator/Python.ml | 23 ++++++++++++++--------- > 1 file changed, 14 insertions(+), 9 deletions(-) > > diff --git a/generator/Python.ml b/generator/Python.ml > index 3f672ba..392be87 100644 > --- a/generator/Python.ml > +++ b/generator/Python.ml > @@ -763,28 +763,33 @@ let > '''Asynchronous I/O persistent buffer''' > > def __init__(self, len): > - '''allocate an uninitialized AIO buffer used for nbd.aio_pread''' > + '''Allocate an uninitialized AIO buffer used for nbd.aio_pread.''' > self._o = libnbdmod.alloc_aio_buffer(len) > > @classmethod > def from_bytearray(cls, ba): > - '''create an AIO buffer from a bytearray''' > + '''Create an AIO buffer from a bytearray or other buffer-like object. > + > + If ba is not a buffer, it is tried as the parameter to the > + bytearray constructor. Otherwise, ba is copied. Either way, the > + resulting AIO buffer is independent from the original. > + ''' > o = libnbdmod.aio_buffer_from_bytearray(ba) > self = cls(0) > self._o = o > return self > > def to_bytearray(self): > - '''copy an AIO buffer into a bytearray''' > + '''Copy an AIO buffer into a bytearray.''' > return libnbdmod.aio_buffer_to_bytearray(self._o) > > def size(self): > - '''return the size of an AIO buffer''' > + '''Return the size of an AIO buffer.''' > return libnbdmod.aio_buffer_size(self._o) > > def is_zero(self, offset=0, size=-1): > - ''' > - Returns true if and only if all bytes in the buffer are zeroes. > + '''Returns true if and only if all bytes in the buffer are zeroes. > + > Note that a freshly allocated buffer is uninitialized, not zero. > > By default this tests the whole buffer, but you can restrict > @@ -801,11 +806,11 @@ let > '''NBD handle''' > > def __init__(self): > - '''create a new NBD handle''' > + '''Create a new NBD handle.''' > self._o = libnbdmod.create() > > def __del__(self): > - '''close the NBD handle and underlying connection''' > + '''Close the NBD handle and underlying connection.''' > if hasattr(self, '_o'): > libnbdmod.close(self._o) > > @@ -855,7 +860,7 @@ let > let longdesc = Str.global_replace py_fn_rex "C<nbd.\\1>" longdesc in > let longdesc = Str.global_replace py_const_rex "C<" longdesc in > let longdesc = pod2text longdesc in > - pr " '''▶ %s\n\n%s'''\n" shortdesc (String.concat "\n" > longdesc); > + pr " u'''▶ %s\n\n%s'''\n" shortdesc (String.concat "\n" > longdesc); > pr " return libnbdmod.%s(" name; > pr_wrap ',' (fun () -> > pr "self._o";
Reviewed-by: Richard W.M. Jones <rjo...@redhat.com> Rich. -- Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones Read my programming and virtualization blog: http://rwmj.wordpress.com nbdkit - Flexible, fast NBD server with plugins https://gitlab.com/nbdkit/nbdkit _______________________________________________ Libguestfs mailing list Libguestfs@redhat.com https://listman.redhat.com/mailman/listinfo/libguestfs