[Python-checkins] Docs: Add bz2 usage examples (GH-13258)
Miss Islington (bot)
webhook-mailer at python.org
Mon May 13 14:50:23 EDT 2019
https://github.com/python/cpython/commit/ee9b5ce3903542a55e7f55817538d355bb260518
commit: ee9b5ce3903542a55e7f55817538d355bb260518
branch: 3.7
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: GitHub <noreply at github.com>
date: 2019-05-13T11:50:16-07:00
summary:
Docs: Add bz2 usage examples (GH-13258)
* Docs: Add bz2 usage examples
- Adds an "Examples of usage" section inspired by the one
found in the gzip docs
- Corrects the descriptions for ``compresslevel`` and ``data``:
- ``compresslevel`` must be an `int`, not any number. For
instance, passing a float will raise ``TypeError``
- Notes that `data` must be bytes-like
(cherry picked from commit be6939fb02e65b56c45377940b339d150b124d05)
Co-authored-by: Brad <brad.solomon.1124 at gmail.com>
files:
M Doc/library/bz2.rst
diff --git a/Doc/library/bz2.rst b/Doc/library/bz2.rst
index d5f622515a40..b247de6dfc85 100644
--- a/Doc/library/bz2.rst
+++ b/Doc/library/bz2.rst
@@ -83,7 +83,7 @@ All of the classes in this module may safely be accessed from multiple threads.
The *buffering* argument is ignored. Its use is deprecated.
- If *mode* is ``'w'`` or ``'a'``, *compresslevel* can be a number between
+ If *mode* is ``'w'`` or ``'a'``, *compresslevel* can be an integer between
``1`` and ``9`` specifying the level of compression: ``1`` produces the
least compression, and ``9`` (default) produces the most compression.
@@ -144,7 +144,7 @@ Incremental (de)compression
incrementally. For one-shot compression, use the :func:`compress` function
instead.
- *compresslevel*, if given, must be a number between ``1`` and ``9``. The
+ *compresslevel*, if given, must be an integer between ``1`` and ``9``. The
default is ``9``.
.. method:: compress(data)
@@ -230,9 +230,9 @@ One-shot (de)compression
.. function:: compress(data, compresslevel=9)
- Compress *data*.
+ Compress *data*, a :term:`bytes-like object <bytes-like object>`.
- *compresslevel*, if given, must be a number between ``1`` and ``9``. The
+ *compresslevel*, if given, must be an integer between ``1`` and ``9``. The
default is ``9``.
For incremental compression, use a :class:`BZ2Compressor` instead.
@@ -240,7 +240,7 @@ One-shot (de)compression
.. function:: decompress(data)
- Decompress *data*.
+ Decompress *data*, a :term:`bytes-like object <bytes-like object>`.
If *data* is the concatenation of multiple compressed streams, decompress
all of the streams.
@@ -250,3 +250,77 @@ One-shot (de)compression
.. versionchanged:: 3.3
Support for multi-stream inputs was added.
+.. _bz2-usage-examples:
+
+Examples of usage
+-----------------
+
+Below are some examples of typical usage of the :mod:`bz2` module.
+
+Using :func:`compress` and :func:`decompress` to demonstrate round-trip compression:
+
+ >>> import bz2
+
+ >>> data = b"""\
+ ... Donec rhoncus quis sapien sit amet molestie. Fusce scelerisque vel augue
+ ... nec ullamcorper. Nam rutrum pretium placerat. Aliquam vel tristique lorem,
+ ... sit amet cursus ante. In interdum laoreet mi, sit amet ultrices purus
+ ... pulvinar a. Nam gravida euismod magna, non varius justo tincidunt feugiat.
+ ... Aliquam pharetra lacus non risus vehicula rutrum. Maecenas aliquam leo
+ ... felis. Pellentesque semper nunc sit amet nibh ullamcorper, ac elementum
+ ... dolor luctus. Curabitur lacinia mi ornare consectetur vestibulum."""
+
+ >>> c = bz2.compress(data)
+ >>> len(data) / len(c) # Data compression ratio
+ 1.513595166163142
+
+ >>> d = bz2.decompress(c)
+ >>> data == d # Check equality to original object after round-trip
+ True
+
+Using :class:`BZ2Compressor` for incremental compression:
+
+ >>> import bz2
+
+ >>> def gen_data(chunks=10, chunksize=1000):
+ ... """Yield incremental blocks of chunksize bytes."""
+ ... for _ in range(chunks):
+ ... yield b"z" * chunksize
+ ...
+ >>> comp = bz2.BZ2Compressor()
+ >>> out = b""
+ >>> for chunk in gen_data():
+ ... # Provide data to the compressor object
+ ... out = out + comp.compress(chunk)
+ ...
+ >>> # Finish the compression process. Call this once you have
+ >>> # finished providing data to the compressor.
+ >>> out = out + comp.flush()
+
+The example above uses a very "nonrandom" stream of data
+(a stream of `b"z"` chunks). Random data tends to compress poorly,
+while ordered, repetitive data usually yields a high compression ratio.
+
+Writing and reading a bzip2-compressed file in binary mode:
+
+ >>> import bz2
+
+ >>> data = b"""\
+ ... Donec rhoncus quis sapien sit amet molestie. Fusce scelerisque vel augue
+ ... nec ullamcorper. Nam rutrum pretium placerat. Aliquam vel tristique lorem,
+ ... sit amet cursus ante. In interdum laoreet mi, sit amet ultrices purus
+ ... pulvinar a. Nam gravida euismod magna, non varius justo tincidunt feugiat.
+ ... Aliquam pharetra lacus non risus vehicula rutrum. Maecenas aliquam leo
+ ... felis. Pellentesque semper nunc sit amet nibh ullamcorper, ac elementum
+ ... dolor luctus. Curabitur lacinia mi ornare consectetur vestibulum."""
+
+ >>> with bz2.open("myfile.bz2", "wb") as f:
+ ... # Write compressed data to file
+ ... unused = f.write(data)
+
+ >>> with bz2.open("myfile.bz2", "rb") as f:
+ ... # Decompress data from file
+ ... content = f.read()
+
+ >>> content == data # Check equality to original object after round-trip
+ True
More information about the Python-checkins
mailing list