tronpytool.common.encoding API documentation

# Module `tronpytool.common.encoding`

Expand source code

    import json
    import re
    from typing import Union

    from eth_account.datastructures import AttributeDict
    from eth_utils import (
        hexstr_if_str,
        to_hex,
        big_endian_to_int,
        int_to_big_endian
    )
    from hexbytes import HexBytes
    from trx_utils import (
        remove_0x_prefix,
        encode_hex,
        add_0x_prefix,
        decode_hex,
        is_boolean,
        is_integer,
        is_list_like,
        is_bytes
    )

    from tronpytool.common.abi import (
        size_of_type,
        sub_type_of_array_type,
        is_array_type,
        is_bool_type,
        is_uint_type,
        is_int_type,
        is_address_type,
        is_bytes_type,
        is_string_type
    )
    from tronpytool.common.toolz import (
        curry
    )
    from tronpytool.common.validation import assert_one_val
    from tronpytool.common.validation import (
        validate_abi_type,
        validate_abi_value
    )

    def hex_encode_abi_type(abi_type, value, force_size=None):
        """
        Encodes value into a hex string in format of abi_type
        """
        validate_abi_type(abi_type)
        validate_abi_value(abi_type, value)

        data_size = force_size or size_of_type(abi_type)
        if is_array_type(abi_type):
            sub_type = sub_type_of_array_type(abi_type)
            return "".join([remove_0x_prefix(hex_encode_abi_type(sub_type, v, 256)) for v in value])
        elif is_bool_type(abi_type):
            return to_hex_with_size(value, data_size)
        elif is_uint_type(abi_type):
            return to_hex_with_size(value, data_size)
        elif is_int_type(abi_type):
            return to_hex_twos_compliment(value, data_size)
        elif is_address_type(abi_type):
            return pad_hex(value, data_size)
        elif is_bytes_type(abi_type):
            if is_bytes(value):
                return encode_hex(value)
            else:
                return value
        elif is_string_type(abi_type):
            return to_hex(text=value)
        else:
            raise ValueError(
                "Unsupported ABI type: {0}".format(abi_type)
            )

    def to_hex_twos_compliment(value, bit_size):
        """
        Converts integer value to twos compliment hex representation with given bit_size
        """
        if value >= 0:
            return to_hex_with_size(value, bit_size)

        value = (1 << bit_size) + value
        hex_value = hex(value)
        hex_value = hex_value.rstrip("L")
        return hex_value

    def to_hex_with_size(value, bit_size):
        """Converts a value to hex with given bit_size:"""
        return pad_hex(to_hex(value), bit_size)

    def pad_hex(value, bit_size):
        """Pads a hex string up to the given bit_size"""
        value = remove_0x_prefix(value)
        return add_0x_prefix(value.zfill(int(bit_size / 4)))

    def trim_hex(hexstr):
        if hexstr.startswith('0x0'):
            hexstr = re.sub('^0x0+', '0x', hexstr)
            if hexstr == '0x':
                hexstr = '0x0'
        return hexstr

    def to_int(value=None, hexstr=None, text=None):
        """Converts value to it's integer representation.

        Values are converted this way:

         * value:
           * bytes: big-endian integer
           * bool: True => 1, False => 0
         * hexstr: interpret hex as integer
         * text: interpret as string of digits, like '12' => 12
        """
        assert_one_val(value, hexstr=hexstr, text=text)

        if hexstr is not None:
            return int(hexstr, 16)
        elif text is not None:
            return int(text)
        elif isinstance(value, bytes):
            return big_endian_to_int(value)
        elif isinstance(value, str):
            raise TypeError("Pass in strings with keyword hexstr or text")
        else:
            return int(value)

    @curry
    def text_if_str(to_type, text_or_primitive):
        """Convert to a type, assuming that strings can be only unicode text (not a hexstr)"""
        if isinstance(text_or_primitive, str):
            (primitive, text) = (None, text_or_primitive)
        else:
            (primitive, text) = (text_or_primitive, None)
        return to_type(primitive, text=text)

    def to_text(primitive=None, hexstr=None, text=None):
        assert_one_val(primitive, hexstr=hexstr, text=text)

        if hexstr is not None:
            return to_bytes(hexstr=hexstr).decode('utf-8')
        elif text is not None:
            return text
        elif isinstance(primitive, str):
            return to_text(hexstr=primitive)
        elif isinstance(primitive, bytes):
            return primitive.decode('utf-8')
        elif is_integer(primitive):
            byte_encoding = int_to_big_endian(primitive)
            return to_text(byte_encoding)
        raise TypeError("Expected an int, bytes or hexstr.")

    def to_bytes(primitive=None, hexstr=None, text=None):
        assert_one_val(primitive, hexstr=hexstr, text=text)

        if is_boolean(primitive):
            return b'\x01' if primitive else b'\x00'
        elif isinstance(primitive, bytes):
            return primitive
        elif is_integer(primitive):
            return to_bytes(hexstr=to_hex(primitive))
        elif hexstr is not None:
            if len(hexstr) % 2:
                hexstr = '0x0' + remove_0x_prefix(hexstr)
            return decode_hex(hexstr)
        elif text is not None:
            return text.encode('utf-8')
        raise TypeError("expected an int in first arg, or keyword of hexstr or text")

    def to_4byte_hex(hex_or_str_or_bytes: Union[int, str, bytes]) -> str:
        size_of_4bytes = 4 * 8
        byte_str = hexstr_if_str(to_bytes, hex_or_str_or_bytes)
        if len(byte_str) > 4:
            raise ValueError(
                'expected value of size 4 bytes. Got: %d bytes' % len(byte_str)
            )
        hex_str = encode_hex(byte_str)
        return pad_hex(hex_str, size_of_4bytes)

    class FriendlyJsonSerialize:
        """
        Friendly JSON serializer & deserializer
        When encoding or decoding fails, this class collects
        information on which fields failed, to show more
        helpful information in the raised error messages.
        """

        def _json_mapping_errors(self, mapping):
            for key, val in mapping.items():
                try:
                    self._friendly_json_encode(val)
                except TypeError as exc:
                    yield "%r: because (%s)" % (key, exc)

        def _json_list_errors(self, iterable):
            for index, element in enumerate(iterable):
                try:
                    self._friendly_json_encode(element)
                except TypeError as exc:
                    yield "%d: because (%s)" % (index, exc)

        def _friendly_json_encode(self, obj, cls=None):
            try:
                encoded = json.dumps(obj, cls=cls)
                return encoded
            except TypeError as full_exception:
                if hasattr(obj, 'items'):
                    item_errors = '; '.join(self._json_mapping_errors(obj))
                    raise TypeError("dict had unencodable value at keys: {{{}}}".format(item_errors))
                elif is_list_like(obj):
                    element_errors = '; '.join(self._json_list_errors(obj))
                    raise TypeError("list had unencodable value at index: [{}]".format(element_errors))
                else:
                    raise full_exception

        @staticmethod
        def json_decode(json_str):
            try:
                decoded = json.loads(json_str)
                return decoded
            except json.decoder.JSONDecodeError as exc:
                err_msg = 'Could not decode {} because of {}.'.format(repr(json_str), exc)
                # Calling code may rely on catching JSONDecodeError to recognize bad json
                # so we have to re-raise the same type.
                raise json.decoder.JSONDecodeError(err_msg, exc.doc, exc.pos)

        def json_encode(self, obj, cls=None):
            try:
                return self._friendly_json_encode(obj, cls=cls)
            except TypeError as exc:
                raise TypeError("Could not encode to JSON: {}".format(exc))

    class TronJsonEncoder(json.JSONEncoder):
        def default(self, obj):
            if isinstance(obj, AttributeDict):
                return {k: v for k, v in obj.items()}
            if isinstance(obj, HexBytes):
                return obj.hex()
            return json.JSONEncoder.default(self, obj)

    def to_json(obj: object) -> object:
        """Convert a complex object (like a transaction object) to a JSON string"""
        return FriendlyJsonSerialize().json_encode(obj, cls=TronJsonEncoder)

## Functions

`def hex_encode_abi_type(abi_type, value, force_size=None)`

  Encodes value into a hex string in format of abi_type

  Expand source code

      def hex_encode_abi_type(abi_type, value, force_size=None):
          """
          Encodes value into a hex string in format of abi_type
          """
          validate_abi_type(abi_type)
          validate_abi_value(abi_type, value)

          data_size = force_size or size_of_type(abi_type)
          if is_array_type(abi_type):
              sub_type = sub_type_of_array_type(abi_type)
              return "".join([remove_0x_prefix(hex_encode_abi_type(sub_type, v, 256)) for v in value])
          elif is_bool_type(abi_type):
              return to_hex_with_size(value, data_size)
          elif is_uint_type(abi_type):
              return to_hex_with_size(value, data_size)
          elif is_int_type(abi_type):
              return to_hex_twos_compliment(value, data_size)
          elif is_address_type(abi_type):
              return pad_hex(value, data_size)
          elif is_bytes_type(abi_type):
              if is_bytes(value):
                  return encode_hex(value)
              else:
                  return value
          elif is_string_type(abi_type):
              return to_hex(text=value)
          else:
              raise ValueError(
                  "Unsupported ABI type: {0}".format(abi_type)
              )

`def pad_hex(value, bit_size)`

  Pads a hex string up to the given bit_size

  Expand source code

      def pad_hex(value, bit_size):
          """Pads a hex string up to the given bit_size"""
          value = remove_0x_prefix(value)
          return add_0x_prefix(value.zfill(int(bit_size / 4)))

`def text_if_str(to_type='__no__default__', text_or_primitive='__no__default__')`

  Convert to a type, assuming that strings can be only unicode text (not a hexstr)

`def to_4byte_hex(hex_or_str_or_bytes: Union[int, str, bytes]) ‑> str`
  Expand source code

      def to_4byte_hex(hex_or_str_or_bytes: Union[int, str, bytes]) -> str:
          size_of_4bytes = 4 * 8
          byte_str = hexstr_if_str(to_bytes, hex_or_str_or_bytes)
          if len(byte_str) > 4:
              raise ValueError(
                  'expected value of size 4 bytes. Got: %d bytes' % len(byte_str)
              )
          hex_str = encode_hex(byte_str)
          return pad_hex(hex_str, size_of_4bytes)

`def to_bytes(primitive=None, hexstr=None, text=None)`
  Expand source code

      def to_bytes(primitive=None, hexstr=None, text=None):
          assert_one_val(primitive, hexstr=hexstr, text=text)

          if is_boolean(primitive):
              return b'\x01' if primitive else b'\x00'
          elif isinstance(primitive, bytes):
              return primitive
          elif is_integer(primitive):
              return to_bytes(hexstr=to_hex(primitive))
          elif hexstr is not None:
              if len(hexstr) % 2:
                  hexstr = '0x0' + remove_0x_prefix(hexstr)
              return decode_hex(hexstr)
          elif text is not None:
              return text.encode('utf-8')
          raise TypeError("expected an int in first arg, or keyword of hexstr or text")

`def to_hex_twos_compliment(value, bit_size)`

  Converts integer value to twos compliment hex representation with given bit_size

  Expand source code

      def to_hex_twos_compliment(value, bit_size):
          """
          Converts integer value to twos compliment hex representation with given bit_size
          """
          if value >= 0:
              return to_hex_with_size(value, bit_size)

          value = (1 << bit_size) + value
          hex_value = hex(value)
          hex_value = hex_value.rstrip("L")
          return hex_value

`def to_hex_with_size(value, bit_size)`

  Converts a value to hex with given bit_size:

  Expand source code

      def to_hex_with_size(value, bit_size):
          """Converts a value to hex with given bit_size:"""
          return pad_hex(to_hex(value), bit_size)

`def to_int(value=None, hexstr=None, text=None)`

  Converts value to it's integer representation.

  Values are converted this way:

  - value:
  - bytes: big-endian integer
  - bool: True => 1, False => 0
  - hexstr: interpret hex as integer
  - text: interpret as string of digits, like '12' => 12
  Expand source code

      def to_int(value=None, hexstr=None, text=None):
          """Converts value to it's integer representation.

          Values are converted this way:

           * value:
             * bytes: big-endian integer
             * bool: True => 1, False => 0
           * hexstr: interpret hex as integer
           * text: interpret as string of digits, like '12' => 12
          """
          assert_one_val(value, hexstr=hexstr, text=text)

          if hexstr is not None:
              return int(hexstr, 16)
          elif text is not None:
              return int(text)
          elif isinstance(value, bytes):
              return big_endian_to_int(value)
          elif isinstance(value, str):
              raise TypeError("Pass in strings with keyword hexstr or text")
          else:
              return int(value)

`def to_json(obj: object) ‑> object`

  Convert a complex object (like a transaction object) to a JSON string

  Expand source code

      def to_json(obj: object) -> object:
          """Convert a complex object (like a transaction object) to a JSON string"""
          return FriendlyJsonSerialize().json_encode(obj, cls=TronJsonEncoder)

`def to_text(primitive=None, hexstr=None, text=None)`
  Expand source code

      def to_text(primitive=None, hexstr=None, text=None):
          assert_one_val(primitive, hexstr=hexstr, text=text)

          if hexstr is not None:
              return to_bytes(hexstr=hexstr).decode('utf-8')
          elif text is not None:
              return text
          elif isinstance(primitive, str):
              return to_text(hexstr=primitive)
          elif isinstance(primitive, bytes):
              return primitive.decode('utf-8')
          elif is_integer(primitive):
              byte_encoding = int_to_big_endian(primitive)
              return to_text(byte_encoding)
          raise TypeError("Expected an int, bytes or hexstr.")

`def trim_hex(hexstr)`
  Expand source code

      def trim_hex(hexstr):
          if hexstr.startswith('0x0'):
              hexstr = re.sub('^0x0+', '0x', hexstr)
              if hexstr == '0x':
                  hexstr = '0x0'
          return hexstr

## Classes

`class FriendlyJsonSerialize`

  Friendly JSON serializer & deserializer When encoding or decoding fails, this class collects information on which fields failed, to show more helpful information in the raised error messages.

  Expand source code

      class FriendlyJsonSerialize:
          """
          Friendly JSON serializer & deserializer
          When encoding or decoding fails, this class collects
          information on which fields failed, to show more
          helpful information in the raised error messages.
          """

          def _json_mapping_errors(self, mapping):
              for key, val in mapping.items():
                  try:
                      self._friendly_json_encode(val)
                  except TypeError as exc:
                      yield "%r: because (%s)" % (key, exc)

          def _json_list_errors(self, iterable):
              for index, element in enumerate(iterable):
                  try:
                      self._friendly_json_encode(element)
                  except TypeError as exc:
                      yield "%d: because (%s)" % (index, exc)

          def _friendly_json_encode(self, obj, cls=None):
              try:
                  encoded = json.dumps(obj, cls=cls)
                  return encoded
              except TypeError as full_exception:
                  if hasattr(obj, 'items'):
                      item_errors = '; '.join(self._json_mapping_errors(obj))
                      raise TypeError("dict had unencodable value at keys: {{{}}}".format(item_errors))
                  elif is_list_like(obj):
                      element_errors = '; '.join(self._json_list_errors(obj))
                      raise TypeError("list had unencodable value at index: [{}]".format(element_errors))
                  else:
                      raise full_exception

          @staticmethod
          def json_decode(json_str):
              try:
                  decoded = json.loads(json_str)
                  return decoded
              except json.decoder.JSONDecodeError as exc:
                  err_msg = 'Could not decode {} because of {}.'.format(repr(json_str), exc)
                  # Calling code may rely on catching JSONDecodeError to recognize bad json
                  # so we have to re-raise the same type.
                  raise json.decoder.JSONDecodeError(err_msg, exc.doc, exc.pos)

          def json_encode(self, obj, cls=None):
              try:
                  return self._friendly_json_encode(obj, cls=cls)
              except TypeError as exc:
                  raise TypeError("Could not encode to JSON: {}".format(exc))

  ### Static methods

  `def json_decode(json_str)`
    Expand source code

        @staticmethod
        def json_decode(json_str):
            try:
                decoded = json.loads(json_str)
                return decoded
            except json.decoder.JSONDecodeError as exc:
                err_msg = 'Could not decode {} because of {}.'.format(repr(json_str), exc)
                # Calling code may rely on catching JSONDecodeError to recognize bad json
                # so we have to re-raise the same type.
                raise json.decoder.JSONDecodeError(err_msg, exc.doc, exc.pos)

  ### Methods

  `def json_encode(self, obj, cls=None)`
    Expand source code

        def json_encode(self, obj, cls=None):
            try:
                return self._friendly_json_encode(obj, cls=cls)
            except TypeError as exc:
                raise TypeError("Could not encode to JSON: {}".format(exc))

`class TronJsonEncoder (*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)`

  Extensible JSON http://json.org encoder for Python data structures.

  Supports the following objects and types by default:

  +-------------------+---------------+ | Python | JSON | +===================+===============+ | dict | object | +-------------------+---------------+ | list, tuple | array | +-------------------+---------------+ | str | string | +-------------------+---------------+ | int, float | number | +-------------------+---------------+ | True | true | +-------------------+---------------+ | False | false | +-------------------+---------------+ | None | null | +-------------------+---------------+

  To extend this to recognize other objects, subclass and implement a `.default()` method with another method that returns a serializable object for `o` if possible, otherwise it should call the superclass implementation (to raise `TypeError`).

  Constructor for JSONEncoder, with sensible defaults.

  If skipkeys is false, then it is a TypeError to attempt encoding of keys that are not str, int, float or None. If skipkeys is True, such items are simply skipped.

  If ensure_ascii is true, the output is guaranteed to be str objects with all incoming non-ASCII characters escaped. If ensure_ascii is false, the output can contain non-ASCII characters.

  If check_circular is true, then lists, dicts, and custom encoded objects will be checked for circular references during encoding to prevent an infinite recursion (which would cause an OverflowError). Otherwise, no such check takes place.

  If allow_nan is true, then NaN, Infinity, and -Infinity will be encoded as such. This behavior is not JSON specification compliant, but is consistent with most JavaScript based encoders and decoders. Otherwise, it will be a ValueError to encode such floats.

  If sort_keys is true, then the output of dictionaries will be sorted by key; this is useful for regression tests to ensure that JSON serializations can be compared on a day-to-day basis.

  If indent is a non-negative integer, then JSON array elements and object members will be pretty-printed with that indent level. An indent level of 0 will only insert newlines. None is the most compact representation.

  If specified, separators should be an (item_separator, key_separator) tuple. The default is (', ', ': ') if indent is `None` and (',', ': ') otherwise. To get the most compact JSON representation, you should specify (',', ':') to eliminate whitespace.

  If specified, default is a function that gets called for objects that can't otherwise be serialized. It should return a JSON encodable version of the object or raise a `TypeError`.

  Expand source code

      class TronJsonEncoder(json.JSONEncoder):
          def default(self, obj):
              if isinstance(obj, AttributeDict):
                  return {k: v for k, v in obj.items()}
              if isinstance(obj, HexBytes):
                  return obj.hex()
              return json.JSONEncoder.default(self, obj)

  ### Ancestors

  - json.encoder.JSONEncoder

  ### Methods

  `def default(self, obj)`

    Implement this method in a subclass such that it returns a serializable object for `o`, or calls the base implementation (to raise a `TypeError`).

    For example, to support arbitrary iterators, you could implement default like this::

        def default(self, o):
            try:
                iterable = iter(o)
            except TypeError:
                pass
            else:
                return list(iterable)
            # Let the base class default method raise the TypeError
            return JSONEncoder.default(self, o)

    Expand source code

        def default(self, obj):
            if isinstance(obj, AttributeDict):
                return {k: v for k, v in obj.items()}
            if isinstance(obj, HexBytes):
                return obj.hex()
            return json.JSONEncoder.default(self, obj)