Make lzma.{encode,decode}_filter_properties private.

These functions were originally added to support LZMA compression in the zipfile
module, and are not of interest for the majority of users.

They can be made public in 3.4 if there is user interest, but in the meanwhile,
I've opted to present a smaller, simpler API for the module's initial release.

diff --git a/Doc/library/lzma.rst b/Doc/library/lzma.rst
index 3174dd3d4594e6b88fc76fad347270d30bd90c32..402fae203c1e9214d4aa0983a10df8729016d983 100644 (file)
--- a/Doc/library/lzma.rst
+++ b/Doc/library/lzma.rst
@@ -268,32 +268,6 @@ Miscellaneous
    feature set.
 
 
-.. function:: encode_filter_properties(filter)
-
-   Return a :class:`bytes` object encoding the options (properties) of the
-   filter specified by *filter* (a dictionary).
-
-   *filter* is interpreted as a filter specifier, as described in
-   :ref:`filter-chain-specs`.
-
-   The returned data does not include the filter ID itself, only the options.
-
-   This function is primarily of interest to users implementing custom file
-   formats.
-
-
-.. function:: decode_filter_properties(filter_id, encoded_props)
-
-   Return a dictionary describing a filter with ID *filter_id*, and options
-   (properties) decoded from the :class:`bytes` object *encoded_props*.
-
-   The returned dictionary is a filter specifier, as described in
-   :ref:`filter-chain-specs`.
-
-   This function is primarily of interest to users implementing custom file
-   formats.
-
-
 .. _filter-chain-specs:
 
 Specifying custom filter chains

diff --git a/Lib/lzma.py b/Lib/lzma.py
index f6232040d71fae193b5d0f3a49359b4c07e3bc47..ffcf812564efe1353854cf45c0565dd6aca017ff 100644 (file)
--- a/Lib/lzma.py
+++ b/Lib/lzma.py
@@ -19,12 +19,12 @@ __all__ = [
 
     "LZMACompressor", "LZMADecompressor", "LZMAFile", "LZMAError",
     "open", "compress", "decompress", "is_check_supported",
-    "encode_filter_properties", "decode_filter_properties",
 ]
 
 import builtins
 import io
 from _lzma import *
+from _lzma import _encode_filter_properties, _decode_filter_properties
 
 
 _MODE_CLOSED   = 0

diff --git a/Lib/test/test_lzma.py b/Lib/test/test_lzma.py
index a086586d486a94aa3b5f3690e0a4b8786edf306d..a13cf3bd09aa66d35011cf3a1c6f95b4cb4333df 100644 (file)
--- a/Lib/test/test_lzma.py
+++ b/Lib/test/test_lzma.py
@@ -1073,19 +1073,19 @@ class MiscellaneousTestCase(unittest.TestCase):
         # This value should not be a valid check ID.
         self.assertFalse(lzma.is_check_supported(lzma.CHECK_UNKNOWN))
 
-    def test_encode_filter_properties(self):
+    def test__encode_filter_properties(self):
         with self.assertRaises(TypeError):
-            lzma.encode_filter_properties(b"not a dict")
+            lzma._encode_filter_properties(b"not a dict")
         with self.assertRaises(ValueError):
-            lzma.encode_filter_properties({"id": 0x100})
+            lzma._encode_filter_properties({"id": 0x100})
         with self.assertRaises(ValueError):
-            lzma.encode_filter_properties({"id": lzma.FILTER_LZMA2, "junk": 12})
+            lzma._encode_filter_properties({"id": lzma.FILTER_LZMA2, "junk": 12})
         with self.assertRaises(lzma.LZMAError):
-            lzma.encode_filter_properties({"id": lzma.FILTER_DELTA,
+            lzma._encode_filter_properties({"id": lzma.FILTER_DELTA,
                                            "dist": 9001})
 
         # Test with parameters used by zipfile module.
-        props = lzma.encode_filter_properties({
+        props = lzma._encode_filter_properties({
                 "id": lzma.FILTER_LZMA1,
                 "pb": 2,
                 "lp": 0,
@@ -1094,14 +1094,14 @@ class MiscellaneousTestCase(unittest.TestCase):
             })
         self.assertEqual(props, b"]\x00\x00\x80\x00")
 
-    def test_decode_filter_properties(self):
+    def test__decode_filter_properties(self):
         with self.assertRaises(TypeError):
-            lzma.decode_filter_properties(lzma.FILTER_X86, {"should be": bytes})
+            lzma._decode_filter_properties(lzma.FILTER_X86, {"should be": bytes})
         with self.assertRaises(lzma.LZMAError):
-            lzma.decode_filter_properties(lzma.FILTER_DELTA, b"too long")
+            lzma._decode_filter_properties(lzma.FILTER_DELTA, b"too long")
 
         # Test with parameters used by zipfile module.
-        filterspec = lzma.decode_filter_properties(
+        filterspec = lzma._decode_filter_properties(
                 lzma.FILTER_LZMA1, b"]\x00\x00\x80\x00")
         self.assertEqual(filterspec["id"], lzma.FILTER_LZMA1)
         self.assertEqual(filterspec["pb"], 2)
@@ -1110,10 +1110,10 @@ class MiscellaneousTestCase(unittest.TestCase):
         self.assertEqual(filterspec["dict_size"], 8 << 20)
 
     def test_filter_properties_roundtrip(self):
-        spec1 = lzma.decode_filter_properties(
+        spec1 = lzma._decode_filter_properties(
                 lzma.FILTER_LZMA1, b"]\x00\x00\x80\x00")
-        reencoded = lzma.encode_filter_properties(spec1)
-        spec2 = lzma.decode_filter_properties(lzma.FILTER_LZMA1, reencoded)
+        reencoded = lzma._encode_filter_properties(spec1)
+        spec2 = lzma._decode_filter_properties(lzma.FILTER_LZMA1, reencoded)
         self.assertEqual(spec1, spec2)
 
 

diff --git a/Lib/zipfile.py b/Lib/zipfile.py
index c127c2c92f9666bb92d907a0a9c18358263ef90e..a6c07e61c5d5fc892990e1645301696710a51c85 100644 (file)
--- a/Lib/zipfile.py
+++ b/Lib/zipfile.py
@@ -495,9 +495,9 @@ class LZMACompressor:
         self._comp = None
 
     def _init(self):
-        props = lzma.encode_filter_properties({'id': lzma.FILTER_LZMA1})
+        props = lzma._encode_filter_properties({'id': lzma.FILTER_LZMA1})
         self._comp = lzma.LZMACompressor(lzma.FORMAT_RAW, filters=[
-                lzma.decode_filter_properties(lzma.FILTER_LZMA1, props)
+                lzma._decode_filter_properties(lzma.FILTER_LZMA1, props)
         ])
         return struct.pack('<BBH', 9, 4, len(props)) + props
 
@@ -529,7 +529,7 @@ class LZMADecompressor:
                 return b''
 
             self._decomp = lzma.LZMADecompressor(lzma.FORMAT_RAW, filters=[
-                    lzma.decode_filter_properties(lzma.FILTER_LZMA1,
+                    lzma._decode_filter_properties(lzma.FILTER_LZMA1,
                             self._unconsumed[4:4 + psize])
             ])
             data = self._unconsumed[4 + psize:]

diff --git a/Modules/_lzmamodule.c b/Modules/_lzmamodule.c
index 6720d4c04e32be8acd2cdb90caccfef692c00e32..b482a7767db18887babbe9381cb6d5bcfd207d97 100644 (file)
--- a/Modules/_lzmamodule.c
+++ b/Modules/_lzmamodule.c
@@ -1097,19 +1097,16 @@ is_check_supported(PyObject *self, PyObject *args)
 }
 
 
-PyDoc_STRVAR(encode_filter_properties_doc,
-"encode_filter_properties(filter) -> bytes\n"
+PyDoc_STRVAR(_encode_filter_properties_doc,
+"_encode_filter_properties(filter) -> bytes\n"
 "\n"
 "Return a bytes object encoding the options (properties) of the filter\n"
 "specified by *filter* (a dict).\n"
 "\n"
-"The result does not include the filter ID itself, only the options.\n"
-"\n"
-"This function is primarily of interest to users implementing custom\n"
-"file formats.\n");
+"The result does not include the filter ID itself, only the options.\n");
 
 static PyObject *
-encode_filter_properties(PyObject *self, PyObject *args)
+_encode_filter_properties(PyObject *self, PyObject *args)
 {
     PyObject *filterspec;
     lzma_filter filter;
@@ -1117,7 +1114,7 @@ encode_filter_properties(PyObject *self, PyObject *args)
     uint32_t encoded_size;
     PyObject *result = NULL;
 
-    if (!PyArg_ParseTuple(args, "O:encode_filter_properties", &filterspec))
+    if (!PyArg_ParseTuple(args, "O:_encode_filter_properties", &filterspec))
         return NULL;
 
     if (parse_filter_spec(&filter, filterspec) == NULL)
@@ -1146,24 +1143,21 @@ error:
 }
 
 
-PyDoc_STRVAR(decode_filter_properties_doc,
-"decode_filter_properties(filter_id, encoded_props) -> dict\n"
+PyDoc_STRVAR(_decode_filter_properties_doc,
+"_decode_filter_properties(filter_id, encoded_props) -> dict\n"
 "\n"
 "Return a dict describing a filter with ID *filter_id*, and options\n"
-"(properties) decoded from the bytes object *encoded_props*.\n"
-"\n"
-"This function is primarily of interest to users implementing custom\n"
-"file formats.\n");
+"(properties) decoded from the bytes object *encoded_props*.\n");
 
 static PyObject *
-decode_filter_properties(PyObject *self, PyObject *args)
+_decode_filter_properties(PyObject *self, PyObject *args)
 {
     Py_buffer encoded_props;
     lzma_filter filter;
     lzma_ret lzret;
     PyObject *result = NULL;
 
-    if (!PyArg_ParseTuple(args, "O&y*:decode_filter_properties",
+    if (!PyArg_ParseTuple(args, "O&y*:_decode_filter_properties",
                           lzma_vli_converter, &filter.id, &encoded_props))
         return NULL;
 
@@ -1187,10 +1181,10 @@ decode_filter_properties(PyObject *self, PyObject *args)
 static PyMethodDef module_methods[] = {
     {"is_check_supported", (PyCFunction)is_check_supported,
      METH_VARARGS, is_check_supported_doc},
-    {"encode_filter_properties", (PyCFunction)encode_filter_properties,
-     METH_VARARGS, encode_filter_properties_doc},
-    {"decode_filter_properties", (PyCFunction)decode_filter_properties,
-     METH_VARARGS, decode_filter_properties_doc},
+    {"_encode_filter_properties", (PyCFunction)_encode_filter_properties,
+     METH_VARARGS, _encode_filter_properties_doc},
+    {"_decode_filter_properties", (PyCFunction)_decode_filter_properties,
+     METH_VARARGS, _decode_filter_properties_doc},
     {NULL}
 };