Skip to content

Development #116

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jonathanunderwood merged 4 commits into from
Feb 11, 2018
+83 −61
Merged

Development #116

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
340674d
Fix some docstring list formatting issues
jonathanunderwood Feb 10, 2018
8994e22
Detail end_frame kwarg for compress_flush properly
jonathanunderwood Feb 10, 2018
fde78f3
Improve _frame.c docstrings
jonathanunderwood Feb 11, 2018
616a12f
Fix docstrings
jonathanunderwood Feb 11, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
144 changes: 83 additions & 61 deletions lz4/frame/_frame.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
);
Expand Down Expand Up @@ -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" \
Expand All @@ -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" \
Expand All @@ -1484,52 +1488,64 @@ 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 subsequent calls to\n" \
"`lz4.frame.compress_chunk`.\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, 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 ``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" \
" 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 ``bytes`` object is returned.\n" \
" The 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
Expand All @@ -1544,38 +1560,41 @@ 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
(
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"
Expand All @@ -1584,18 +1603,20 @@ 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" \
" data (str, bytes or buffer-compatible object): data to decompress.\n" \
" 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" \
Expand All @@ -1604,14 +1625,15 @@ 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
(
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" \
Expand All @@ -1621,19 +1643,19 @@ 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" \
" - 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[] =
Expand Down