# Encoder class

class rapidjson.Encoder(skip_invalid_keys=False, ensure_ascii=True, write_mode=WM_COMPACT, indent=4, sort_keys=False, number_mode=None, datetime_mode=None, uuid_mode=None, bytes_mode=BM_UTF8, iterable_mode=IM_ANY_ITERABLE, mapping_mode=MM_ANY_MAPPING)

  Class-based `dumps()`-like functionality.

  Parameters:

    - skip_invalid_keys (bool) – whether invalid `dict` keys will be skipped

    - ensure_ascii (bool) – whether the output should contain only ASCII characters

    - write_mode (int) – enable particular pretty print behaviors

    - indent – either an integer, the indentation width, or a string, that will be used as line separator, when write_mode is not `WM_COMPACT`

    - sort_keys (bool) – whether dictionary keys should be sorted alphabetically

    - number_mode (int) – enable particular behaviors in handling numbers

    - datetime_mode (int) – how should datetime, time and date instances be handled

    - uuid_mode (int) – how should UUID instances be handled

    - bytes_mode (int) – how should bytes instances be handled

    - iterable_mode (int) – how should iterable values be handled

    - mapping_mode (int) – how should mapping values be handled

  Attributes

  bytes_mode
    Type:

      int

    How bytes values should be treated.

  datetime_mode
    Type:

      int

    Whether and how datetime values should be encoded.

  ensure_ascii
    Type:

      bool

    Whether the output should contain only ASCII characters.

  indent_char
    Type:

      str

    What will be used as end-of-line character.

  indent_count
    Type:

      int

    The indentation width.

  iterable_mode
    Type:

      int

    Whether iterables will be generically encoded as `JSON` arrays or not.

  mapping_mode
    Type:

      int

    Whether mappings will be generically encoded as `JSON` objects or not.

  number_mode
    Type:

      int

    The encoding behavior with regards to numeric values.

  skip_invalid_keys
    Type:

      bool

    Whether invalid keys shall be skipped.

    Note

    skip_invalid_keys is a backward compatible alias of new `MM_SKIP_NON_STRING_KEYS` mapping mode.

  sort_keys
    Type:

      bool

    Whether dictionary keys shall be sorted alphabetically.

    Note

    sort_keys is a backward compatible alias of new `MM_SORT_KEYS` mapping mode.

  uuid_mode
    Type:

      int

    Whether and how UUID values should be encoded

  write_mode
    Type:

      int

    Whether the output should be pretty printed or not.

  Methods

  __call__(obj, stream=None, *, chunk_size=65536)
    Parameters:

      - obj – the value to be encoded

      - stream – a file-like instance

      - chunk_size (int) – write the stream in chunks of this size at a time

    Returns:

      a string with the `JSON` encoded value, when stream is `None`

    When stream is specified, the encoded result will be written there, possibly in chunks of chunk_size bytes at a time, and the return value will be `None`.

  default(value)
    Parameters:

      value – the Python value to be encoded

    Returns:

      a JSON-serializable value

    If implemented, this method is called whenever the serialization machinery finds a Python object that it does not recognize: if possible, the method should returns a JSON encodable version of the value, otherwise raise a `TypeError`:

        >>> class Point:
        ...   def __init__(self, x, y):
        ...     self.x = x
        ...     self.y = y
        ...
        >>> point = Point(1,2)
        >>> Encoder()(point)
        Traceback (most recent call last):
          File "<stdin>", line 1, in <module>
        TypeError: <__main__.Point object at …> is not JSON serializable
        >>> class PointEncoder(Encoder):
        ...   def default(self, obj):
        ...     if isinstance(obj, Point):
        ...       return {'x': obj.x, 'y': obj.y}
        ...     else:
        ...       raise TypeError('%r is not JSON serializable' % obj)
        ...
        >>> pe = PointEncoder(sort_keys=True)
        >>> pe(point)
        '{"x":1,"y":2}'

    When you want to treat your `bytes` instances in a special way, you can use `BM_NONE` together with this method:

        >>> class HexifyBytes(Encoder):
        ...   def default(self, obj):
        ...     if isinstance(obj, bytes):
        ...       return obj.hex()
        ...     else:
        ...       return obj
        ...
        >>> small_numbers = bytes([1, 2, 3])
        >>> hb = HexifyBytes(bytes_mode=BM_NONE)
        >>> hb(small_numbers)
        '"010203"'

    Likewise, when you want full control on how an iterable such as a `tuple` should be encoded, you can use `IM_ONLY_LISTS` and implement a suitable `default()` method:

        >>> from time import localtime, struct_time
        >>> class ObjectifyStructTime(Encoder):
        ...   def default(self, obj):
        ...     if isinstance(obj, struct_time):
        ...       return {'__class__': 'time.struct_time', '__init__': list(obj)}
        ...     else:
        ...       raise ValueError('%r is not JSON serializable' % obj)
        ...
        >>> obst = ObjectifyStructTime(iterable_mode=IM_ONLY_LISTS)
        >>> obst(localtime())
        '[2020,11,28,19,55,40,5,333,0]'

    Similarly, when you want full control on how a mapping other than plain `dict` should be encoded, you can use `MM_ONLY_DICTS` and implement a `default()` method:

        >>> from collections import OrderedDict
        >>> class ObjectifyOrderedDict(Encoder):
        ...   def default(self, obj):
        ...     if isinstance(obj, OrderedDict):
        ...       return {'__class__': 'collections.OrderedDict',
        ...               '__init__': list(obj.items())}
        ...     else:
        ...       raise ValueError('%r is not JSON serializable' % obj)
        ...
        >>> ood = ObjectifyOrderedDict(mapping_mode=MM_ONLY_DICTS)
        >>> ood(OrderedDict((('a', 1), ('b', 2))))
        '{"__class__":"collections.OrderedDict","__init__":[["a",1],["b",2]]}'