zstandard: add compress()/decompress() convenience functions

People have requested these utility functions in the past. Now seems
like as good a time as any to add them.

Author: indygreg

docs/misc_apis.rst

@@ -22,16 +22,26 @@ https://github.com/facebook/zstd/blob/master/doc/zstd_compression_format.md.
    :members:
    :undoc-members:
 
-estimate_decompression_context_size()
-=====================================
+``estimate_decompression_context_size()``
+=========================================
 
 .. autofunction:: zstandard.estimate_decompression_context_size
 
-open()
-======
+``open()``
+==========
 
 .. autofunction:: zstandard.open
 
+``compress()``
+==============
+
+.. autofunction:: zstandard.compress
+
+``decompress()``
+================
+
+.. autofunction:: zstandard.decompress
+
 Constants
 =========
 

docs/news.rst

@@ -229,6 +229,9 @@ Changes
   defined via Python docstrings instead of spread across Sphinx ReST
   files and source code.
 * ``ZstdCompressionParameters`` now exposes a ``strategy`` property.
+* There are now ``compress()`` and ``decompress()`` convenience functions
+  on the ``zstandard`` module. These are simply wrappers around the
+  corresponding APIs on ``ZstdCompressor`` and ``ZstdDecompressor``.
 
 0.14.1 (released 2020-12-05)
 ============================

tests/test_utility.py

@@ -0,0 +1,21 @@
+import unittest
+
+import zstandard as zstd
+
+
+class TestCompress(unittest.TestCase):
+    def test_simple(self):
+        frame = zstd.compress(b"foobar")
+
+        fp = zstd.get_frame_parameters(frame)
+        self.assertEqual(fp.content_size, 6)
+        self.assertFalse(fp.has_checksum)
+
+        zstd.compress(b"foobar" * 16384, level=7)
+
+
+class TestDecompress(unittest.TestCase):
+    def test_simple(self):
+        source = b"foobar" * 8192
+        frame = zstd.compress(source)
+        self.assertEqual(zstd.decompress(frame), source)

zstandard/__init__.py

@@ -18,6 +18,8 @@
 import os
 import platform
 
+from typing import ByteString
+
 # Some Python implementations don't support C extensions. That's why we have
 # a CFFI implementation in the first place. The code here import one of our
 # "backends" then re-exports the symbols from this module. For convenience,
@@ -170,3 +172,39 @@ def open(
         )
     else:
         return fh
+
+
+def compress(data: ByteString, level: int = 3) -> bytes:
+    """Compress source data using the zstd compression format.
+
+    This performs one-shot compression using basic/default compression
+    settings.
+
+    This method is provided for convenience and is equivalent to calling
+    ``ZstdCompressor(level=level).compress(data)``.
+
+    If you find yourself calling this function in a tight loop,
+    performance will be greater if you construct a single ``ZstdCompressor``
+    and repeatedly call ``compress()`` on it.
+    """
+    cctx = ZstdCompressor(level=level)
+
+    return cctx.compress(data)
+
+
+def decompress(data: ByteString, max_output_size: int = 0) -> bytes:
+    """Decompress a zstd frame into its original data.
+
+    This performs one-shot decompression using basic/default compression
+    settings.
+
+    This method is provided for convenience and is equivalent to calling
+    ``ZstdDecompressor().decompress(data, max_output_size=max_output_size)``.
+
+    If you find yourself calling this function in a tight loop, performance
+    will be greater if you construct a single ``ZstdDecompressor`` and
+    repeatedly call ``decompress()`` on it.
+    """
+    dctx = ZstdDecompressor()
+
+    return dctx.decompress(data, max_output_size=max_output_size)

zstandard/__init__.pyi

@@ -457,3 +457,5 @@ def open(
     newline: Optional[str] = None,
     closefd: bool = None,
 ): ...
+def compress(data: ByteString, level: int = ...) -> bytes: ...
+def decompress(data: ByteString, max_output_size: int = ...) -> bytes: ...