From 340674d78790d29289818022c8e1f92cf6d4be7e Mon Sep 17 00:00:00 2001 From: "Jonathan G. Underwood" Date: Sat, 10 Feb 2018 23:39:05 +0000 Subject: [PATCH 1/4] Fix some docstring list formatting issues --- lz4/frame/_frame.c | 38 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/lz4/frame/_frame.c b/lz4/frame/_frame.c index 6469231c..b1da8555 100644 --- a/lz4/frame/_frame.c +++ b/lz4/frame/_frame.c @@ -1544,19 +1544,19 @@ PyDoc_STRVAR "Returns:\n" \ " dict: Dictionary with keys:\n" \ "\n" \ - " - ``block_size`` (int): the maximum size (in bytes) of each block\n" \ - " - ``block_size_id`` (int): identifier for maximum block size\n" \ - " - ``content_checksum`` (bool): specifies whether the frame\n" \ - " contains a checksum of the uncompressed content\n" \ - " - ``content_size`` (int): uncompressed size in bytes of\n" \ - " frame content\n" \ - " - ``block_linked`` (bool): specifies whether the frame contains\n" \ - " blocks which are independently compressed (``False``) or\n" \ - " linked (``True``)\n" \ - " - ``block_checksum`` (bool): specifies whether each block\n" \ - " contains a checksum of its contents\n" \ - " - ``skippable`` (bool): whether the block is skippable (``True``)\n" \ - " or not (``False``)\n" + " - ``block_size`` (int): the maximum size (in bytes) of each block\n" \ + " - ``block_size_id`` (int): identifier for maximum block size\n" \ + " - ``content_checksum`` (bool): specifies whether the frame\n" \ + " contains a checksum of the uncompressed content\n" \ + " - ``content_size`` (int): uncompressed size in bytes of\n" \ + " frame content\n" \ + " - ``block_linked`` (bool): specifies whether the frame contains\n" \ + " blocks which are independently compressed (``False``) or\n" \ + " linked (``True``)\n" \ + " - ``block_checksum`` (bool): specifies whether each block\n" \ + " contains a checksum of its contents\n" \ + " - ``skippable`` (bool): whether the block is skippable (``True``)\n" \ + " or not (``False``)\n" ); PyDoc_STRVAR @@ -1604,8 +1604,8 @@ PyDoc_STRVAR " If the ``return_bytes_read`` argument is ``True`` this function\n" \ " returns a tuple consisting of:\n" \ "\n" \ - " - bytes or bytearray: Uncompressed data\n" \ - " - int: Number of bytes consumed from ``data``\n" + " - bytes or bytearray: Uncompressed data\n" \ + " - int: Number of bytes consumed from ``data``\n" ); PyDoc_STRVAR @@ -1630,10 +1630,10 @@ PyDoc_STRVAR "\n" \ " This function returns a tuple consisting of:\n" \ "\n" \ - " - bytes or bytearray: Uncompressed data\n" \ - " - int: Number of bytes consumed from input ``data``\n" \ - " - bool: ``True`` if the end of the compressed frame has been\n" \ - " reached. ``False`` otherwise.\n" + " - bytes or bytearray: Uncompressed data\n" \ + " - int: Number of bytes consumed from input ``data``\n" \ + " - bool: ``True`` if the end of the compressed frame has been\n" \ + " reached. ``False`` otherwise.\n" ); static PyMethodDef module_methods[] = From 8994e22739af02df1ad98d7332ea72d8515afec3 Mon Sep 17 00:00:00 2001 From: "Jonathan G. Underwood" Date: Sat, 10 Feb 2018 23:53:31 +0000 Subject: [PATCH 2/4] Detail end_frame kwarg for compress_flush properly --- lz4/frame/_frame.c | 32 ++++++++++++++++++-------------- 1 file changed, 18 insertions(+), 14 deletions(-) diff --git a/lz4/frame/_frame.c b/lz4/frame/_frame.c index b1da8555..6143aa8d 100644 --- a/lz4/frame/_frame.c +++ b/lz4/frame/_frame.c @@ -1507,29 +1507,33 @@ PyDoc_STRVAR PyDoc_STRVAR ( compress_flush__doc, - "compress_flush(context, return_bytearray=False)\n\n" \ - "Flushes a compression context returning any data buffed in the context as\n" \ - "compressed data. If ``end_frame`` is ``True`` an endmark and optional\n" \ - "checksum are appended, and the compression context is reset for re-use\n" \ - "for creating a new frame. The returned data should be appended to the\n" \ - "output of previous calls to ``compress``.\n" \ + "compress_flush(context, end_frame=True, return_bytearray=False)\n\n" \ + "Flushes a compression context returning any data buffed in the context\n" \ + "as compressed data. The returned data should be appended to the\n" \ + "output of previous calls to ``compress``. The ``end_frame`` argument\n" \ + "specifies whether or not the frame should be ended.\n" \ "\n" \ "Args:\n" \ " context (cCtx): Compression context\n" \ " end_frame (bool): If ``True``, in addition to flushing any buffered\n" \ " data, an end frame marker (and possibly a checksum) will be\n" \ - " appended to the data, and the compression context reset. If\n" \ - " ``end_frame`` is ``False`` but the underlying LZ4 library doesn't" \ - " support flushing without ending the frame, a ``RuntimeError``\n" \ - " will be raised. Default is ``True``.\n" \ + " appended to the data returned. In this case the compression\n" \ + " context will be reset and can be used for creating a new frame.\n" \ + " Default is ``True``.\n" \ "\n" \ "Keyword Args:\n" \ - " return_bytearray (bool): If True a bytearray object will be returned.\n" \ - " If False, a string of bytes is returned. The default is False.\n" \ + " return_bytearray (bool): If ``True`` a ``bytearray`` object will\n" \ + " be returned. If ``False``, a string of bytes is returned. The.\n" \ + " default is ``False``.\n" \ "\n" \ "Returns:\n" \ - " bytes or bytearray: Remaining (buffered) compressed data, and\n" \ - " optionally an end frame marker and frame content checksum.\n" + " bytes or bytearray: Remaining (buffered) compressed data, and\n" \ + " optionally an end frame marker and frame content checksum.\n" \ + "\n" \ + "Notes:\n" \ + " If ``end_frame`` is ``False`` but the underlying LZ4 library doesn't" \ + " support flushing without ending the frame, a ``RuntimeError``\n" \ + " will be raised.\n" ); PyDoc_STRVAR From fde78f3b199823bdab6d9c821205a0b7c3c96cf6 Mon Sep 17 00:00:00 2001 From: "Jonathan G. Underwood" Date: Sun, 11 Feb 2018 00:09:44 +0000 Subject: [PATCH 3/4] Improve _frame.c docstrings --- lz4/frame/_frame.c | 74 ++++++++++++++++++++++++++++------------------ 1 file changed, 45 insertions(+), 29 deletions(-) diff --git a/lz4/frame/_frame.c b/lz4/frame/_frame.c index 6143aa8d..f1903fd0 100644 --- a/lz4/frame/_frame.c +++ b/lz4/frame/_frame.c @@ -1390,9 +1390,11 @@ decompress_chunk (PyObject * Py_UNUSED (self), PyObject * args, PyDoc_STRVAR( create_compression_context__doc, - "create_compression_context()\n\n" \ + "create_compression_context()\n" \ + "\n" \ "Creates a Compression Context object, which will be used in all\n" \ - "compression operations.\n\n" \ + "compression operations.\n" \ + "\n" \ "Returns:\n" \ " cCtx: A compression context\n" ); @@ -1441,7 +1443,8 @@ PyDoc_STRVAR( PyDoc_STRVAR( compress__doc, "compress(data, compression_level=0, block_size=0, content_checksum=0,\n" \ - " block_linked=True, store_size=True, return_bytearray=False)\n\n" \ + "block_linked=True, store_size=True, return_bytearray=False)\n" \ + "\n" \ "Compresses ``data`` returning the compressed data as a complete frame.\n\n" \ "The returned data includes a header and endmark and so is suitable\n" \ "for writing to a file.\n\n" \ @@ -1459,8 +1462,9 @@ PyDoc_STRVAR ( compress_begin__doc, "compress_begin(context, source_size=0, compression_level=0, block_size=0,\n" \ - " content_checksum=0, content_size=1, block_mode=0, frame_type=0,\n" \ - " auto_flush=1)\n\n" \ + "content_checksum=0, content_size=1, block_mode=0, frame_type=0,\n" \ + "auto_flush=1)\n" \ + "\n" \ "Creates a frame header from a compression context.\n\n" \ "Args:\n" \ " context (cCtx): A compression context.\n\n" \ @@ -1484,30 +1488,36 @@ PyDoc_STRVAR PyDoc_STRVAR ( compress_chunk__doc, - "compress_chunk(context, data)\n\n" \ + "compress_chunk(context, data)\n" \ + "\n" \ "Compresses blocks of data and returns the compressed data.\n" \ "\n" \ "The returned data should be concatenated with the data returned from\n" \ - "`compress_begin` and any previous calls to `compress`.\n" \ + "`lz4.frame.compress_begin` and any previous calls to `lz4.frame.compress`.\n" \ "\n" \ "Args:\n" \ " context (cCtx): compression context\n" \ - " data (str, bytes or buffer-compatible object): data to compress\n\n" \ + " data (str, bytes or buffer-compatible object): data to compress\n" \ + "\n" \ "Keyword Args:\n" \ - " return_bytearray (bool): If ``True`` a bytearray object will be returned.\n" \ - " If ``False``, a string of bytes is returned. The default is False.\n\n" \ + " return_bytearray (bool): If ``True`` a bytearray object will be\n" \ + " returned. If ``False``, a string of bytes is returned. The\n" \ + " default is False.\n" \ + "\n" \ "Returns:\n" \ " bytes or bytearray: Compressed data\n\n" \ "Notes:\n" \ - " If auto flush is disabled (``auto_flush``=``False`` when calling\n" \ - " `compress_begin`) this function may buffer and retain some or all of\n" \ - " the compressed data for future calls to `compress`.\n" + " If auto flush is disabled (``auto_flush=False`` when calling\n" \ + " `lz4.frame.compress_begin`) this function may buffer and retain\n" \ + " some or all of the compressed data for future calls to\n" \ + " `lz4.frame.compress`.\n" ); PyDoc_STRVAR ( compress_flush__doc, - "compress_flush(context, end_frame=True, return_bytearray=False)\n\n" \ + "compress_flush(context, end_frame=True, return_bytearray=False)\n" \ + "\n" \ "Flushes a compression context returning any data buffed in the context\n" \ "as compressed data. The returned data should be appended to the\n" \ "output of previous calls to ``compress``. The ``end_frame`` argument\n" \ @@ -1566,20 +1576,23 @@ PyDoc_STRVAR PyDoc_STRVAR ( create_decompression_context__doc, - "create_decompression_context()\n\n" \ - "Creates a decompression context object, which will be used for\n" \ - "decompression operations.\n\n" \ - "Returns:\n" \ + "create_decompression_context()\n" \ + "\n" \ + "Creates a decompression context object, which will be used for\n" \ + "decompression operations.\n" \ + "\n" \ + "Returns:\n" \ " dCtx: A decompression context\n" ); PyDoc_STRVAR ( reset_decompression_context__doc, - "reset_decompression_context(context)\n\n" \ + "reset_decompression_context(context)\n" \ + "\n" \ "Resets a decompression context object. This is useful for recovering\n" \ "from an error or for stopping an unfinished decompression and starting\n" \ - "a new one with the same context\n" \ + "a new one with the same context\n" \ "\n" \ "Args:\n" \ " context (dCtx): A decompression context\n" @@ -1588,7 +1601,8 @@ PyDoc_STRVAR PyDoc_STRVAR ( decompress__doc, - "decompress(data)\n\n" \ + "decompress(data, return_bytearray=False, return_bytes_read=False)\n" \ + "\n" \ "Decompresses a frame of data and returns it as a string of bytes.\n" \ "\n" \ "Args:\n" \ @@ -1596,10 +1610,11 @@ PyDoc_STRVAR " This should contain a complete LZ4 frame of compressed data.\n" \ "\n" \ "Keyword Args:\n" \ - " return_bytearray (bool): If True a bytearray object will be returned.\n" \ - " If False, a string of bytes is returned. The default is False.\n" \ + " return_bytearray (bool): If ``True`` a bytearray object will be\n" \ + " returned. If ``False``, a string of bytes is returned. The\n" \ + " default is ``False``.\n" \ " return_bytes_read (bool): If ``True`` then the number of bytes read\n" \ - " from ``data`` will also be returned.\n" \ + " from ``data`` will also be returned. Default is ``False``\n" \ "\n" \ "Returns:\n" \ " bytes/bytearray or tuple: Uncompressed data and optionally the number" \ @@ -1615,7 +1630,8 @@ PyDoc_STRVAR PyDoc_STRVAR ( decompress_chunk__doc, - "decompress(context, data)\n\n" \ + "decompress(context, data)\n" \ + "\n" \ "Decompresses part of a frame of data. The returned uncompressed data\n" \ "should be catenated with the data returned from previous calls to\n" \ "`decompress_chunk`\n\n" \ @@ -1625,13 +1641,13 @@ PyDoc_STRVAR " frame of compressed data\n\n" \ "Keyword Args:\n" \ " max_length (int): if non-negative this specifies the maximum number" \ - " of bytes of uncompressed data to return. Default is -1.\n" \ - " return_bytearray (bool): If True a bytearray object will be returned.\n" \ - " If False, a string of bytes is returned. The default is False.\n\n" \ + " of bytes of uncompressed data to return. Default is ``-1``.\n" \ + " return_bytearray (bool): If ``True`` a bytearray object will be\n" \ + " returned.If ``False``, a string of bytes is returned. The\n" \ + " default is ``False``.\n" \ "\n" \ "Returns:\n" \ " tuple: (uncompressed data, bytes read, end of frame indicator)\n" \ - "\n" \ " This function returns a tuple consisting of:\n" \ "\n" \ " - bytes or bytearray: Uncompressed data\n" \ From 616a12fc3711b81619219dc60864f4e375ce8a90 Mon Sep 17 00:00:00 2001 From: "Jonathan G. Underwood" Date: Sun, 11 Feb 2018 08:38:54 +0000 Subject: [PATCH 4/4] Fix docstrings --- lz4/frame/_frame.c | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/lz4/frame/_frame.c b/lz4/frame/_frame.c index f1903fd0..5b7eab91 100644 --- a/lz4/frame/_frame.c +++ b/lz4/frame/_frame.c @@ -1493,7 +1493,8 @@ PyDoc_STRVAR "Compresses blocks of data and returns the compressed data.\n" \ "\n" \ "The returned data should be concatenated with the data returned from\n" \ - "`lz4.frame.compress_begin` and any previous calls to `lz4.frame.compress`.\n" \ + "`lz4.frame.compress_begin` and any subsequent calls to\n" \ + "`lz4.frame.compress_chunk`.\n" \ "\n" \ "Args:\n" \ " context (cCtx): compression context\n" \ @@ -1520,8 +1521,9 @@ PyDoc_STRVAR "\n" \ "Flushes a compression context returning any data buffed in the context\n" \ "as compressed data. The returned data should be appended to the\n" \ - "output of previous calls to ``compress``. The ``end_frame`` argument\n" \ - "specifies whether or not the frame should be ended.\n" \ + "output of previous calls to ``lz4.frame.compress_chunk``. The\n" \ + "``end_frame`` argument specifies whether or not the frame should be\n" \ + "ended.\n" \ "\n" \ "Args:\n" \ " context (cCtx): Compression context\n" \ @@ -1533,8 +1535,8 @@ PyDoc_STRVAR "\n" \ "Keyword Args:\n" \ " return_bytearray (bool): If ``True`` a ``bytearray`` object will\n" \ - " be returned. If ``False``, a string of bytes is returned. The.\n" \ - " default is ``False``.\n" \ + " be returned. If ``False``, a ``bytes`` object is returned.\n" \ + " The default is ``False``.\n" \ "\n" \ "Returns:\n" \ " bytes or bytearray: Remaining (buffered) compressed data, and\n" \