Rename and document hexlify/unhexlify wrappers

These wrapper work differently than functions from binascii,
even though they have the same name. That could be a source
of confusion. In this commit, the functions are renamed to
make it clear that they operate with strings.

Because they cannot handle Unicode in any meaningful way,
I have changed their implementation to not even attempt it,
as it is more complicated to handle Unicode, and it doesn't
even work anyway.

Author: ysangkok

bitcoin/rpc.py

@@ -41,8 +41,35 @@
 
 DEFAULT_HTTP_TIMEOUT = 30
 
-unhexlify = lambda h: binascii.unhexlify(h.encode('utf8'))
-hexlify = lambda b: binascii.hexlify(b).decode('utf8')
+def unhexlify_str(h):
+    """
+    Converts a string containing hexadecimal encoding into a bytes-object.
+
+    It works by encoding the given string h as ASCII, then interpreting each of
+    its two-character ASCII tuples as bytes:
+        - "00" to byte 0
+        - "ff" to byte 255
+        - "FF" also to byte 255
+
+    The string must only contain characters in the ranges 0-9, a-f and A-F.
+
+    If the string contains characters not in ASCII,
+        UnicodeEncodeError is raised.
+    If the string contains out-of-range ASCII characters,
+        binascii.Error is raised.
+    If number of encoded ASCII bytes is odd,
+        binascii.Error is raised.
+    """
+    return binascii.unhexlify(h.encode('ascii'))
+
+def hexlify_str(b):
+    """
+    Given an arbitrary bytes-like object, returns a string (that would encode
+    as ASCII) containing the hex-representation of the bytes-like object.
+
+    Always succeeds.
+    """
+    return binascii.hexlify(b).decode('ascii')
 
 
 class JSONRPCError(Exception):
@@ -365,10 +392,10 @@ def fundrawtransaction(self, tx, include_watching=False):
          'changepos': Position of added change output, or -1,
         }
         """
-        hextx = hexlify(tx.serialize())
+        hextx = hexlify_str(tx.serialize())
         r = self._call('fundrawtransaction', hextx, include_watching)
 
-        r['tx'] = CTransaction.deserialize(unhexlify(r['hex']))
+        r['tx'] = CTransaction.deserialize(unhexlify_str(r['hex']))
         del r['hex']
 
         r['fee'] = int(r['fee'] * COIN)
@@ -456,7 +483,7 @@ def getblockheader(self, block_hash, verbose=False):
                     'nextblockhash':nextblockhash,
                     'chainwork':x(r['chainwork'])}
         else:
-            return CBlockHeader.deserialize(unhexlify(r))
+            return CBlockHeader.deserialize(unhexlify_str(r))
 
 
     def getblock(self, block_hash):
@@ -477,7 +504,7 @@ def getblock(self, block_hash):
         except InvalidAddressOrKeyError as ex:
             raise IndexError('%s.getblock(): %s (%d)' %
                     (self.__class__.__name__, ex.error['message'], ex.error['code']))
-        return CBlock.deserialize(unhexlify(r))
+        return CBlock.deserialize(unhexlify_str(r))
 
     def getblockcount(self):
         """Return the number of blocks in the longest block chain"""
@@ -556,7 +583,7 @@ def getrawtransaction(self, txid, verbose=False):
             raise IndexError('%s.getrawtransaction(): %s (%d)' %
                     (self.__class__.__name__, ex.error['message'], ex.error['code']))
         if verbose:
-            r['tx'] = CTransaction.deserialize(unhexlify(r['hex']))
+            r['tx'] = CTransaction.deserialize(unhexlify_str(r['hex']))
             del r['hex']
             del r['txid']
             del r['version']
@@ -565,7 +592,7 @@ def getrawtransaction(self, txid, verbose=False):
             del r['vout']
             r['blockhash'] = lx(r['blockhash']) if 'blockhash' in r else None
         else:
-            r = CTransaction.deserialize(unhexlify(r))
+            r = CTransaction.deserialize(unhexlify_str(r))
 
         return r
 
@@ -613,7 +640,7 @@ def gettxout(self, outpoint, includemempool=True):
             raise IndexError('%s.gettxout(): unspent txout %r not found' % (self.__class__.__name__, outpoint))
 
         r['txout'] = CTxOut(int(r['value'] * COIN),
-                            CScript(unhexlify(r['scriptPubKey']['hex'])))
+                            CScript(unhexlify_str(r['scriptPubKey']['hex'])))
         del r['value']
         del r['scriptPubKey']
         r['bestblock'] = lx(r['bestblock'])
@@ -653,7 +680,7 @@ def listunspent(self, minconf=0, maxconf=9999999, addrs=None):
                 unspent['address'] = CBitcoinAddress(unspent['address'])
             except KeyError:
                 pass
-            unspent['scriptPubKey'] = CScript(unhexlify(unspent['scriptPubKey']))
+            unspent['scriptPubKey'] = CScript(unhexlify_str(unspent['scriptPubKey']))
             unspent['amount'] = int(unspent['amount'] * COIN)
             r2.append(unspent)
         return r2
@@ -669,7 +696,7 @@ def sendrawtransaction(self, tx, allowhighfees=False):
 
         allowhighfees - Allow even if fees are unreasonably high.
         """
-        hextx = hexlify(tx.serialize())
+        hextx = hexlify_str(tx.serialize())
         r = None
         if allowhighfees:
             r = self._call('sendrawtransaction', hextx, True)
@@ -699,9 +726,9 @@ def signrawtransaction(self, tx, *args):
 
         FIXME: implement options
         """
-        hextx = hexlify(tx.serialize())
+        hextx = hexlify_str(tx.serialize())
         r = self._call('signrawtransaction', hextx, *args)
-        r['tx'] = CTransaction.deserialize(unhexlify(r['hex']))
+        r['tx'] = CTransaction.deserialize(unhexlify_str(r['hex']))
         del r['hex']
         return r
 
@@ -711,9 +738,9 @@ def signrawtransactionwithwallet(self, tx, *args):
 
         FIXME: implement options
         """
-        hextx = hexlify(tx.serialize())
+        hextx = hexlify_str(tx.serialize())
         r = self._call('signrawtransactionwithwallet', hextx, *args)
-        r['tx'] = CTransaction.deserialize(unhexlify(r['hex']))
+        r['tx'] = CTransaction.deserialize(unhexlify_str(r['hex']))
         del r['hex']
         return r
 
@@ -723,7 +750,7 @@ def submitblock(self, block, params=None):
         params is optional and is currently ignored by bitcoind. See
         https://en.bitcoin.it/wiki/BIP_0022 for full specification.
         """
-        hexblock = hexlify(block.serialize())
+        hexblock = hexlify_str(block.serialize())
         if params is not None:
             return self._call('submitblock', hexblock, params)
         else:
@@ -735,7 +762,7 @@ def validateaddress(self, address):
         if r['isvalid']:
             r['address'] = CBitcoinAddress(r['address'])
         if 'pubkey' in r:
-            r['pubkey'] = unhexlify(r['pubkey'])
+            r['pubkey'] = unhexlify_str(r['pubkey'])
         return r
 
     def unlockwallet(self, password, timeout=60):