bpo-39353: Deprecate the binhex module (GH-18025)

Deprecate binhex4 and hexbin4 standards. Deprecate the binhex module
and the following binascii functions:

* b2a_hqx(), a2b_hqx()
* rlecode_hqx(), rledecode_hqx()
* crc_hqx()

1 files changed, 37 insertions, 12 deletions

diff --git a/Lib/binhex.py b/Lib/binhex.py
index 56b5f852c0..6ff38dd822 100644
--- a/Lib/binhex.py
+++ b/Lib/binhex.py
@@ -21,10 +21,16 @@ hexbin(inputfilename, outputfilename)
 # input. The resulting code (xx 90 90) would appear to be interpreted as an
 # escaped *value* of 0x90. All coders I've seen appear to ignore this nicety...
 #
+import binascii
+import contextlib
 import io
 import os
 import struct
-import binascii
+import warnings
+
+warnings.warn('the binhex module is deprecated', DeprecationWarning,
+              stacklevel=2)
+
 
 __all__ = ["binhex","hexbin","Error"]
 
@@ -76,6 +82,16 @@ class openrsrc:
     def close(self):
         pass
 
+
+# DeprecationWarning is already emitted on "import binhex". There is no need
+# to repeat the warning at each call to deprecated binascii functions.
+@contextlib.contextmanager
+def _ignore_deprecation_warning():
+    with warnings.catch_warnings():
+        warnings.filterwarnings('ignore', '', DeprecationWarning)
+        yield
+
+
 class _Hqxcoderengine:
     """Write data to the coder in 3-byte chunks"""
 
@@ -93,7 +109,8 @@ class _Hqxcoderengine:
         self.data = self.data[todo:]
         if not data:
             return
-        self.hqxdata = self.hqxdata + binascii.b2a_hqx(data)
+        with _ignore_deprecation_warning():
+            self.hqxdata = self.hqxdata + binascii.b2a_hqx(data)
         self._flush(0)
 
     def _flush(self, force):
@@ -109,7 +126,8 @@ class _Hqxcoderengine:
 
     def close(self):
         if self.data:
-            self.hqxdata = self.hqxdata + binascii.b2a_hqx(self.data)
+            with _ignore_deprecation_warning():
+                self.hqxdata = self.hqxdata + binascii.b2a_hqx(self.data)
         self._flush(1)
         self.ofp.close()
         del self.ofp
@@ -125,13 +143,15 @@ class _Rlecoderengine:
         self.data = self.data + data
         if len(self.data) < REASONABLY_LARGE:
             return
-        rledata = binascii.rlecode_hqx(self.data)
+        with _ignore_deprecation_warning():
+            rledata = binascii.rlecode_hqx(self.data)
         self.ofp.write(rledata)
         self.data = b''
 
     def close(self):
         if self.data:
-            rledata = binascii.rlecode_hqx(self.data)
+            with _ignore_deprecation_warning():
+                rledata = binascii.rlecode_hqx(self.data)
             self.ofp.write(rledata)
         self.ofp.close()
         del self.ofp
@@ -180,7 +200,8 @@ class BinHex:
         self._writecrc()
 
     def _write(self, data):
-        self.crc = binascii.crc_hqx(data, self.crc)
+        with _ignore_deprecation_warning():
+            self.crc = binascii.crc_hqx(data, self.crc)
         self.ofp.write(data)
 
     def _writecrc(self):
@@ -276,7 +297,8 @@ class _Hqxdecoderengine:
             #
             while True:
                 try:
-                    decdatacur, self.eof = binascii.a2b_hqx(data)
+                    with _ignore_deprecation_warning():
+                        decdatacur, self.eof = binascii.a2b_hqx(data)
                     break
                 except binascii.Incomplete:
                     pass
@@ -312,8 +334,9 @@ class _Rledecoderengine:
     def _fill(self, wtd):
         self.pre_buffer = self.pre_buffer + self.ifp.read(wtd + 4)
         if self.ifp.eof:
-            self.post_buffer = self.post_buffer + \
-                binascii.rledecode_hqx(self.pre_buffer)
+            with _ignore_deprecation_warning():
+                self.post_buffer = self.post_buffer + \
+                    binascii.rledecode_hqx(self.pre_buffer)
             self.pre_buffer = b''
             return
 
@@ -340,8 +363,9 @@ class _Rledecoderengine:
         else:
             mark = mark - 1
 
-        self.post_buffer = self.post_buffer + \
-            binascii.rledecode_hqx(self.pre_buffer[:mark])
+        with _ignore_deprecation_warning():
+            self.post_buffer = self.post_buffer + \
+                binascii.rledecode_hqx(self.pre_buffer[:mark])
         self.pre_buffer = self.pre_buffer[mark:]
 
     def close(self):
@@ -372,7 +396,8 @@ class HexBin:
 
     def _read(self, len):
         data = self.ifp.read(len)
-        self.crc = binascii.crc_hqx(data, self.crc)
+        with _ignore_deprecation_warning():
+            self.crc = binascii.crc_hqx(data, self.crc)
         return data
 
     def _checkcrc(self):