hjson API documentation
Description: Hjson, the Human JSON. A configuration file format that caters to humans and helps reduce the errors...

Top

# hjson module

Hjson, the Human JSON. A configuration file format that caters to humans and helps reduce the errors they make.

For details and syntax see http://hjson.org.

Decoding Hjson::

    >>> import hjson
    >>> text = "{\n  foo: a\n  bar: 1\n}"
    >>> hjson.loads(text)
    OrderedDict([('foo', 'a'), ('bar', 1)])

Encoding Python object hierarchies::

    >>> import hjson
    >>> # hjson.dumps({'foo': 'text', 'bar': (1, 2)})
    >>> hjson.dumps(OrderedDict([('foo', 'text'), ('bar', (1, 2))]))
    '{\n  foo: text\n  bar:\n  [\n    1\n    2\n  ]\n}'

Encoding as JSON::

    Note that this is probably not as performant as the simplejson version.

    >>> import hjson
    >>> hjson.dumpsJSON(['foo', {'bar': ('baz', None, 1.0, 2)}])
    '["foo", {"bar": ["baz", null, 1.0, 2]}]'

Using hjson.tool from the shell to validate and pretty-print::

    $ echo '{"json":"obj"}' | python -m hjson.tool
    {
      json: obj
    }

    Other formats are -c for compact or -j for formatted JSON.

Show source ≡

    r"""Hjson, the Human JSON. A configuration file format that caters to
    humans and helps reduce the errors they make.

    For details and syntax see .

    Decoding Hjson::

        >>> import hjson
        >>> text = "{\n  foo: a\n  bar: 1\n}"
        >>> hjson.loads(text)
        OrderedDict([('foo', 'a'), ('bar', 1)])

    Encoding Python object hierarchies::

        >>> import hjson
        >>> # hjson.dumps({'foo': 'text', 'bar': (1, 2)})
        >>> hjson.dumps(OrderedDict([('foo', 'text'), ('bar', (1, 2))]))
        '{\n  foo: text\n  bar:\n  [\n    1\n    2\n  ]\n}'

    Encoding as JSON::

        Note that this is probably not as performant as the simplejson version.

        >>> import hjson
        >>> hjson.dumpsJSON(['foo', {'bar': ('baz', None, 1.0, 2)}])
        '["foo", {"bar": ["baz", null, 1.0, 2]}]'

    Using hjson.tool from the shell to validate and pretty-print::

        $ echo '{"json":"obj"}' | python -m hjson.tool
        {
          json: obj
        }

        Other formats are -c for compact or -j for formatted JSON.

    """
    from __future__ import absolute_import
    __version__ = '2.0.0'
    __all__ = [
        'dump', 'dumps', 'load', 'loads',
        'dumpJSON', 'dumpsJSON',
        'HjsonDecoder', 'HjsonDecodeError', 'HjsonEncoder', 'JSONEncoder',
        'OrderedDict', 'simple_first',
    ]

    # based on simplejson by
    # __author__ = 'Bob Ippolito '
    __author__ = 'Christian Zangl '

    from decimal import Decimal

    from .scanner import HjsonDecodeError
    from .decoder import HjsonDecoder
    from .encoderH import HjsonEncoder
    from .encoder import JSONEncoder
    def _import_OrderedDict():
        import collections
        try:
            return collections.OrderedDict
        except AttributeError:
            from . import ordered_dict
            return ordered_dict.OrderedDict
    OrderedDict = _import_OrderedDict()

    _default_decoder = HjsonDecoder(encoding=None, object_hook=None,
                                   object_pairs_hook=OrderedDict)

    def load(fp, encoding=None, cls=None, object_hook=None, parse_float=None,
            parse_int=None, object_pairs_hook=OrderedDict,
            use_decimal=False, namedtuple_as_object=True, tuple_as_array=True,
            **kw):
        """Deserialize ``fp`` (a ``.read()``-supporting file-like object containing
        a JSON document) to a Python object.

        *encoding* determines the encoding used to interpret any
        :class:`str` objects decoded by this instance (``'utf-8'`` by
        default).  It has no effect when decoding :class:`unicode` objects.

        Note that currently only encodings that are a superset of ASCII work,
        strings of other encodings should be passed in as :class:`unicode`.

        *object_hook*, if specified, will be called with the result of every
        JSON object decoded and its return value will be used in place of the
        given :class:`dict`.  This can be used to provide custom
        deserializations (e.g. to support JSON-RPC class hinting).

        *object_pairs_hook* is an optional function that will be called with
        the result of any object literal decode with an ordered list of pairs.
        The return value of *object_pairs_hook* will be used instead of the
        :class:`dict`.  This feature can be used to implement custom decoders
        that rely on the order that the key and value pairs are decoded (for
        example, :func:`collections.OrderedDict` will remember the order of
        insertion). If *object_hook* is also defined, the *object_pairs_hook*
        takes priority.

        *parse_float*, if specified, will be called with the string of every
        JSON float to be decoded.  By default, this is equivalent to
        ``float(num_str)``. This can be used to use another datatype or parser
        for JSON floats (e.g. :class:`decimal.Decimal`).

        *parse_int*, if specified, will be called with the string of every
        JSON int to be decoded.  By default, this is equivalent to
        ``int(num_str)``.  This can be used to use another datatype or parser
        for JSON integers (e.g. :class:`float`).

        If *use_decimal* is true (default: ``False``) then it implies
        parse_float=decimal.Decimal for parity with ``dump``.

        To use a custom ``HjsonDecoder`` subclass, specify it with the ``cls``
        kwarg. NOTE: You should use *object_hook* or *object_pairs_hook* instead
        of subclassing whenever possible.

        """
        return loads(fp.read(),
            encoding=encoding, cls=cls, object_hook=object_hook,
            parse_float=parse_float, parse_int=parse_int,
            object_pairs_hook=object_pairs_hook,
            use_decimal=use_decimal, **kw)

    def loads(s, encoding=None, cls=None, object_hook=None, parse_float=None,
            parse_int=None, object_pairs_hook=None,
            use_decimal=False, **kw):
        """Deserialize ``s`` (a ``str`` or ``unicode`` instance containing a JSON
        document) to a Python object.

        *encoding* determines the encoding used to interpret any
        :class:`str` objects decoded by this instance (``'utf-8'`` by
        default).  It has no effect when decoding :class:`unicode` objects.

        Note that currently only encodings that are a superset of ASCII work,
        strings of other encodings should be passed in as :class:`unicode`.

        *object_hook*, if specified, will be called with the result of every
        JSON object decoded and its return value will be used in place of the
        given :class:`dict`.  This can be used to provide custom
        deserializations (e.g. to support JSON-RPC class hinting).

        *object_pairs_hook* is an optional function that will be called with
        the result of any object literal decode with an ordered list of pairs.
        The return value of *object_pairs_hook* will be used instead of the
        :class:`dict`.  This feature can be used to implement custom decoders
        that rely on the order that the key and value pairs are decoded (for
        example, :func:`collections.OrderedDict` will remember the order of
        insertion). If *object_hook* is also defined, the *object_pairs_hook*
        takes priority.

        *parse_float*, if specified, will be called with the string of every
        JSON float to be decoded.  By default, this is equivalent to
        ``float(num_str)``. This can be used to use another datatype or parser
        for JSON floats (e.g. :class:`decimal.Decimal`).

        *parse_int*, if specified, will be called with the string of every
        JSON int to be decoded.  By default, this is equivalent to
        ``int(num_str)``.  This can be used to use another datatype or parser
        for JSON integers (e.g. :class:`float`).

        If *use_decimal* is true (default: ``False``) then it implies
        parse_float=decimal.Decimal for parity with ``dump``.

        To use a custom ``HjsonDecoder`` subclass, specify it with the ``cls``
        kwarg. NOTE: You should use *object_hook* or *object_pairs_hook* instead
        of subclassing whenever possible.

        """
        if (cls is None and encoding is None and object_hook is None and
                parse_int is None and parse_float is None and
                object_pairs_hook is None
                and not use_decimal and not kw):
            return _default_decoder.decode(s)
        if cls is None:
            cls = HjsonDecoder
        if object_hook is not None:
            kw['object_hook'] = object_hook
        if object_pairs_hook is not None:
            kw['object_pairs_hook'] = object_pairs_hook
        if parse_float is not None:
            kw['parse_float'] = parse_float
        if parse_int is not None:
            kw['parse_int'] = parse_int
        if use_decimal:
            if parse_float is not None:
                raise TypeError("use_decimal=True implies parse_float=Decimal")
            kw['parse_float'] = Decimal
        return cls(encoding=encoding, **kw).decode(s)

    _default_hjson_encoder = HjsonEncoder(
        skipkeys=False,
        ensure_ascii=True,
        check_circular=True,
        indent=None,
        encoding='utf-8',
        default=None,
        use_decimal=True,
        namedtuple_as_object=True,
        tuple_as_array=True,
        bigint_as_string=False,
        item_sort_key=None,
        for_json=False,
        int_as_string_bitcount=None,
    )

    def dump(obj, fp, skipkeys=False, ensure_ascii=True, check_circular=True,
             cls=None, indent=None,
             encoding='utf-8', default=None, use_decimal=True,
             namedtuple_as_object=True, tuple_as_array=True,
             bigint_as_string=False, sort_keys=False, item_sort_key=None,
             for_json=False, int_as_string_bitcount=None, **kw):
        """Serialize ``obj`` as a JSON formatted stream to ``fp`` (a
        ``.write()``-supporting file-like object).

        If *skipkeys* is true then ``dict`` keys that are not basic types
        (``str``, ``unicode``, ``int``, ``long``, ``float``, ``bool``, ``None``)
        will be skipped instead of raising a ``TypeError``.

        If *ensure_ascii* is false, then the some chunks written to ``fp``
        may be ``unicode`` instances, subject to normal Python ``str`` to
        ``unicode`` coercion rules. Unless ``fp.write()`` explicitly
        understands ``unicode`` (as in ``codecs.getwriter()``) this is likely
        to cause an error.

        If *check_circular* is false, then the circular reference check
        for container types will be skipped and a circular reference will
        result in an ``OverflowError`` (or worse).

        If *indent* is a string, then JSON array elements and object members
        will be pretty-printed with a newline followed by that string repeated
        for each level of nesting. ``None`` (the default) selects the most compact
        representation without any newlines. For backwards compatibility with
        versions of hjson earlier than 2.1.0, an integer is also accepted
        and is converted to a string with that many spaces.

        *encoding* is the character encoding for str instances, default is UTF-8.

        *default(obj)* is a function that should return a serializable version
        of obj or raise ``TypeError``. The default simply raises ``TypeError``.

        If *use_decimal* is true (default: ``True``) then decimal.Decimal
        will be natively serialized to JSON with full precision.

        If *namedtuple_as_object* is true (default: ``True``),
        :class:`tuple` subclasses with ``_asdict()`` methods will be encoded
        as JSON objects.

        If *tuple_as_array* is true (default: ``True``),
        :class:`tuple` (and subclasses) will be encoded as JSON arrays.

        If *bigint_as_string* is true (default: ``False``), ints 2**53 and higher
        or lower than -2**53 will be encoded as strings. This is to avoid the
        rounding that happens in Javascript otherwise. Note that this is still a
        lossy operation that will not round-trip correctly and should be used
        sparingly.

        If *int_as_string_bitcount* is a positive number (n), then int of size
        greater than or equal to 2**n or lower than or equal to -2**n will be
        encoded as strings.

        If specified, *item_sort_key* is a callable used to sort the items in
        each dictionary. This is useful if you want to sort items other than
        in alphabetical order by key. This option takes precedence over
        *sort_keys*.

        If *sort_keys* is true (default: ``False``), the output of dictionaries
        will be sorted by item.

        If *for_json* is true (default: ``False``), objects with a ``for_json()``
        method will use the return value of that method for encoding as JSON
        instead of the object.

        To use a custom ``HjsonEncoder`` subclass (e.g. one that overrides the
        ``.default()`` method to serialize additional types), specify it with
        the ``cls`` kwarg. NOTE: You should use *default* or *for_json* instead
        of subclassing whenever possible.

        """
        # cached encoder
        if (not skipkeys and ensure_ascii and
            check_circular and
            cls is None and indent is None and
            encoding == 'utf-8' and default is None and use_decimal
            and namedtuple_as_object and tuple_as_array
            and not bigint_as_string and not sort_keys
            and not item_sort_key and not for_json
            and int_as_string_bitcount is None
            and not kw
        ):
            iterable = _default_hjson_encoder.iterencode(obj)
        else:
            if cls is None:
                cls = HjsonEncoder
            iterable = cls(skipkeys=skipkeys, ensure_ascii=ensure_ascii,
                check_circular=check_circular, indent=indent,
                encoding=encoding,
                default=default, use_decimal=use_decimal,
                namedtuple_as_object=namedtuple_as_object,
                tuple_as_array=tuple_as_array,
                bigint_as_string=bigint_as_string,
                sort_keys=sort_keys,
                item_sort_key=item_sort_key,
                for_json=for_json,
                int_as_string_bitcount=int_as_string_bitcount,
                **kw).iterencode(obj)
        # could accelerate with writelines in some versions of Python, at
        # a debuggability cost
        for chunk in iterable:
            fp.write(chunk)

    def dumps(obj, skipkeys=False, ensure_ascii=True, check_circular=True,
              cls=None, indent=None,
              encoding='utf-8', default=None, use_decimal=True,
              namedtuple_as_object=True, tuple_as_array=True,
              bigint_as_string=False, sort_keys=False, item_sort_key=None,
              for_json=False, int_as_string_bitcount=None, **kw):
        """Serialize ``obj`` to a JSON formatted ``str``.

        If ``skipkeys`` is false then ``dict`` keys that are not basic types
        (``str``, ``unicode``, ``int``, ``long``, ``float``, ``bool``, ``None``)
        will be skipped instead of raising a ``TypeError``.

        If ``ensure_ascii`` is false, then the return value will be a
        ``unicode`` instance subject to normal Python ``str`` to ``unicode``
        coercion rules instead of being escaped to an ASCII ``str``.

        If ``check_circular`` is false, then the circular reference check
        for container types will be skipped and a circular reference will
        result in an ``OverflowError`` (or worse).

        If ``indent`` is a string, then JSON array elements and object members
        will be pretty-printed with a newline followed by that string repeated
        for each level of nesting. ``None`` (the default) selects the most compact
        representation without any newlines. For backwards compatibility with
        versions of hjson earlier than 2.1.0, an integer is also accepted
        and is converted to a string with that many spaces.

        ``encoding`` is the character encoding for str instances, default is UTF-8.

        ``default(obj)`` is a function that should return a serializable version
        of obj or raise TypeError. The default simply raises TypeError.

        If *use_decimal* is true (default: ``True``) then decimal.Decimal
        will be natively serialized to JSON with full precision.

        If *namedtuple_as_object* is true (default: ``True``),
        :class:`tuple` subclasses with ``_asdict()`` methods will be encoded
        as JSON objects.

        If *tuple_as_array* is true (default: ``True``),
        :class:`tuple` (and subclasses) will be encoded as JSON arrays.

        If *bigint_as_string* is true (not the default), ints 2**53 and higher
        or lower than -2**53 will be encoded as strings. This is to avoid the
        rounding that happens in Javascript otherwise.

        If *int_as_string_bitcount* is a positive number (n), then int of size
        greater than or equal to 2**n or lower than or equal to -2**n will be
        encoded as strings.

        If specified, *item_sort_key* is a callable used to sort the items in
        each dictionary. This is useful if you want to sort items other than
        in alphabetical order by key. This option takes precendence over
        *sort_keys*.

        If *sort_keys* is true (default: ``False``), the output of dictionaries
        will be sorted by item.

        If *for_json* is true (default: ``False``), objects with a ``for_json()``
        method will use the return value of that method for encoding as JSON
        instead of the object.

        To use a custom ``HjsonEncoder`` subclass (e.g. one that overrides the
        ``.default()`` method to serialize additional types), specify it with
        the ``cls`` kwarg. NOTE: You should use *default* instead of subclassing
        whenever possible.

        """
        # cached encoder
        if (
            not skipkeys and ensure_ascii and
            check_circular and
            cls is None and indent is None and
            encoding == 'utf-8' and default is None and use_decimal
            and namedtuple_as_object and tuple_as_array
            and not bigint_as_string and not sort_keys
            and not item_sort_key and not for_json
            and int_as_string_bitcount is None
            and not kw
        ):
            return _default_hjson_encoder.encode(obj)
        if cls is None:
            cls = HjsonEncoder
        return cls(
            skipkeys=skipkeys, ensure_ascii=ensure_ascii,
            check_circular=check_circular, indent=indent,
            encoding=encoding, default=default,
            use_decimal=use_decimal,
            namedtuple_as_object=namedtuple_as_object,
            tuple_as_array=tuple_as_array,
            bigint_as_string=bigint_as_string,
            sort_keys=sort_keys,
            item_sort_key=item_sort_key,
            for_json=for_json,
            int_as_string_bitcount=int_as_string_bitcount,
            **kw).encode(obj)

    _default_json_encoder = JSONEncoder(
        skipkeys=False,
        ensure_ascii=True,
        check_circular=True,
        indent=None,
        separators=None,
        encoding='utf-8',
        default=None,
        use_decimal=True,
        namedtuple_as_object=True,
        tuple_as_array=True,
        bigint_as_string=False,
        item_sort_key=None,
        for_json=False,
        int_as_string_bitcount=None,
    )

    def dumpJSON(obj, fp, skipkeys=False, ensure_ascii=True, check_circular=True,
             cls=None, indent=None, separators=None,
             encoding='utf-8', default=None, use_decimal=True,
             namedtuple_as_object=True, tuple_as_array=True,
             bigint_as_string=False, sort_keys=False, item_sort_key=None,
             for_json=False, int_as_string_bitcount=None, **kw):
        """Serialize ``obj`` as a JSON formatted stream to ``fp`` (a
        ``.write()``-supporting file-like object).

        If *skipkeys* is true then ``dict`` keys that are not basic types
        (``str``, ``unicode``, ``int``, ``long``, ``float``, ``bool``, ``None``)
        will be skipped instead of raising a ``TypeError``.

        If *ensure_ascii* is false, then the some chunks written to ``fp``
        may be ``unicode`` instances, subject to normal Python ``str`` to
        ``unicode`` coercion rules. Unless ``fp.write()`` explicitly
        understands ``unicode`` (as in ``codecs.getwriter()``) this is likely
        to cause an error.

        If *check_circular* is false, then the circular reference check
        for container types will be skipped and a circular reference will
        result in an ``OverflowError`` (or worse).

        If *indent* is a string, then JSON array elements and object members
        will be pretty-printed with a newline followed by that string repeated
        for each level of nesting. ``None`` (the default) selects the most compact
        representation without any newlines. An integer is also accepted
        and is converted to a string with that many spaces.

        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.

        *encoding* is the character encoding for str instances, default is UTF-8.

        *default(obj)* is a function that should return a serializable version
        of obj or raise ``TypeError``. The default simply raises ``TypeError``.

        If *use_decimal* is true (default: ``True``) then decimal.Decimal
        will be natively serialized to JSON with full precision.

        If *namedtuple_as_object* is true (default: ``True``),
        :class:`tuple` subclasses with ``_asdict()`` methods will be encoded
        as JSON objects.

        If *tuple_as_array* is true (default: ``True``),
        :class:`tuple` (and subclasses) will be encoded as JSON arrays.

        If *bigint_as_string* is true (default: ``False``), ints 2**53 and higher
        or lower than -2**53 will be encoded as strings. This is to avoid the
        rounding that happens in Javascript otherwise. Note that this is still a
        lossy operation that will not round-trip correctly and should be used
        sparingly.

        If *int_as_string_bitcount* is a positive number (n), then int of size
        greater than or equal to 2**n or lower than or equal to -2**n will be
        encoded as strings.

        If specified, *item_sort_key* is a callable used to sort the items in
        each dictionary. This is useful if you want to sort items other than
        in alphabetical order by key. This option takes precedence over
        *sort_keys*.

        If *sort_keys* is true (default: ``False``), the output of dictionaries
        will be sorted by item.

        If *for_json* is true (default: ``False``), objects with a ``for_json()``
        method will use the return value of that method for encoding as JSON
        instead of the object.

        To use a custom ``JSONEncoder`` subclass (e.g. one that overrides the
        ``.default()`` method to serialize additional types), specify it with
        the ``cls`` kwarg. NOTE: You should use *default* or *for_json* instead
        of subclassing whenever possible.

        """
        # cached encoder
        if (not skipkeys and ensure_ascii and
            check_circular and
            cls is None and indent is None and separators is None and
            encoding == 'utf-8' and default is None and use_decimal
            and namedtuple_as_object and tuple_as_array
            and not bigint_as_string and not sort_keys
            and not item_sort_key and not for_json
            and int_as_string_bitcount is None
            and not kw
        ):
            iterable = _default_json_encoder.iterencode(obj)
        else:
            if cls is None:
                cls = JSONEncoder
            iterable = cls(skipkeys=skipkeys, ensure_ascii=ensure_ascii,
                check_circular=check_circular, indent=indent,
                separators=separators, encoding=encoding,
                default=default, use_decimal=use_decimal,
                namedtuple_as_object=namedtuple_as_object,
                tuple_as_array=tuple_as_array,
                bigint_as_string=bigint_as_string,
                sort_keys=sort_keys,
                item_sort_key=item_sort_key,
                for_json=for_json,
                int_as_string_bitcount=int_as_string_bitcount,
                **kw).iterencode(obj)
        # could accelerate with writelines in some versions of Python, at
        # a debuggability cost
        for chunk in iterable:
            fp.write(chunk)

    def dumpsJSON(obj, skipkeys=False, ensure_ascii=True, check_circular=True,
              cls=None, indent=None, separators=None,
              encoding='utf-8', default=None, use_decimal=True,
              namedtuple_as_object=True, tuple_as_array=True,
              bigint_as_string=False, sort_keys=False, item_sort_key=None,
              for_json=False, int_as_string_bitcount=None, **kw):
        """Serialize ``obj`` to a JSON formatted ``str``.

        If ``skipkeys`` is false then ``dict`` keys that are not basic types
        (``str``, ``unicode``, ``int``, ``long``, ``float``, ``bool``, ``None``)
        will be skipped instead of raising a ``TypeError``.

        If ``ensure_ascii`` is false, then the return value will be a
        ``unicode`` instance subject to normal Python ``str`` to ``unicode``
        coercion rules instead of being escaped to an ASCII ``str``.

        If ``check_circular`` is false, then the circular reference check
        for container types will be skipped and a circular reference will
        result in an ``OverflowError`` (or worse).

        If ``indent`` is a string, then JSON array elements and object members
        will be pretty-printed with a newline followed by that string repeated
        for each level of nesting. ``None`` (the default) selects the most compact
        representation without any newlines. An integer is also accepted
        and is converted to a string with that many spaces.

        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.

        ``encoding`` is the character encoding for str instances, default is UTF-8.

        ``default(obj)`` is a function that should return a serializable version
        of obj or raise TypeError. The default simply raises TypeError.

        If *use_decimal* is true (default: ``True``) then decimal.Decimal
        will be natively serialized to JSON with full precision.

        If *namedtuple_as_object* is true (default: ``True``),
        :class:`tuple` subclasses with ``_asdict()`` methods will be encoded
        as JSON objects.

        If *tuple_as_array* is true (default: ``True``),
        :class:`tuple` (and subclasses) will be encoded as JSON arrays.

        If *bigint_as_string* is true (not the default), ints 2**53 and higher
        or lower than -2**53 will be encoded as strings. This is to avoid the
        rounding that happens in Javascript otherwise.

        If *int_as_string_bitcount* is a positive number (n), then int of size
        greater than or equal to 2**n or lower than or equal to -2**n will be
        encoded as strings.

        If specified, *item_sort_key* is a callable used to sort the items in
        each dictionary. This is useful if you want to sort items other than
        in alphabetical order by key. This option takes precendence over
        *sort_keys*.

        If *sort_keys* is true (default: ``False``), the output of dictionaries
        will be sorted by item.

        If *for_json* is true (default: ``False``), objects with a ``for_json()``
        method will use the return value of that method for encoding as JSON
        instead of the object.

        To use a custom ``JSONEncoder`` subclass (e.g. one that overrides the
        ``.default()`` method to serialize additional types), specify it with
        the ``cls`` kwarg. NOTE: You should use *default* instead of subclassing
        whenever possible.

        """
        # cached encoder
        if (
            not skipkeys and ensure_ascii and
            check_circular and
            cls is None and indent is None and separators is None and
            encoding == 'utf-8' and default is None and use_decimal
            and namedtuple_as_object and tuple_as_array
            and not bigint_as_string and not sort_keys
            and not item_sort_key and not for_json
            and int_as_string_bitcount is None
            and not kw
        ):
            return _default_json_encoder.encode(obj)
        if cls is None:
            cls = JSONEncoder
        return cls(
            skipkeys=skipkeys, ensure_ascii=ensure_ascii,
            check_circular=check_circular, indent=indent,
            separators=separators, encoding=encoding, default=default,
            use_decimal=use_decimal,
            namedtuple_as_object=namedtuple_as_object,
            tuple_as_array=tuple_as_array,
            bigint_as_string=bigint_as_string,
            sort_keys=sort_keys,
            item_sort_key=item_sort_key,
            for_json=for_json,
            int_as_string_bitcount=int_as_string_bitcount,
            **kw).encode(obj)

    def simple_first(kv):
        """Helper function to pass to item_sort_key to sort simple
        elements to the top, then container elements.
        """
        return (isinstance(kv[1], (list, dict, tuple)), kv[0])

## Functions

def dump(

obj, fp, skipkeys=False, ensure_ascii=True, check_circular=True, cls=None, indent=None, encoding='utf-8', default=None, use_decimal=True, namedtuple_as_object=True, tuple_as_array=True, bigint_as_string=False, sort_keys=False, item_sort_key=None, for_json=False, int_as_string_bitcount=None, **kw)

Serialize `obj` as a JSON formatted stream to `fp` (a `.write()`-supporting file-like object).

If skipkeys is true then `dict` keys that are not basic types (`str`, `unicode`, `int`, `long`, `float`, `bool`, `None`) will be skipped instead of raising a `TypeError`.

If ensure_ascii is false, then the some chunks written to `fp` may be `unicode` instances, subject to normal Python `str` to `unicode` coercion rules. Unless `fp.write()` explicitly understands `unicode` (as in `codecs.getwriter()`) this is likely to cause an error.

If check_circular is false, then the circular reference check for container types will be skipped and a circular reference will result in an `OverflowError` (or worse).

If indent is a string, then JSON array elements and object members will be pretty-printed with a newline followed by that string repeated for each level of nesting. `None` (the default) selects the most compact representation without any newlines. For backwards compatibility with versions of hjson earlier than 2.1.0, an integer is also accepted and is converted to a string with that many spaces.

encoding is the character encoding for str instances, default is UTF-8.

default(obj) is a function that should return a serializable version of obj or raise `TypeError`. The default simply raises `TypeError`.

If use_decimal is true (default: `True`) then decimal.Decimal will be natively serialized to JSON with full precision.

If namedtuple_as_object is true (default: `True`), :class:`tuple` subclasses with `_asdict()` methods will be encoded as JSON objects.

If tuple_as_array is true (default: `True`), :class:`tuple` (and subclasses) will be encoded as JSON arrays.

If bigint_as_string is true (default: `False`), ints 253 and higher or lower than -253 will be encoded as strings. This is to avoid the rounding that happens in Javascript otherwise. Note that this is still a lossy operation that will not round-trip correctly and should be used sparingly.

If int_as_string_bitcount is a positive number (n), then int of size greater than or equal to 2n or lower than or equal to -2n will be encoded as strings.

If specified, item_sort_key is a callable used to sort the items in each dictionary. This is useful if you want to sort items other than in alphabetical order by key. This option takes precedence over sort_keys.

If sort_keys is true (default: `False`), the output of dictionaries will be sorted by item.

If for_json is true (default: `False`), objects with a `for_json()` method will use the return value of that method for encoding as JSON instead of the object.

To use a custom `HjsonEncoder` subclass (e.g. one that overrides the `.default()` method to serialize additional types), specify it with the `cls` kwarg. NOTE: You should use default or for_json instead of subclassing whenever possible.

Show source ≡

    def dump(obj, fp, skipkeys=False, ensure_ascii=True, check_circular=True,
             cls=None, indent=None,
             encoding='utf-8', default=None, use_decimal=True,
             namedtuple_as_object=True, tuple_as_array=True,
             bigint_as_string=False, sort_keys=False, item_sort_key=None,
             for_json=False, int_as_string_bitcount=None, **kw):
        """Serialize ``obj`` as a JSON formatted stream to ``fp`` (a
        ``.write()``-supporting file-like object).

        If *skipkeys* is true then ``dict`` keys that are not basic types
        (``str``, ``unicode``, ``int``, ``long``, ``float``, ``bool``, ``None``)
        will be skipped instead of raising a ``TypeError``.

        If *ensure_ascii* is false, then the some chunks written to ``fp``
        may be ``unicode`` instances, subject to normal Python ``str`` to
        ``unicode`` coercion rules. Unless ``fp.write()`` explicitly
        understands ``unicode`` (as in ``codecs.getwriter()``) this is likely
        to cause an error.

        If *check_circular* is false, then the circular reference check
        for container types will be skipped and a circular reference will
        result in an ``OverflowError`` (or worse).

        If *indent* is a string, then JSON array elements and object members
        will be pretty-printed with a newline followed by that string repeated
        for each level of nesting. ``None`` (the default) selects the most compact
        representation without any newlines. For backwards compatibility with
        versions of hjson earlier than 2.1.0, an integer is also accepted
        and is converted to a string with that many spaces.

        *encoding* is the character encoding for str instances, default is UTF-8.

        *default(obj)* is a function that should return a serializable version
        of obj or raise ``TypeError``. The default simply raises ``TypeError``.

        If *use_decimal* is true (default: ``True``) then decimal.Decimal
        will be natively serialized to JSON with full precision.

        If *namedtuple_as_object* is true (default: ``True``),
        :class:`tuple` subclasses with ``_asdict()`` methods will be encoded
        as JSON objects.

        If *tuple_as_array* is true (default: ``True``),
        :class:`tuple` (and subclasses) will be encoded as JSON arrays.

        If *bigint_as_string* is true (default: ``False``), ints 2**53 and higher
        or lower than -2**53 will be encoded as strings. This is to avoid the
        rounding that happens in Javascript otherwise. Note that this is still a
        lossy operation that will not round-trip correctly and should be used
        sparingly.

        If *int_as_string_bitcount* is a positive number (n), then int of size
        greater than or equal to 2**n or lower than or equal to -2**n will be
        encoded as strings.

        If specified, *item_sort_key* is a callable used to sort the items in
        each dictionary. This is useful if you want to sort items other than
        in alphabetical order by key. This option takes precedence over
        *sort_keys*.

        If *sort_keys* is true (default: ``False``), the output of dictionaries
        will be sorted by item.

        If *for_json* is true (default: ``False``), objects with a ``for_json()``
        method will use the return value of that method for encoding as JSON
        instead of the object.

        To use a custom ``HjsonEncoder`` subclass (e.g. one that overrides the
        ``.default()`` method to serialize additional types), specify it with
        the ``cls`` kwarg. NOTE: You should use *default* or *for_json* instead
        of subclassing whenever possible.

        """
        # cached encoder
        if (not skipkeys and ensure_ascii and
            check_circular and
            cls is None and indent is None and
            encoding == 'utf-8' and default is None and use_decimal
            and namedtuple_as_object and tuple_as_array
            and not bigint_as_string and not sort_keys
            and not item_sort_key and not for_json
            and int_as_string_bitcount is None
            and not kw
        ):
            iterable = _default_hjson_encoder.iterencode(obj)
        else:
            if cls is None:
                cls = HjsonEncoder
            iterable = cls(skipkeys=skipkeys, ensure_ascii=ensure_ascii,
                check_circular=check_circular, indent=indent,
                encoding=encoding,
                default=default, use_decimal=use_decimal,
                namedtuple_as_object=namedtuple_as_object,
                tuple_as_array=tuple_as_array,
                bigint_as_string=bigint_as_string,
                sort_keys=sort_keys,
                item_sort_key=item_sort_key,
                for_json=for_json,
                int_as_string_bitcount=int_as_string_bitcount,
                **kw).iterencode(obj)
        # could accelerate with writelines in some versions of Python, at
        # a debuggability cost
        for chunk in iterable:
            fp.write(chunk)

def dumpJSON(

obj, fp, skipkeys=False, ensure_ascii=True, check_circular=True, cls=None, indent=None, separators=None, encoding='utf-8', default=None, use_decimal=True, namedtuple_as_object=True, tuple_as_array=True, bigint_as_string=False, sort_keys=False, item_sort_key=None, for_json=False, int_as_string_bitcount=None, **kw)

Serialize `obj` as a JSON formatted stream to `fp` (a `.write()`-supporting file-like object).

If skipkeys is true then `dict` keys that are not basic types (`str`, `unicode`, `int`, `long`, `float`, `bool`, `None`) will be skipped instead of raising a `TypeError`.

If ensure_ascii is false, then the some chunks written to `fp` may be `unicode` instances, subject to normal Python `str` to `unicode` coercion rules. Unless `fp.write()` explicitly understands `unicode` (as in `codecs.getwriter()`) this is likely to cause an error.

If check_circular is false, then the circular reference check for container types will be skipped and a circular reference will result in an `OverflowError` (or worse).

If indent is a string, then JSON array elements and object members will be pretty-printed with a newline followed by that string repeated for each level of nesting. `None` (the default) selects the most compact representation without any newlines. An integer is also accepted and is converted to a string with that many spaces.

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.

encoding is the character encoding for str instances, default is UTF-8.

default(obj) is a function that should return a serializable version of obj or raise `TypeError`. The default simply raises `TypeError`.

If use_decimal is true (default: `True`) then decimal.Decimal will be natively serialized to JSON with full precision.

If namedtuple_as_object is true (default: `True`), :class:`tuple` subclasses with `_asdict()` methods will be encoded as JSON objects.

If tuple_as_array is true (default: `True`), :class:`tuple` (and subclasses) will be encoded as JSON arrays.

If bigint_as_string is true (default: `False`), ints 253 and higher or lower than -253 will be encoded as strings. This is to avoid the rounding that happens in Javascript otherwise. Note that this is still a lossy operation that will not round-trip correctly and should be used sparingly.

If int_as_string_bitcount is a positive number (n), then int of size greater than or equal to 2n or lower than or equal to -2n will be encoded as strings.

If specified, item_sort_key is a callable used to sort the items in each dictionary. This is useful if you want to sort items other than in alphabetical order by key. This option takes precedence over sort_keys.

If sort_keys is true (default: `False`), the output of dictionaries will be sorted by item.

If for_json is true (default: `False`), objects with a `for_json()` method will use the return value of that method for encoding as JSON instead of the object.

To use a custom `JSONEncoder` subclass (e.g. one that overrides the `.default()` method to serialize additional types), specify it with the `cls` kwarg. NOTE: You should use default or for_json instead of subclassing whenever possible.

Show source ≡

    def dumpJSON(obj, fp, skipkeys=False, ensure_ascii=True, check_circular=True,
             cls=None, indent=None, separators=None,
             encoding='utf-8', default=None, use_decimal=True,
             namedtuple_as_object=True, tuple_as_array=True,
             bigint_as_string=False, sort_keys=False, item_sort_key=None,
             for_json=False, int_as_string_bitcount=None, **kw):
        """Serialize ``obj`` as a JSON formatted stream to ``fp`` (a
        ``.write()``-supporting file-like object).

        If *skipkeys* is true then ``dict`` keys that are not basic types
        (``str``, ``unicode``, ``int``, ``long``, ``float``, ``bool``, ``None``)
        will be skipped instead of raising a ``TypeError``.

        If *ensure_ascii* is false, then the some chunks written to ``fp``
        may be ``unicode`` instances, subject to normal Python ``str`` to
        ``unicode`` coercion rules. Unless ``fp.write()`` explicitly
        understands ``unicode`` (as in ``codecs.getwriter()``) this is likely
        to cause an error.

        If *check_circular* is false, then the circular reference check
        for container types will be skipped and a circular reference will
        result in an ``OverflowError`` (or worse).

        If *indent* is a string, then JSON array elements and object members
        will be pretty-printed with a newline followed by that string repeated
        for each level of nesting. ``None`` (the default) selects the most compact
        representation without any newlines. An integer is also accepted
        and is converted to a string with that many spaces.

        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.

        *encoding* is the character encoding for str instances, default is UTF-8.

        *default(obj)* is a function that should return a serializable version
        of obj or raise ``TypeError``. The default simply raises ``TypeError``.

        If *use_decimal* is true (default: ``True``) then decimal.Decimal
        will be natively serialized to JSON with full precision.

        If *namedtuple_as_object* is true (default: ``True``),
        :class:`tuple` subclasses with ``_asdict()`` methods will be encoded
        as JSON objects.

        If *tuple_as_array* is true (default: ``True``),
        :class:`tuple` (and subclasses) will be encoded as JSON arrays.

        If *bigint_as_string* is true (default: ``False``), ints 2**53 and higher
        or lower than -2**53 will be encoded as strings. This is to avoid the
        rounding that happens in Javascript otherwise. Note that this is still a
        lossy operation that will not round-trip correctly and should be used
        sparingly.

        If *int_as_string_bitcount* is a positive number (n), then int of size
        greater than or equal to 2**n or lower than or equal to -2**n will be
        encoded as strings.

        If specified, *item_sort_key* is a callable used to sort the items in
        each dictionary. This is useful if you want to sort items other than
        in alphabetical order by key. This option takes precedence over
        *sort_keys*.

        If *sort_keys* is true (default: ``False``), the output of dictionaries
        will be sorted by item.

        If *for_json* is true (default: ``False``), objects with a ``for_json()``
        method will use the return value of that method for encoding as JSON
        instead of the object.

        To use a custom ``JSONEncoder`` subclass (e.g. one that overrides the
        ``.default()`` method to serialize additional types), specify it with
        the ``cls`` kwarg. NOTE: You should use *default* or *for_json* instead
        of subclassing whenever possible.

        """
        # cached encoder
        if (not skipkeys and ensure_ascii and
            check_circular and
            cls is None and indent is None and separators is None and
            encoding == 'utf-8' and default is None and use_decimal
            and namedtuple_as_object and tuple_as_array
            and not bigint_as_string and not sort_keys
            and not item_sort_key and not for_json
            and int_as_string_bitcount is None
            and not kw
        ):
            iterable = _default_json_encoder.iterencode(obj)
        else:
            if cls is None:
                cls = JSONEncoder
            iterable = cls(skipkeys=skipkeys, ensure_ascii=ensure_ascii,
                check_circular=check_circular, indent=indent,
                separators=separators, encoding=encoding,
                default=default, use_decimal=use_decimal,
                namedtuple_as_object=namedtuple_as_object,
                tuple_as_array=tuple_as_array,
                bigint_as_string=bigint_as_string,
                sort_keys=sort_keys,
                item_sort_key=item_sort_key,
                for_json=for_json,
                int_as_string_bitcount=int_as_string_bitcount,
                **kw).iterencode(obj)
        # could accelerate with writelines in some versions of Python, at
        # a debuggability cost
        for chunk in iterable:
            fp.write(chunk)

def dumps(

obj, skipkeys=False, ensure_ascii=True, check_circular=True, cls=None, indent=None, encoding='utf-8', default=None, use_decimal=True, namedtuple_as_object=True, tuple_as_array=True, bigint_as_string=False, sort_keys=False, item_sort_key=None, for_json=False, int_as_string_bitcount=None, **kw)

Serialize `obj` to a JSON formatted `str`.

If `skipkeys` is false then `dict` keys that are not basic types (`str`, `unicode`, `int`, `long`, `float`, `bool`, `None`) will be skipped instead of raising a `TypeError`.

If `ensure_ascii` is false, then the return value will be a `unicode` instance subject to normal Python `str` to `unicode` coercion rules instead of being escaped to an ASCII `str`.

If `check_circular` is false, then the circular reference check for container types will be skipped and a circular reference will result in an `OverflowError` (or worse).

If `indent` is a string, then JSON array elements and object members will be pretty-printed with a newline followed by that string repeated for each level of nesting. `None` (the default) selects the most compact representation without any newlines. For backwards compatibility with versions of hjson earlier than 2.1.0, an integer is also accepted and is converted to a string with that many spaces.

`encoding` is the character encoding for str instances, default is UTF-8.

`default(obj)` is a function that should return a serializable version of obj or raise TypeError. The default simply raises TypeError.

If use_decimal is true (default: `True`) then decimal.Decimal will be natively serialized to JSON with full precision.

If namedtuple_as_object is true (default: `True`), :class:`tuple` subclasses with `_asdict()` methods will be encoded as JSON objects.

If tuple_as_array is true (default: `True`), :class:`tuple` (and subclasses) will be encoded as JSON arrays.

If bigint_as_string is true (not the default), ints 253 and higher or lower than -253 will be encoded as strings. This is to avoid the rounding that happens in Javascript otherwise.

If int_as_string_bitcount is a positive number (n), then int of size greater than or equal to 2n or lower than or equal to -2n will be encoded as strings.

If specified, item_sort_key is a callable used to sort the items in each dictionary. This is useful if you want to sort items other than in alphabetical order by key. This option takes precendence over sort_keys.

If sort_keys is true (default: `False`), the output of dictionaries will be sorted by item.

If for_json is true (default: `False`), objects with a `for_json()` method will use the return value of that method for encoding as JSON instead of the object.

To use a custom `HjsonEncoder` subclass (e.g. one that overrides the `.default()` method to serialize additional types), specify it with the `cls` kwarg. NOTE: You should use default instead of subclassing whenever possible.

Show source ≡

    def dumps(obj, skipkeys=False, ensure_ascii=True, check_circular=True,
              cls=None, indent=None,
              encoding='utf-8', default=None, use_decimal=True,
              namedtuple_as_object=True, tuple_as_array=True,
              bigint_as_string=False, sort_keys=False, item_sort_key=None,
              for_json=False, int_as_string_bitcount=None, **kw):
        """Serialize ``obj`` to a JSON formatted ``str``.

        If ``skipkeys`` is false then ``dict`` keys that are not basic types
        (``str``, ``unicode``, ``int``, ``long``, ``float``, ``bool``, ``None``)
        will be skipped instead of raising a ``TypeError``.

        If ``ensure_ascii`` is false, then the return value will be a
        ``unicode`` instance subject to normal Python ``str`` to ``unicode``
        coercion rules instead of being escaped to an ASCII ``str``.

        If ``check_circular`` is false, then the circular reference check
        for container types will be skipped and a circular reference will
        result in an ``OverflowError`` (or worse).

        If ``indent`` is a string, then JSON array elements and object members
        will be pretty-printed with a newline followed by that string repeated
        for each level of nesting. ``None`` (the default) selects the most compact
        representation without any newlines. For backwards compatibility with
        versions of hjson earlier than 2.1.0, an integer is also accepted
        and is converted to a string with that many spaces.

        ``encoding`` is the character encoding for str instances, default is UTF-8.

        ``default(obj)`` is a function that should return a serializable version
        of obj or raise TypeError. The default simply raises TypeError.

        If *use_decimal* is true (default: ``True``) then decimal.Decimal
        will be natively serialized to JSON with full precision.

        If *namedtuple_as_object* is true (default: ``True``),
        :class:`tuple` subclasses with ``_asdict()`` methods will be encoded
        as JSON objects.

        If *tuple_as_array* is true (default: ``True``),
        :class:`tuple` (and subclasses) will be encoded as JSON arrays.

        If *bigint_as_string* is true (not the default), ints 2**53 and higher
        or lower than -2**53 will be encoded as strings. This is to avoid the
        rounding that happens in Javascript otherwise.

        If *int_as_string_bitcount* is a positive number (n), then int of size
        greater than or equal to 2**n or lower than or equal to -2**n will be
        encoded as strings.

        If specified, *item_sort_key* is a callable used to sort the items in
        each dictionary. This is useful if you want to sort items other than
        in alphabetical order by key. This option takes precendence over
        *sort_keys*.

        If *sort_keys* is true (default: ``False``), the output of dictionaries
        will be sorted by item.

        If *for_json* is true (default: ``False``), objects with a ``for_json()``
        method will use the return value of that method for encoding as JSON
        instead of the object.

        To use a custom ``HjsonEncoder`` subclass (e.g. one that overrides the
        ``.default()`` method to serialize additional types), specify it with
        the ``cls`` kwarg. NOTE: You should use *default* instead of subclassing
        whenever possible.

        """
        # cached encoder
        if (
            not skipkeys and ensure_ascii and
            check_circular and
            cls is None and indent is None and
            encoding == 'utf-8' and default is None and use_decimal
            and namedtuple_as_object and tuple_as_array
            and not bigint_as_string and not sort_keys
            and not item_sort_key and not for_json
            and int_as_string_bitcount is None
            and not kw
        ):
            return _default_hjson_encoder.encode(obj)
        if cls is None:
            cls = HjsonEncoder
        return cls(
            skipkeys=skipkeys, ensure_ascii=ensure_ascii,
            check_circular=check_circular, indent=indent,
            encoding=encoding, default=default,
            use_decimal=use_decimal,
            namedtuple_as_object=namedtuple_as_object,
            tuple_as_array=tuple_as_array,
            bigint_as_string=bigint_as_string,
            sort_keys=sort_keys,
            item_sort_key=item_sort_key,
            for_json=for_json,
            int_as_string_bitcount=int_as_string_bitcount,
            **kw).encode(obj)

def dumpsJSON(

obj, skipkeys=False, ensure_ascii=True, check_circular=True, cls=None, indent=None, separators=None, encoding='utf-8', default=None, use_decimal=True, namedtuple_as_object=True, tuple_as_array=True, bigint_as_string=False, sort_keys=False, item_sort_key=None, for_json=False, int_as_string_bitcount=None, **kw)

Serialize `obj` to a JSON formatted `str`.

If `skipkeys` is false then `dict` keys that are not basic types (`str`, `unicode`, `int`, `long`, `float`, `bool`, `None`) will be skipped instead of raising a `TypeError`.

If `ensure_ascii` is false, then the return value will be a `unicode` instance subject to normal Python `str` to `unicode` coercion rules instead of being escaped to an ASCII `str`.

If `check_circular` is false, then the circular reference check for container types will be skipped and a circular reference will result in an `OverflowError` (or worse).

If `indent` is a string, then JSON array elements and object members will be pretty-printed with a newline followed by that string repeated for each level of nesting. `None` (the default) selects the most compact representation without any newlines. An integer is also accepted and is converted to a string with that many spaces.

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.

`encoding` is the character encoding for str instances, default is UTF-8.

`default(obj)` is a function that should return a serializable version of obj or raise TypeError. The default simply raises TypeError.

If use_decimal is true (default: `True`) then decimal.Decimal will be natively serialized to JSON with full precision.

If namedtuple_as_object is true (default: `True`), :class:`tuple` subclasses with `_asdict()` methods will be encoded as JSON objects.

If tuple_as_array is true (default: `True`), :class:`tuple` (and subclasses) will be encoded as JSON arrays.

If bigint_as_string is true (not the default), ints 253 and higher or lower than -253 will be encoded as strings. This is to avoid the rounding that happens in Javascript otherwise.

If int_as_string_bitcount is a positive number (n), then int of size greater than or equal to 2n or lower than or equal to -2n will be encoded as strings.

If specified, item_sort_key is a callable used to sort the items in each dictionary. This is useful if you want to sort items other than in alphabetical order by key. This option takes precendence over sort_keys.

If sort_keys is true (default: `False`), the output of dictionaries will be sorted by item.

If for_json is true (default: `False`), objects with a `for_json()` method will use the return value of that method for encoding as JSON instead of the object.

To use a custom `JSONEncoder` subclass (e.g. one that overrides the `.default()` method to serialize additional types), specify it with the `cls` kwarg. NOTE: You should use default instead of subclassing whenever possible.

Show source ≡

    def dumpsJSON(obj, skipkeys=False, ensure_ascii=True, check_circular=True,
              cls=None, indent=None, separators=None,
              encoding='utf-8', default=None, use_decimal=True,
              namedtuple_as_object=True, tuple_as_array=True,
              bigint_as_string=False, sort_keys=False, item_sort_key=None,
              for_json=False, int_as_string_bitcount=None, **kw):
        """Serialize ``obj`` to a JSON formatted ``str``.

        If ``skipkeys`` is false then ``dict`` keys that are not basic types
        (``str``, ``unicode``, ``int``, ``long``, ``float``, ``bool``, ``None``)
        will be skipped instead of raising a ``TypeError``.

        If ``ensure_ascii`` is false, then the return value will be a
        ``unicode`` instance subject to normal Python ``str`` to ``unicode``
        coercion rules instead of being escaped to an ASCII ``str``.

        If ``check_circular`` is false, then the circular reference check
        for container types will be skipped and a circular reference will
        result in an ``OverflowError`` (or worse).

        If ``indent`` is a string, then JSON array elements and object members
        will be pretty-printed with a newline followed by that string repeated
        for each level of nesting. ``None`` (the default) selects the most compact
        representation without any newlines. An integer is also accepted
        and is converted to a string with that many spaces.

        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.

        ``encoding`` is the character encoding for str instances, default is UTF-8.

        ``default(obj)`` is a function that should return a serializable version
        of obj or raise TypeError. The default simply raises TypeError.

        If *use_decimal* is true (default: ``True``) then decimal.Decimal
        will be natively serialized to JSON with full precision.

        If *namedtuple_as_object* is true (default: ``True``),
        :class:`tuple` subclasses with ``_asdict()`` methods will be encoded
        as JSON objects.

        If *tuple_as_array* is true (default: ``True``),
        :class:`tuple` (and subclasses) will be encoded as JSON arrays.

        If *bigint_as_string* is true (not the default), ints 2**53 and higher
        or lower than -2**53 will be encoded as strings. This is to avoid the
        rounding that happens in Javascript otherwise.

        If *int_as_string_bitcount* is a positive number (n), then int of size
        greater than or equal to 2**n or lower than or equal to -2**n will be
        encoded as strings.

        If specified, *item_sort_key* is a callable used to sort the items in
        each dictionary. This is useful if you want to sort items other than
        in alphabetical order by key. This option takes precendence over
        *sort_keys*.

        If *sort_keys* is true (default: ``False``), the output of dictionaries
        will be sorted by item.

        If *for_json* is true (default: ``False``), objects with a ``for_json()``
        method will use the return value of that method for encoding as JSON
        instead of the object.

        To use a custom ``JSONEncoder`` subclass (e.g. one that overrides the
        ``.default()`` method to serialize additional types), specify it with
        the ``cls`` kwarg. NOTE: You should use *default* instead of subclassing
        whenever possible.

        """
        # cached encoder
        if (
            not skipkeys and ensure_ascii and
            check_circular and
            cls is None and indent is None and separators is None and
            encoding == 'utf-8' and default is None and use_decimal
            and namedtuple_as_object and tuple_as_array
            and not bigint_as_string and not sort_keys
            and not item_sort_key and not for_json
            and int_as_string_bitcount is None
            and not kw
        ):
            return _default_json_encoder.encode(obj)
        if cls is None:
            cls = JSONEncoder
        return cls(
            skipkeys=skipkeys, ensure_ascii=ensure_ascii,
            check_circular=check_circular, indent=indent,
            separators=separators, encoding=encoding, default=default,
            use_decimal=use_decimal,
            namedtuple_as_object=namedtuple_as_object,
            tuple_as_array=tuple_as_array,
            bigint_as_string=bigint_as_string,
            sort_keys=sort_keys,
            item_sort_key=item_sort_key,
            for_json=for_json,
            int_as_string_bitcount=int_as_string_bitcount,
            **kw).encode(obj)

def load(

fp, encoding=None, cls=None, object_hook=None, parse_float=None, parse_int=None, object_pairs_hook=<class 'collections.OrderedDict'>, use_decimal=False, namedtuple_as_object=True, tuple_as_array=True, **kw)

Deserialize `fp` (a `.read()`-supporting file-like object containing a JSON document) to a Python object.

encoding determines the encoding used to interpret any :class:`str` objects decoded by this instance (`'utf-8'` by default). It has no effect when decoding :class:`unicode` objects.

Note that currently only encodings that are a superset of ASCII work, strings of other encodings should be passed in as :class:`unicode`.

object_hook, if specified, will be called with the result of every JSON object decoded and its return value will be used in place of the given :class:`dict`. This can be used to provide custom deserializations (e.g. to support JSON-RPC class hinting).

object_pairs_hook is an optional function that will be called with the result of any object literal decode with an ordered list of pairs. The return value of object_pairs_hook will be used instead of the :class:`dict`. This feature can be used to implement custom decoders that rely on the order that the key and value pairs are decoded (for example, :func:`collections.OrderedDict` will remember the order of insertion). If object_hook is also defined, the object_pairs_hook takes priority.

parse_float, if specified, will be called with the string of every JSON float to be decoded. By default, this is equivalent to `float(num_str)`. This can be used to use another datatype or parser for JSON floats (e.g. :class:`decimal.Decimal`).

parse_int, if specified, will be called with the string of every JSON int to be decoded. By default, this is equivalent to `int(num_str)`. This can be used to use another datatype or parser for JSON integers (e.g. :class:`float`).

If use_decimal is true (default: `False`) then it implies parse_float=decimal.Decimal for parity with `dump`.

To use a custom `HjsonDecoder` subclass, specify it with the `cls` kwarg. NOTE: You should use object_hook or object_pairs_hook instead of subclassing whenever possible.

Show source ≡

    def load(fp, encoding=None, cls=None, object_hook=None, parse_float=None,
            parse_int=None, object_pairs_hook=OrderedDict,
            use_decimal=False, namedtuple_as_object=True, tuple_as_array=True,
            **kw):
        """Deserialize ``fp`` (a ``.read()``-supporting file-like object containing
        a JSON document) to a Python object.

        *encoding* determines the encoding used to interpret any
        :class:`str` objects decoded by this instance (``'utf-8'`` by
        default).  It has no effect when decoding :class:`unicode` objects.

        Note that currently only encodings that are a superset of ASCII work,
        strings of other encodings should be passed in as :class:`unicode`.

        *object_hook*, if specified, will be called with the result of every
        JSON object decoded and its return value will be used in place of the
        given :class:`dict`.  This can be used to provide custom
        deserializations (e.g. to support JSON-RPC class hinting).

        *object_pairs_hook* is an optional function that will be called with
        the result of any object literal decode with an ordered list of pairs.
        The return value of *object_pairs_hook* will be used instead of the
        :class:`dict`.  This feature can be used to implement custom decoders
        that rely on the order that the key and value pairs are decoded (for
        example, :func:`collections.OrderedDict` will remember the order of
        insertion). If *object_hook* is also defined, the *object_pairs_hook*
        takes priority.

        *parse_float*, if specified, will be called with the string of every
        JSON float to be decoded.  By default, this is equivalent to
        ``float(num_str)``. This can be used to use another datatype or parser
        for JSON floats (e.g. :class:`decimal.Decimal`).

        *parse_int*, if specified, will be called with the string of every
        JSON int to be decoded.  By default, this is equivalent to
        ``int(num_str)``.  This can be used to use another datatype or parser
        for JSON integers (e.g. :class:`float`).

        If *use_decimal* is true (default: ``False``) then it implies
        parse_float=decimal.Decimal for parity with ``dump``.

        To use a custom ``HjsonDecoder`` subclass, specify it with the ``cls``
        kwarg. NOTE: You should use *object_hook* or *object_pairs_hook* instead
        of subclassing whenever possible.

        """
        return loads(fp.read(),
            encoding=encoding, cls=cls, object_hook=object_hook,
            parse_float=parse_float, parse_int=parse_int,
            object_pairs_hook=object_pairs_hook,
            use_decimal=use_decimal, **kw)

def loads(

s, encoding=None, cls=None, object_hook=None, parse_float=None, parse_int=None, object_pairs_hook=None, use_decimal=False, **kw)

Deserialize `s` (a `str` or `unicode` instance containing a JSON document) to a Python object.

encoding determines the encoding used to interpret any :class:`str` objects decoded by this instance (`'utf-8'` by default). It has no effect when decoding :class:`unicode` objects.

Note that currently only encodings that are a superset of ASCII work, strings of other encodings should be passed in as :class:`unicode`.

object_hook, if specified, will be called with the result of every JSON object decoded and its return value will be used in place of the given :class:`dict`. This can be used to provide custom deserializations (e.g. to support JSON-RPC class hinting).

object_pairs_hook is an optional function that will be called with the result of any object literal decode with an ordered list of pairs. The return value of object_pairs_hook will be used instead of the :class:`dict`. This feature can be used to implement custom decoders that rely on the order that the key and value pairs are decoded (for example, :func:`collections.OrderedDict` will remember the order of insertion). If object_hook is also defined, the object_pairs_hook takes priority.

parse_float, if specified, will be called with the string of every JSON float to be decoded. By default, this is equivalent to `float(num_str)`. This can be used to use another datatype or parser for JSON floats (e.g. :class:`decimal.Decimal`).

parse_int, if specified, will be called with the string of every JSON int to be decoded. By default, this is equivalent to `int(num_str)`. This can be used to use another datatype or parser for JSON integers (e.g. :class:`float`).

If use_decimal is true (default: `False`) then it implies parse_float=decimal.Decimal for parity with `dump`.

To use a custom `HjsonDecoder` subclass, specify it with the `cls` kwarg. NOTE: You should use object_hook or object_pairs_hook instead of subclassing whenever possible.

Show source ≡

    def loads(s, encoding=None, cls=None, object_hook=None, parse_float=None,
            parse_int=None, object_pairs_hook=None,
            use_decimal=False, **kw):
        """Deserialize ``s`` (a ``str`` or ``unicode`` instance containing a JSON
        document) to a Python object.

        *encoding* determines the encoding used to interpret any
        :class:`str` objects decoded by this instance (``'utf-8'`` by
        default).  It has no effect when decoding :class:`unicode` objects.

        Note that currently only encodings that are a superset of ASCII work,
        strings of other encodings should be passed in as :class:`unicode`.

        *object_hook*, if specified, will be called with the result of every
        JSON object decoded and its return value will be used in place of the
        given :class:`dict`.  This can be used to provide custom
        deserializations (e.g. to support JSON-RPC class hinting).

        *object_pairs_hook* is an optional function that will be called with
        the result of any object literal decode with an ordered list of pairs.
        The return value of *object_pairs_hook* will be used instead of the
        :class:`dict`.  This feature can be used to implement custom decoders
        that rely on the order that the key and value pairs are decoded (for
        example, :func:`collections.OrderedDict` will remember the order of
        insertion). If *object_hook* is also defined, the *object_pairs_hook*
        takes priority.

        *parse_float*, if specified, will be called with the string of every
        JSON float to be decoded.  By default, this is equivalent to
        ``float(num_str)``. This can be used to use another datatype or parser
        for JSON floats (e.g. :class:`decimal.Decimal`).

        *parse_int*, if specified, will be called with the string of every
        JSON int to be decoded.  By default, this is equivalent to
        ``int(num_str)``.  This can be used to use another datatype or parser
        for JSON integers (e.g. :class:`float`).

        If *use_decimal* is true (default: ``False``) then it implies
        parse_float=decimal.Decimal for parity with ``dump``.

        To use a custom ``HjsonDecoder`` subclass, specify it with the ``cls``
        kwarg. NOTE: You should use *object_hook* or *object_pairs_hook* instead
        of subclassing whenever possible.

        """
        if (cls is None and encoding is None and object_hook is None and
                parse_int is None and parse_float is None and
                object_pairs_hook is None
                and not use_decimal and not kw):
            return _default_decoder.decode(s)
        if cls is None:
            cls = HjsonDecoder
        if object_hook is not None:
            kw['object_hook'] = object_hook
        if object_pairs_hook is not None:
            kw['object_pairs_hook'] = object_pairs_hook
        if parse_float is not None:
            kw['parse_float'] = parse_float
        if parse_int is not None:
            kw['parse_int'] = parse_int
        if use_decimal:
            if parse_float is not None:
                raise TypeError("use_decimal=True implies parse_float=Decimal")
            kw['parse_float'] = Decimal
        return cls(encoding=encoding, **kw).decode(s)

def simple_first(

kv)

Helper function to pass to item_sort_key to sort simple elements to the top, then container elements.

Show source ≡

    def simple_first(kv):
        """Helper function to pass to item_sort_key to sort simple
        elements to the top, then container elements.
        """
        return (isinstance(kv[1], (list, dict, tuple)), kv[0])

## Classes

class HjsonDecodeError

Subclass of ValueError with the following additional properties:

msg: The unformatted error message doc: The JSON document being parsed pos: The start index of doc where parsing failed end: The end index of doc where parsing failed (may be None) lineno: The line corresponding to pos colno: The column corresponding to pos endlineno: The line corresponding to end (may be None) endcolno: The column corresponding to end (may be None)

Show source ≡

    class HjsonDecodeError(ValueError):
        """Subclass of ValueError with the following additional properties:

        msg: The unformatted error message
        doc: The JSON document being parsed
        pos: The start index of doc where parsing failed
        end: The end index of doc where parsing failed (may be None)
        lineno: The line corresponding to pos
        colno: The column corresponding to pos
        endlineno: The line corresponding to end (may be None)
        endcolno: The column corresponding to end (may be None)

        """
        # Note that this exception is used from _speedups
        def __init__(self, msg, doc, pos, end=None):
            ValueError.__init__(self, errmsg(msg, doc, pos, end=end))
            self.msg = msg
            self.doc = doc
            self.pos = pos
            self.end = end
            self.lineno, self.colno = linecol(doc, pos)
            if end is not None:
                self.endlineno, self.endcolno = linecol(doc, end)
            else:
                self.endlineno, self.endcolno = None, None

        def __reduce__(self):
            return self.__class__, (self.msg, self.doc, self.pos, self.end)

### Ancestors (in MRO)

- HjsonDecodeError
- exceptions.ValueError
- exceptions.StandardError
- exceptions.Exception
- exceptions.BaseException
- __builtin__.object

### Class variables

var args

var message

### Instance variables

var doc

var end

var msg

var pos

### Methods

def __init__(

self, msg, doc, pos, end=None)

Show source ≡

    def __init__(self, msg, doc, pos, end=None):
        ValueError.__init__(self, errmsg(msg, doc, pos, end=end))
        self.msg = msg
        self.doc = doc
        self.pos = pos
        self.end = end
        self.lineno, self.colno = linecol(doc, pos)
        if end is not None:
            self.endlineno, self.endcolno = linecol(doc, end)
        else:
            self.endlineno, self.endcolno = None, None

class HjsonDecoder

Hjson decoder

Performs the following translations in decoding by default:

+---------------+-------------------+ | JSON | Python | +===============+===================+ | object | dict | +---------------+-------------------+ | array | list | +---------------+-------------------+ | string | str, unicode | +---------------+-------------------+ | number (int) | int, long | +---------------+-------------------+ | number (real) | float | +---------------+-------------------+ | true | True | +---------------+-------------------+ | false | False | +---------------+-------------------+ | null | None | +---------------+-------------------+

Show source ≡

    class HjsonDecoder(object):
        """Hjson decoder

        Performs the following translations in decoding by default:

        +---------------+-------------------+
        | JSON          | Python            |
        +===============+===================+
        | object        | dict              |
        +---------------+-------------------+
        | array         | list              |
        +---------------+-------------------+
        | string        | str, unicode      |
        +---------------+-------------------+
        | number (int)  | int, long         |
        +---------------+-------------------+
        | number (real) | float             |
        +---------------+-------------------+
        | true          | True              |
        +---------------+-------------------+
        | false         | False             |
        +---------------+-------------------+
        | null          | None              |
        +---------------+-------------------+

        """

        def __init__(self, encoding=None, object_hook=None, parse_float=None,
                parse_int=None, strict=True,
                object_pairs_hook=None):
            """
            *encoding* determines the encoding used to interpret any
            :class:`str` objects decoded by this instance (``'utf-8'`` by
            default).  It has no effect when decoding :class:`unicode` objects.

            Note that currently only encodings that are a superset of ASCII work,
            strings of other encodings should be passed in as :class:`unicode`.

            *object_hook*, if specified, will be called with the result of every
            JSON object decoded and its return value will be used in place of the
            given :class:`dict`.  This can be used to provide custom
            deserializations (e.g. to support JSON-RPC class hinting).

            *object_pairs_hook* is an optional function that will be called with
            the result of any object literal decode with an ordered list of pairs.
            The return value of *object_pairs_hook* will be used instead of the
            :class:`dict`.  This feature can be used to implement custom decoders
            that rely on the order that the key and value pairs are decoded (for
            example, :func:`collections.OrderedDict` will remember the order of
            insertion). If *object_hook* is also defined, the *object_pairs_hook*
            takes priority.

            *parse_float*, if specified, will be called with the string of every
            JSON float to be decoded.  By default, this is equivalent to
            ``float(num_str)``. This can be used to use another datatype or parser
            for JSON floats (e.g. :class:`decimal.Decimal`).

            *parse_int*, if specified, will be called with the string of every
            JSON int to be decoded.  By default, this is equivalent to
            ``int(num_str)``.  This can be used to use another datatype or parser
            for JSON integers (e.g. :class:`float`).

            *strict* controls the parser's behavior when it encounters an
            invalid control character in a string. The default setting of
            ``True`` means that unescaped control characters are parse errors, if
            ``False`` then control characters will be allowed in strings.

            """
            if encoding is None:
                encoding = DEFAULT_ENCODING
            self.encoding = encoding
            self.object_hook = object_hook
            self.object_pairs_hook = object_pairs_hook
            self.parse_float = parse_float or float
            self.parse_int = parse_int or int
            self.strict = strict
            self.parse_object = JSONObject
            self.parse_array = JSONArray
            self.parse_string = scanstring
            self.parse_mlstring = mlscanstring
            self.parse_tfnns = scantfnns
            self.memo = {}
            (self.scan_once, self.scan_object_once) = make_scanner(self)

        def decode(self, s, _PY3=PY3):
            """Return the Python representation of ``s`` (a ``str`` or ``unicode``
            instance containing a JSON document)

            """
            if _PY3 and isinstance(s, binary_type):
                s = s.decode(self.encoding)
            obj, end = self.raw_decode(s)
            ch, end = getNext(s, end)
            if end != len(s):
                raise HjsonDecodeError("Extra data", s, end, len(s))
            return obj

        def raw_decode(self, s, idx=0, _PY3=PY3):
            """Decode a JSON document from ``s`` (a ``str`` or ``unicode``
            beginning with a JSON document) and return a 2-tuple of the Python
            representation and the index in ``s`` where the document ended.
            Optionally, ``idx`` can be used to specify an offset in ``s`` where
            the JSON document begins.

            This can be used to decode a JSON document from a string that may
            have extraneous data at the end.

            """
            if idx < 0:
                # Ensure that raw_decode bails on negative indexes, the regex
                # would otherwise mask this behavior. #98
                raise HjsonDecodeError('Expecting value', s, idx)
            if _PY3 and not isinstance(s, text_type):
                raise TypeError("Input string must be text, not bytes")
            # strip UTF-8 bom
            if len(s) > idx:
                ord0 = ord(s[idx])
                if ord0 == 0xfeff:
                    idx += 1
                elif ord0 == 0xef and s[idx:idx + 3] == '\xef\xbb\xbf':
                    idx += 3

            ch, idx = getNext(s, idx)

            if ch == '{' or ch == '[':
                return self.scan_once(s, idx)
            else:
                # assume we have a root object without braces
                try:
                    return self.scan_object_once(s, idx)
                except HjsonDecodeError as e:
                    # test if we are dealing with a single JSON value instead (true/false/null/num/"")
                    try:
                        return self.scan_once(s, idx)
                    except:
                        raise e

### Ancestors (in MRO)

- HjsonDecoder
- __builtin__.object

### Instance variables

var encoding

var memo

var object_hook

var object_pairs_hook

var parse_array

var parse_float

var parse_int

var parse_mlstring

var parse_object

var parse_string

var parse_tfnns

var strict

### Methods

def __init__(

self, encoding=None, object_hook=None, parse_float=None, parse_int=None, strict=True, object_pairs_hook=None)

encoding determines the encoding used to interpret any :class:`str` objects decoded by this instance (`'utf-8'` by default). It has no effect when decoding :class:`unicode` objects.

Note that currently only encodings that are a superset of ASCII work, strings of other encodings should be passed in as :class:`unicode`.

object_hook, if specified, will be called with the result of every JSON object decoded and its return value will be used in place of the given :class:`dict`. This can be used to provide custom deserializations (e.g. to support JSON-RPC class hinting).

object_pairs_hook is an optional function that will be called with the result of any object literal decode with an ordered list of pairs. The return value of object_pairs_hook will be used instead of the :class:`dict`. This feature can be used to implement custom decoders that rely on the order that the key and value pairs are decoded (for example, :func:`collections.OrderedDict` will remember the order of insertion). If object_hook is also defined, the object_pairs_hook takes priority.

parse_float, if specified, will be called with the string of every JSON float to be decoded. By default, this is equivalent to `float(num_str)`. This can be used to use another datatype or parser for JSON floats (e.g. :class:`decimal.Decimal`).

parse_int, if specified, will be called with the string of every JSON int to be decoded. By default, this is equivalent to `int(num_str)`. This can be used to use another datatype or parser for JSON integers (e.g. :class:`float`).

strict controls the parser's behavior when it encounters an invalid control character in a string. The default setting of `True` means that unescaped control characters are parse errors, if `False` then control characters will be allowed in strings.

Show source ≡

    def __init__(self, encoding=None, object_hook=None, parse_float=None,
            parse_int=None, strict=True,
            object_pairs_hook=None):
        """
        *encoding* determines the encoding used to interpret any
        :class:`str` objects decoded by this instance (``'utf-8'`` by
        default).  It has no effect when decoding :class:`unicode` objects.
        Note that currently only encodings that are a superset of ASCII work,
        strings of other encodings should be passed in as :class:`unicode`.
        *object_hook*, if specified, will be called with the result of every
        JSON object decoded and its return value will be used in place of the
        given :class:`dict`.  This can be used to provide custom
        deserializations (e.g. to support JSON-RPC class hinting).
        *object_pairs_hook* is an optional function that will be called with
        the result of any object literal decode with an ordered list of pairs.
        The return value of *object_pairs_hook* will be used instead of the
        :class:`dict`.  This feature can be used to implement custom decoders
        that rely on the order that the key and value pairs are decoded (for
        example, :func:`collections.OrderedDict` will remember the order of
        insertion). If *object_hook* is also defined, the *object_pairs_hook*
        takes priority.
        *parse_float*, if specified, will be called with the string of every
        JSON float to be decoded.  By default, this is equivalent to
        ``float(num_str)``. This can be used to use another datatype or parser
        for JSON floats (e.g. :class:`decimal.Decimal`).
        *parse_int*, if specified, will be called with the string of every
        JSON int to be decoded.  By default, this is equivalent to
        ``int(num_str)``.  This can be used to use another datatype or parser
        for JSON integers (e.g. :class:`float`).
        *strict* controls the parser's behavior when it encounters an
        invalid control character in a string. The default setting of
        ``True`` means that unescaped control characters are parse errors, if
        ``False`` then control characters will be allowed in strings.
        """
        if encoding is None:
            encoding = DEFAULT_ENCODING
        self.encoding = encoding
        self.object_hook = object_hook
        self.object_pairs_hook = object_pairs_hook
        self.parse_float = parse_float or float
        self.parse_int = parse_int or int
        self.strict = strict
        self.parse_object = JSONObject
        self.parse_array = JSONArray
        self.parse_string = scanstring
        self.parse_mlstring = mlscanstring
        self.parse_tfnns = scantfnns
        self.memo = {}
        (self.scan_once, self.scan_object_once) = make_scanner(self)

def decode(

self, s, _PY3=False)

Return the Python representation of `s` (a `str` or `unicode` instance containing a JSON document)

Show source ≡

    def decode(self, s, _PY3=PY3):
        """Return the Python representation of ``s`` (a ``str`` or ``unicode``
        instance containing a JSON document)
        """
        if _PY3 and isinstance(s, binary_type):
            s = s.decode(self.encoding)
        obj, end = self.raw_decode(s)
        ch, end = getNext(s, end)
        if end != len(s):
            raise HjsonDecodeError("Extra data", s, end, len(s))
        return obj

def raw_decode(

self, s, idx=0, _PY3=False)

Decode a JSON document from `s` (a `str` or `unicode` beginning with a JSON document) and return a 2-tuple of the Python representation and the index in `s` where the document ended. Optionally, `idx` can be used to specify an offset in `s` where the JSON document begins.

This can be used to decode a JSON document from a string that may have extraneous data at the end.

Show source ≡

    def raw_decode(self, s, idx=0, _PY3=PY3):
        """Decode a JSON document from ``s`` (a ``str`` or ``unicode``
        beginning with a JSON document) and return a 2-tuple of the Python
        representation and the index in ``s`` where the document ended.
        Optionally, ``idx`` can be used to specify an offset in ``s`` where
        the JSON document begins.
        This can be used to decode a JSON document from a string that may
        have extraneous data at the end.
        """
        if idx < 0:
            # Ensure that raw_decode bails on negative indexes, the regex
            # would otherwise mask this behavior. #98
            raise HjsonDecodeError('Expecting value', s, idx)
        if _PY3 and not isinstance(s, text_type):
            raise TypeError("Input string must be text, not bytes")
        # strip UTF-8 bom
        if len(s) > idx:
            ord0 = ord(s[idx])
            if ord0 == 0xfeff:
                idx += 1
            elif ord0 == 0xef and s[idx:idx + 3] == '\xef\xbb\xbf':
                idx += 3
        ch, idx = getNext(s, idx)
        if ch == '{' or ch == '[':
            return self.scan_once(s, idx)
        else:
            # assume we have a root object without braces
            try:
                return self.scan_object_once(s, idx)
            except HjsonDecodeError as e:
                # test if we are dealing with a single JSON value instead (true/false/null/num/"")
                try:
                    return self.scan_once(s, idx)
                except:
                    raise e

class HjsonEncoder

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

Supports the following objects and types by default:

+-------------------+---------------+ | Python | JSON | +===================+===============+ | dict, namedtuple | object | +-------------------+---------------+ | list, tuple | array | +-------------------+---------------+ | str, unicode | string | +-------------------+---------------+ | int, long, 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`).

Show source ≡

    class HjsonEncoder(object):
        """Extensible JSON  encoder for Python data structures.

        Supports the following objects and types by default:

        +-------------------+---------------+
        | Python            | JSON          |
        +===================+===============+
        | dict, namedtuple  | object        |
        +-------------------+---------------+
        | list, tuple       | array         |
        +-------------------+---------------+
        | str, unicode      | string        |
        +-------------------+---------------+
        | int, long, 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``).

        """

        def __init__(self, skipkeys=False, ensure_ascii=True,
                     check_circular=True, sort_keys=False,
                     indent='  ', encoding='utf-8', default=None,
                     use_decimal=True, namedtuple_as_object=True,
                     tuple_as_array=True, bigint_as_string=False,
                     item_sort_key=None, for_json=False,
                     int_as_string_bitcount=None):
            """Constructor for HjsonEncoder, with sensible defaults.

            If skipkeys is false, then it is a TypeError to attempt
            encoding of keys that are not str, int, long, 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 unicode characters escaped.  If
            ensure_ascii is false, the output will be unicode object.

            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 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 string, then JSON array elements and object members
            will be pretty-printed with a newline followed by that string repeated
            for each level of nesting.

            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``.

            If encoding is not None, then all input strings will be
            transformed into unicode using that encoding prior to JSON-encoding.
            The default is UTF-8.

            If use_decimal is true (not the default), ``decimal.Decimal`` will
            be supported directly by the encoder. For the inverse, decode JSON
            with ``parse_float=decimal.Decimal``.

            If namedtuple_as_object is true (the default), objects with
            ``_asdict()`` methods will be encoded as JSON objects.

            If tuple_as_array is true (the default), tuple (and subclasses) will
            be encoded as JSON arrays.

            If bigint_as_string is true (not the default), ints 2**53 and higher
            or lower than -2**53 will be encoded as strings. This is to avoid the
            rounding that happens in Javascript otherwise.

            If int_as_string_bitcount is a positive number (n), then int of size
            greater than or equal to 2**n or lower than or equal to -2**n will be
            encoded as strings.

            If specified, item_sort_key is a callable used to sort the items in
            each dictionary. This is useful if you want to sort items other than
            in alphabetical order by key.

            If for_json is true (not the default), objects with a ``for_json()``
            method will use the return value of that method for encoding as JSON
            instead of the object.

            """

            self.skipkeys = skipkeys
            self.ensure_ascii = ensure_ascii
            self.check_circular = check_circular
            self.sort_keys = sort_keys
            self.use_decimal = use_decimal
            self.namedtuple_as_object = namedtuple_as_object
            self.tuple_as_array = tuple_as_array
            self.bigint_as_string = bigint_as_string
            self.item_sort_key = item_sort_key
            self.for_json = for_json
            self.int_as_string_bitcount = int_as_string_bitcount
            if indent is not None and not isinstance(indent, string_types):
                indent = indent * ' '
            elif indent is None:
                indent = '  '
            self.indent = indent
            if default is not None:
                self.default = default
            self.encoding = encoding

        def default(self, o):
            """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)
                    return HjsonEncoder.default(self, o)

            """
            raise TypeError(repr(o) + " is not JSON serializable")

        def encode(self, o):
            """Return a JSON string representation of a Python data structure.

            >>> from hjson import HjsonEncoder
            >>> HjsonEncoder().encode({"foo": ["bar", "baz"]})
            '{"foo": ["bar", "baz"]}'

            """
            # This is for extremely simple cases and benchmarks.
            if isinstance(o, binary_type):
                _encoding = self.encoding
                if (_encoding is not None and not (_encoding == 'utf-8')):
                    o = o.decode(_encoding)

            # This doesn't pass the iterator directly to ''.join() because the
            # exceptions aren't as detailed.  The list call should be roughly
            # equivalent to the PySequence_Fast that ''.join() would do.
            chunks = self.iterencode(o, _one_shot=True)
            if not isinstance(chunks, (list, tuple)):
                chunks = list(chunks)
            if self.ensure_ascii:
                return ''.join(chunks)
            else:
                return u''.join(chunks)

        def iterencode(self, o, _one_shot=False):
            """Encode the given object and yield each string
            representation as available.

            For example::

                for chunk in HjsonEncoder().iterencode(bigobject):
                    mysocket.write(chunk)

            """
            if self.check_circular:
                markers = {}
            else:
                markers = None
            if self.ensure_ascii:
                _encoder = encode_basestring_ascii
            else:
                _encoder = encode_basestring
            if self.encoding != 'utf-8':
                def _encoder(o, _orig_encoder=_encoder, _encoding=self.encoding):
                    if isinstance(o, binary_type):
                        o = o.decode(_encoding)
                    return _orig_encoder(o)

            def floatstr(o, _repr=FLOAT_REPR, _inf=PosInf, _neginf=-PosInf):
                # Check for specials. Note that this type of test is processor
                # and/or platform-specific, so do tests which don't depend on
                # the internals.

                if o != o or o == _inf or o == _neginf:
                    return 'null'
                else:
                    return _repr(o)

            key_memo = {}
            int_as_string_bitcount = (
                53 if self.bigint_as_string else self.int_as_string_bitcount)
            _iterencode = _make_iterencode(
                markers, self.default, _encoder, self.indent, floatstr,
                self.sort_keys, self.skipkeys, _one_shot, self.use_decimal,
                self.namedtuple_as_object, self.tuple_as_array,
                int_as_string_bitcount,
                self.item_sort_key, self.encoding, self.for_json,
                Decimal=Decimal)
            try:
                return _iterencode(o, 0, True)
            finally:
                key_memo.clear()

### Ancestors (in MRO)

- HjsonEncoder
- __builtin__.object

### Instance variables

var bigint_as_string

var check_circular

var encoding

var ensure_ascii

var for_json

var indent

var int_as_string_bitcount

var item_sort_key

var namedtuple_as_object

var skipkeys

var sort_keys

var tuple_as_array

var use_decimal

### Methods

def __init__(

self, skipkeys=False, ensure_ascii=True, check_circular=True, sort_keys=False, indent=' ', encoding='utf-8', default=None, use_decimal=True, namedtuple_as_object=True, tuple_as_array=True, bigint_as_string=False, item_sort_key=None, for_json=False, int_as_string_bitcount=None)

Constructor for HjsonEncoder, with sensible defaults.

If skipkeys is false, then it is a TypeError to attempt encoding of keys that are not str, int, long, 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 unicode characters escaped. If ensure_ascii is false, the output will be unicode object.

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 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 string, then JSON array elements and object members will be pretty-printed with a newline followed by that string repeated for each level of nesting.

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`.

If encoding is not None, then all input strings will be transformed into unicode using that encoding prior to JSON-encoding. The default is UTF-8.

If use_decimal is true (not the default), `decimal.Decimal` will be supported directly by the encoder. For the inverse, decode JSON with `parse_float=decimal.Decimal`.

If namedtuple_as_object is true (the default), objects with `_asdict()` methods will be encoded as JSON objects.

If tuple_as_array is true (the default), tuple (and subclasses) will be encoded as JSON arrays.

If bigint_as_string is true (not the default), ints 253 and higher or lower than -253 will be encoded as strings. This is to avoid the rounding that happens in Javascript otherwise.

If int_as_string_bitcount is a positive number (n), then int of size greater than or equal to 2n or lower than or equal to -2n will be encoded as strings.

If specified, item_sort_key is a callable used to sort the items in each dictionary. This is useful if you want to sort items other than in alphabetical order by key.

If for_json is true (not the default), objects with a `for_json()` method will use the return value of that method for encoding as JSON instead of the object.

Show source ≡

    def __init__(self, skipkeys=False, ensure_ascii=True,
                 check_circular=True, sort_keys=False,
                 indent='  ', encoding='utf-8', default=None,
                 use_decimal=True, namedtuple_as_object=True,
                 tuple_as_array=True, bigint_as_string=False,
                 item_sort_key=None, for_json=False,
                 int_as_string_bitcount=None):
        """Constructor for HjsonEncoder, with sensible defaults.
        If skipkeys is false, then it is a TypeError to attempt
        encoding of keys that are not str, int, long, 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 unicode characters escaped.  If
        ensure_ascii is false, the output will be unicode object.
        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 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 string, then JSON array elements and object members
        will be pretty-printed with a newline followed by that string repeated
        for each level of nesting.
        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``.
        If encoding is not None, then all input strings will be
        transformed into unicode using that encoding prior to JSON-encoding.
        The default is UTF-8.
        If use_decimal is true (not the default), ``decimal.Decimal`` will
        be supported directly by the encoder. For the inverse, decode JSON
        with ``parse_float=decimal.Decimal``.
        If namedtuple_as_object is true (the default), objects with
        ``_asdict()`` methods will be encoded as JSON objects.
        If tuple_as_array is true (the default), tuple (and subclasses) will
        be encoded as JSON arrays.
        If bigint_as_string is true (not the default), ints 2**53 and higher
        or lower than -2**53 will be encoded as strings. This is to avoid the
        rounding that happens in Javascript otherwise.
        If int_as_string_bitcount is a positive number (n), then int of size
        greater than or equal to 2**n or lower than or equal to -2**n will be
        encoded as strings.
        If specified, item_sort_key is a callable used to sort the items in
        each dictionary. This is useful if you want to sort items other than
        in alphabetical order by key.
        If for_json is true (not the default), objects with a ``for_json()``
        method will use the return value of that method for encoding as JSON
        instead of the object.
        """
        self.skipkeys = skipkeys
        self.ensure_ascii = ensure_ascii
        self.check_circular = check_circular
        self.sort_keys = sort_keys
        self.use_decimal = use_decimal
        self.namedtuple_as_object = namedtuple_as_object
        self.tuple_as_array = tuple_as_array
        self.bigint_as_string = bigint_as_string
        self.item_sort_key = item_sort_key
        self.for_json = for_json
        self.int_as_string_bitcount = int_as_string_bitcount
        if indent is not None and not isinstance(indent, string_types):
            indent = indent * ' '
        elif indent is None:
            indent = '  '
        self.indent = indent
        if default is not None:
            self.default = default
        self.encoding = encoding

def default(

self, o)

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)
        return HjsonEncoder.default(self, o)

Show source ≡

    def default(self, o):
        """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)
                return HjsonEncoder.default(self, o)
        """
        raise TypeError(repr(o) + " is not JSON serializable")

def encode(

self, o)

Return a JSON string representation of a Python data structure.

> > > from hjson import HjsonEncoder HjsonEncoder().encode({"foo": ["bar", "baz"]}) '{"foo": ["bar", "baz"]}'

Show source ≡

    def encode(self, o):
        """Return a JSON string representation of a Python data structure.
        >>> from hjson import HjsonEncoder
        >>> HjsonEncoder().encode({"foo": ["bar", "baz"]})
        '{"foo": ["bar", "baz"]}'
        """
        # This is for extremely simple cases and benchmarks.
        if isinstance(o, binary_type):
            _encoding = self.encoding
            if (_encoding is not None and not (_encoding == 'utf-8')):
                o = o.decode(_encoding)
        # This doesn't pass the iterator directly to ''.join() because the
        # exceptions aren't as detailed.  The list call should be roughly
        # equivalent to the PySequence_Fast that ''.join() would do.
        chunks = self.iterencode(o, _one_shot=True)
        if not isinstance(chunks, (list, tuple)):
            chunks = list(chunks)
        if self.ensure_ascii:
            return ''.join(chunks)
        else:
            return u''.join(chunks)

def iterencode(

self, o, _one_shot=False)

Encode the given object and yield each string representation as available.

For example::

    for chunk in HjsonEncoder().iterencode(bigobject):
        mysocket.write(chunk)

Show source ≡

    def iterencode(self, o, _one_shot=False):
        """Encode the given object and yield each string
        representation as available.
        For example::
            for chunk in HjsonEncoder().iterencode(bigobject):
                mysocket.write(chunk)
        """
        if self.check_circular:
            markers = {}
        else:
            markers = None
        if self.ensure_ascii:
            _encoder = encode_basestring_ascii
        else:
            _encoder = encode_basestring
        if self.encoding != 'utf-8':
            def _encoder(o, _orig_encoder=_encoder, _encoding=self.encoding):
                if isinstance(o, binary_type):
                    o = o.decode(_encoding)
                return _orig_encoder(o)
        def floatstr(o, _repr=FLOAT_REPR, _inf=PosInf, _neginf=-PosInf):
            # Check for specials. Note that this type of test is processor
            # and/or platform-specific, so do tests which don't depend on
            # the internals.
            if o != o or o == _inf or o == _neginf:
                return 'null'
            else:
                return _repr(o)
        key_memo = {}
        int_as_string_bitcount = (
            53 if self.bigint_as_string else self.int_as_string_bitcount)
        _iterencode = _make_iterencode(
            markers, self.default, _encoder, self.indent, floatstr,
            self.sort_keys, self.skipkeys, _one_shot, self.use_decimal,
            self.namedtuple_as_object, self.tuple_as_array,
            int_as_string_bitcount,
            self.item_sort_key, self.encoding, self.for_json,
            Decimal=Decimal)
        try:
            return _iterencode(o, 0, True)
        finally:
            key_memo.clear()

class JSONEncoder

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

Supports the following objects and types by default:

+-------------------+---------------+ | Python | JSON | +===================+===============+ | dict, namedtuple | object | +-------------------+---------------+ | list, tuple | array | +-------------------+---------------+ | str, unicode | string | +-------------------+---------------+ | int, long, 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`).

Show source ≡

    class JSONEncoder(object):
        """Extensible JSON  encoder for Python data structures.

        Supports the following objects and types by default:

        +-------------------+---------------+
        | Python            | JSON          |
        +===================+===============+
        | dict, namedtuple  | object        |
        +-------------------+---------------+
        | list, tuple       | array         |
        +-------------------+---------------+
        | str, unicode      | string        |
        +-------------------+---------------+
        | int, long, 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``).

        """
        item_separator = ', '
        key_separator = ': '

        def __init__(self, skipkeys=False, ensure_ascii=True,
                     check_circular=True, sort_keys=False,
                     indent=None, separators=None, encoding='utf-8', default=None,
                     use_decimal=True, namedtuple_as_object=True,
                     tuple_as_array=True, bigint_as_string=False,
                     item_sort_key=None, for_json=False,
                     int_as_string_bitcount=None):
            """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, long, 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 unicode characters escaped.  If
            ensure_ascii is false, the output will be unicode object.

            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 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 string, then JSON array elements and object members
            will be pretty-printed with a newline followed by that string repeated
            for each level of nesting. ``None`` (the default) selects the most compact
            representation without any newlines. For backwards compatibility with
            versions of hjson earlier than 2.1.0, an integer is also accepted
            and is converted to a string with that many spaces.

            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``.

            If encoding is not None, then all input strings will be
            transformed into unicode using that encoding prior to JSON-encoding.
            The default is UTF-8.

            If use_decimal is true (not the default), ``decimal.Decimal`` will
            be supported directly by the encoder. For the inverse, decode JSON
            with ``parse_float=decimal.Decimal``.

            If namedtuple_as_object is true (the default), objects with
            ``_asdict()`` methods will be encoded as JSON objects.

            If tuple_as_array is true (the default), tuple (and subclasses) will
            be encoded as JSON arrays.

            If bigint_as_string is true (not the default), ints 2**53 and higher
            or lower than -2**53 will be encoded as strings. This is to avoid the
            rounding that happens in Javascript otherwise.

            If int_as_string_bitcount is a positive number (n), then int of size
            greater than or equal to 2**n or lower than or equal to -2**n will be
            encoded as strings.

            If specified, item_sort_key is a callable used to sort the items in
            each dictionary. This is useful if you want to sort items other than
            in alphabetical order by key.

            If for_json is true (not the default), objects with a ``for_json()``
            method will use the return value of that method for encoding as JSON
            instead of the object.

            """

            self.skipkeys = skipkeys
            self.ensure_ascii = ensure_ascii
            self.check_circular = check_circular
            self.sort_keys = sort_keys
            self.use_decimal = use_decimal
            self.namedtuple_as_object = namedtuple_as_object
            self.tuple_as_array = tuple_as_array
            self.bigint_as_string = bigint_as_string
            self.item_sort_key = item_sort_key
            self.for_json = for_json
            self.int_as_string_bitcount = int_as_string_bitcount
            if indent is not None and not isinstance(indent, string_types):
                indent = indent * ' '
            self.indent = indent
            if separators is not None:
                self.item_separator, self.key_separator = separators
            elif indent is not None:
                self.item_separator = ','
            if default is not None:
                self.default = default
            self.encoding = encoding

        def default(self, o):
            """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)
                    return JSONEncoder.default(self, o)

            """
            raise TypeError(repr(o) + " is not JSON serializable")

        def encode(self, o):
            """Return a JSON string representation of a Python data structure.

            >>> from hjson import JSONEncoder
            >>> JSONEncoder().encode({"foo": ["bar", "baz"]})
            '{"foo": ["bar", "baz"]}'

            """
            # This is for extremely simple cases and benchmarks.
            if isinstance(o, binary_type):
                _encoding = self.encoding
                if (_encoding is not None and not (_encoding == 'utf-8')):
                    o = o.decode(_encoding)
            if isinstance(o, string_types):
                if self.ensure_ascii:
                    return encode_basestring_ascii(o)
                else:
                    return encode_basestring(o)
            # This doesn't pass the iterator directly to ''.join() because the
            # exceptions aren't as detailed.  The list call should be roughly
            # equivalent to the PySequence_Fast that ''.join() would do.
            chunks = self.iterencode(o, _one_shot=True)
            if not isinstance(chunks, (list, tuple)):
                chunks = list(chunks)
            if self.ensure_ascii:
                return ''.join(chunks)
            else:
                return u''.join(chunks)

        def iterencode(self, o, _one_shot=False):
            """Encode the given object and yield each string
            representation as available.

            For example::

                for chunk in JSONEncoder().iterencode(bigobject):
                    mysocket.write(chunk)

            """
            if self.check_circular:
                markers = {}
            else:
                markers = None
            if self.ensure_ascii:
                _encoder = encode_basestring_ascii
            else:
                _encoder = encode_basestring
            if self.encoding != 'utf-8':
                def _encoder(o, _orig_encoder=_encoder, _encoding=self.encoding):
                    if isinstance(o, binary_type):
                        o = o.decode(_encoding)
                    return _orig_encoder(o)

            def floatstr(o, _repr=FLOAT_REPR, _inf=PosInf, _neginf=-PosInf):
                # Check for specials. Note that this type of test is processor
                # and/or platform-specific, so do tests which don't depend on
                # the internals.

                if o != o:
                    text = 'null'
                elif o == _inf:
                    text = 'null'
                elif o == _neginf:
                    text = 'null'
                else:
                    return _repr(o)

                return text

            key_memo = {}
            int_as_string_bitcount = (
                53 if self.bigint_as_string else self.int_as_string_bitcount)
            _iterencode = _make_iterencode(
                markers, self.default, _encoder, self.indent, floatstr,
                self.key_separator, self.item_separator, self.sort_keys,
                self.skipkeys, _one_shot, self.use_decimal,
                self.namedtuple_as_object, self.tuple_as_array,
                int_as_string_bitcount,
                self.item_sort_key, self.encoding, self.for_json,
                Decimal=Decimal)
            try:
                return _iterencode(o, 0)
            finally:
                key_memo.clear()

### Ancestors (in MRO)

- JSONEncoder
- __builtin__.object

### Class variables

var item_separator

var key_separator

### Instance variables

var bigint_as_string

var check_circular

var encoding

var ensure_ascii

var for_json

var indent

var int_as_string_bitcount

var item_sort_key

var namedtuple_as_object

var skipkeys

var sort_keys

var tuple_as_array

var use_decimal

### Methods

def __init__(

self, skipkeys=False, ensure_ascii=True, check_circular=True, sort_keys=False, indent=None, separators=None, encoding='utf-8', default=None, use_decimal=True, namedtuple_as_object=True, tuple_as_array=True, bigint_as_string=False, item_sort_key=None, for_json=False, int_as_string_bitcount=None)

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, long, 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 unicode characters escaped. If ensure_ascii is false, the output will be unicode object.

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 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 string, then JSON array elements and object members will be pretty-printed with a newline followed by that string repeated for each level of nesting. `None` (the default) selects the most compact representation without any newlines. For backwards compatibility with versions of hjson earlier than 2.1.0, an integer is also accepted and is converted to a string with that many spaces.

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`.

If encoding is not None, then all input strings will be transformed into unicode using that encoding prior to JSON-encoding. The default is UTF-8.

If use_decimal is true (not the default), `decimal.Decimal` will be supported directly by the encoder. For the inverse, decode JSON with `parse_float=decimal.Decimal`.

If namedtuple_as_object is true (the default), objects with `_asdict()` methods will be encoded as JSON objects.

If tuple_as_array is true (the default), tuple (and subclasses) will be encoded as JSON arrays.

If bigint_as_string is true (not the default), ints 253 and higher or lower than -253 will be encoded as strings. This is to avoid the rounding that happens in Javascript otherwise.

If int_as_string_bitcount is a positive number (n), then int of size greater than or equal to 2n or lower than or equal to -2n will be encoded as strings.

If specified, item_sort_key is a callable used to sort the items in each dictionary. This is useful if you want to sort items other than in alphabetical order by key.

If for_json is true (not the default), objects with a `for_json()` method will use the return value of that method for encoding as JSON instead of the object.

Show source ≡

    def __init__(self, skipkeys=False, ensure_ascii=True,
                 check_circular=True, sort_keys=False,
                 indent=None, separators=None, encoding='utf-8', default=None,
                 use_decimal=True, namedtuple_as_object=True,
                 tuple_as_array=True, bigint_as_string=False,
                 item_sort_key=None, for_json=False,
                 int_as_string_bitcount=None):
        """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, long, 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 unicode characters escaped.  If
        ensure_ascii is false, the output will be unicode object.
        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 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 string, then JSON array elements and object members
        will be pretty-printed with a newline followed by that string repeated
        for each level of nesting. ``None`` (the default) selects the most compact
        representation without any newlines. For backwards compatibility with
        versions of hjson earlier than 2.1.0, an integer is also accepted
        and is converted to a string with that many spaces.
        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``.
        If encoding is not None, then all input strings will be
        transformed into unicode using that encoding prior to JSON-encoding.
        The default is UTF-8.
        If use_decimal is true (not the default), ``decimal.Decimal`` will
        be supported directly by the encoder. For the inverse, decode JSON
        with ``parse_float=decimal.Decimal``.
        If namedtuple_as_object is true (the default), objects with
        ``_asdict()`` methods will be encoded as JSON objects.
        If tuple_as_array is true (the default), tuple (and subclasses) will
        be encoded as JSON arrays.
        If bigint_as_string is true (not the default), ints 2**53 and higher
        or lower than -2**53 will be encoded as strings. This is to avoid the
        rounding that happens in Javascript otherwise.
        If int_as_string_bitcount is a positive number (n), then int of size
        greater than or equal to 2**n or lower than or equal to -2**n will be
        encoded as strings.
        If specified, item_sort_key is a callable used to sort the items in
        each dictionary. This is useful if you want to sort items other than
        in alphabetical order by key.
        If for_json is true (not the default), objects with a ``for_json()``
        method will use the return value of that method for encoding as JSON
        instead of the object.
        """
        self.skipkeys = skipkeys
        self.ensure_ascii = ensure_ascii
        self.check_circular = check_circular
        self.sort_keys = sort_keys
        self.use_decimal = use_decimal
        self.namedtuple_as_object = namedtuple_as_object
        self.tuple_as_array = tuple_as_array
        self.bigint_as_string = bigint_as_string
        self.item_sort_key = item_sort_key
        self.for_json = for_json
        self.int_as_string_bitcount = int_as_string_bitcount
        if indent is not None and not isinstance(indent, string_types):
            indent = indent * ' '
        self.indent = indent
        if separators is not None:
            self.item_separator, self.key_separator = separators
        elif indent is not None:
            self.item_separator = ','
        if default is not None:
            self.default = default
        self.encoding = encoding

def default(

self, o)

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)
        return JSONEncoder.default(self, o)

Show source ≡

    def default(self, o):
        """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)
                return JSONEncoder.default(self, o)
        """
        raise TypeError(repr(o) + " is not JSON serializable")

def encode(

self, o)

Return a JSON string representation of a Python data structure.

> > > from hjson import JSONEncoder JSONEncoder().encode({"foo": ["bar", "baz"]}) '{"foo": ["bar", "baz"]}'

Show source ≡

    def encode(self, o):
        """Return a JSON string representation of a Python data structure.
        >>> from hjson import JSONEncoder
        >>> JSONEncoder().encode({"foo": ["bar", "baz"]})
        '{"foo": ["bar", "baz"]}'
        """
        # This is for extremely simple cases and benchmarks.
        if isinstance(o, binary_type):
            _encoding = self.encoding
            if (_encoding is not None and not (_encoding == 'utf-8')):
                o = o.decode(_encoding)
        if isinstance(o, string_types):
            if self.ensure_ascii:
                return encode_basestring_ascii(o)
            else:
                return encode_basestring(o)
        # This doesn't pass the iterator directly to ''.join() because the
        # exceptions aren't as detailed.  The list call should be roughly
        # equivalent to the PySequence_Fast that ''.join() would do.
        chunks = self.iterencode(o, _one_shot=True)
        if not isinstance(chunks, (list, tuple)):
            chunks = list(chunks)
        if self.ensure_ascii:
            return ''.join(chunks)
        else:
            return u''.join(chunks)

def iterencode(

self, o, _one_shot=False)

Encode the given object and yield each string representation as available.

For example::

    for chunk in JSONEncoder().iterencode(bigobject):
        mysocket.write(chunk)

Show source ≡

    def iterencode(self, o, _one_shot=False):
        """Encode the given object and yield each string
        representation as available.
        For example::
            for chunk in JSONEncoder().iterencode(bigobject):
                mysocket.write(chunk)
        """
        if self.check_circular:
            markers = {}
        else:
            markers = None
        if self.ensure_ascii:
            _encoder = encode_basestring_ascii
        else:
            _encoder = encode_basestring
        if self.encoding != 'utf-8':
            def _encoder(o, _orig_encoder=_encoder, _encoding=self.encoding):
                if isinstance(o, binary_type):
                    o = o.decode(_encoding)
                return _orig_encoder(o)
        def floatstr(o, _repr=FLOAT_REPR, _inf=PosInf, _neginf=-PosInf):
            # Check for specials. Note that this type of test is processor
            # and/or platform-specific, so do tests which don't depend on
            # the internals.
            if o != o:
                text = 'null'
            elif o == _inf:
                text = 'null'
            elif o == _neginf:
                text = 'null'
            else:
                return _repr(o)
            return text
        key_memo = {}
        int_as_string_bitcount = (
            53 if self.bigint_as_string else self.int_as_string_bitcount)
        _iterencode = _make_iterencode(
            markers, self.default, _encoder, self.indent, floatstr,
            self.key_separator, self.item_separator, self.sort_keys,
            self.skipkeys, _one_shot, self.use_decimal,
            self.namedtuple_as_object, self.tuple_as_array,
            int_as_string_bitcount,
            self.item_sort_key, self.encoding, self.for_json,
            Decimal=Decimal)
        try:
            return _iterencode(o, 0)
        finally:
            key_memo.clear()

class OrderedDict

Dictionary that remembers insertion order

Show source ≡

    class OrderedDict(dict):
        'Dictionary that remembers insertion order'
        # An inherited dict maps keys to values.
        # The inherited dict provides __getitem__, __len__, __contains__, and get.
        # The remaining methods are order-aware.
        # Big-O running times for all methods are the same as regular dictionaries.

        # The internal self.__map dict maps keys to links in a doubly linked list.
        # The circular doubly linked list starts and ends with a sentinel element.
        # The sentinel element never gets deleted (this simplifies the algorithm).
        # Each link is stored as a list of length three:  [PREV, NEXT, KEY].

        def __init__(*args, **kwds):
            '''Initialize an ordered dictionary.  The signature is the same as
            regular dictionaries, but keyword arguments are not recommended because
            their insertion order is arbitrary.

            '''
            if not args:
                raise TypeError("descriptor '__init__' of 'OrderedDict' object "
                                "needs an argument")
            self = args[0]
            args = args[1:]
            if len(args) > 1:
                raise TypeError('expected at most 1 arguments, got %d' % len(args))
            try:
                self.__root
            except AttributeError:
                self.__root = root = []                     # sentinel node
                root[:] = [root, root, None]
                self.__map = {}
            self.__update(*args, **kwds)

        def __setitem__(self, key, value, dict_setitem=dict.__setitem__):
            'od.__setitem__(i, y) <==> od[i]=y'
            # Setting a new item creates a new link at the end of the linked list,
            # and the inherited dictionary is updated with the new key/value pair.
            if key not in self:
                root = self.__root
                last = root[0]
                last[1] = root[0] = self.__map[key] = [last, root, key]
            return dict_setitem(self, key, value)

        def __delitem__(self, key, dict_delitem=dict.__delitem__):
            'od.__delitem__(y) <==> del od[y]'
            # Deleting an existing item uses self.__map to find the link which gets
            # removed by updating the links in the predecessor and successor nodes.
            dict_delitem(self, key)
            link_prev, link_next, _ = self.__map.pop(key)
            link_prev[1] = link_next                        # update link_prev[NEXT]
            link_next[0] = link_prev                        # update link_next[PREV]

        def __iter__(self):
            'od.__iter__() <==> iter(od)'
            # Traverse the linked list in order.
            root = self.__root
            curr = root[1]                                  # start at the first node
            while curr is not root:
                yield curr[2]                               # yield the curr[KEY]
                curr = curr[1]                              # move to next node

        def __reversed__(self):
            'od.__reversed__() <==> reversed(od)'
            # Traverse the linked list in reverse order.
            root = self.__root
            curr = root[0]                                  # start at the last node
            while curr is not root:
                yield curr[2]                               # yield the curr[KEY]
                curr = curr[0]                              # move to previous node

        def clear(self):
            'od.clear() -> None.  Remove all items from od.'
            root = self.__root
            root[:] = [root, root, None]
            self.__map.clear()
            dict.clear(self)

        # -- the following methods do not depend on the internal structure --

        def keys(self):
            'od.keys() -> list of keys in od'
            return list(self)

        def values(self):
            'od.values() -> list of values in od'
            return [self[key] for key in self]

        def items(self):
            'od.items() -> list of (key, value) pairs in od'
            return [(key, self[key]) for key in self]

        def iterkeys(self):
            'od.iterkeys() -> an iterator over the keys in od'
            return iter(self)

        def itervalues(self):
            'od.itervalues -> an iterator over the values in od'
            for k in self:
                yield self[k]

        def iteritems(self):
            'od.iteritems -> an iterator over the (key, value) pairs in od'
            for k in self:
                yield (k, self[k])

        update = MutableMapping.update

        __update = update # let subclasses override update without breaking __init__

        __marker = object()

        def pop(self, key, default=__marker):
            '''od.pop(k[,d]) -> v, remove specified key and return the corresponding
            value.  If key is not found, d is returned if given, otherwise KeyError
            is raised.

            '''
            if key in self:
                result = self[key]
                del self[key]
                return result
            if default is self.__marker:
                raise KeyError(key)
            return default

        def setdefault(self, key, default=None):
            'od.setdefault(k[,d]) -> od.get(k,d), also set od[k]=d if k not in od'
            if key in self:
                return self[key]
            self[key] = default
            return default

        def popitem(self, last=True):
            '''od.popitem() -> (k, v), return and remove a (key, value) pair.
            Pairs are returned in LIFO order if last is true or FIFO order if false.

            '''
            if not self:
                raise KeyError('dictionary is empty')
            key = next(reversed(self) if last else iter(self))
            value = self.pop(key)
            return key, value

        def __repr__(self, _repr_running={}):
            'od.__repr__() <==> repr(od)'
            call_key = id(self), _get_ident()
            if call_key in _repr_running:
                return '...'
            _repr_running[call_key] = 1
            try:
                if not self:
                    return '%s()' % (self.__class__.__name__,)
                return '%s(%r)' % (self.__class__.__name__, self.items())
            finally:
                del _repr_running[call_key]

        def __reduce__(self):
            'Return state information for pickling'
            items = [[k, self[k]] for k in self]
            inst_dict = vars(self).copy()
            for k in vars(OrderedDict()):
                inst_dict.pop(k, None)
            if inst_dict:
                return (self.__class__, (items,), inst_dict)
            return self.__class__, (items,)

        def copy(self):
            'od.copy() -> a shallow copy of od'
            return self.__class__(self)

        @classmethod
        def fromkeys(cls, iterable, value=None):
            '''OD.fromkeys(S[, v]) -> New ordered dictionary with keys from S.
            If not specified, the value defaults to None.

            '''
            self = cls()
            for key in iterable:
                self[key] = value
            return self

        def __eq__(self, other):
            '''od.__eq__(y) <==> od==y.  Comparison to another OD is order-sensitive
            while comparison to a regular mapping is order-insensitive.

            '''
            if isinstance(other, OrderedDict):
                return dict.__eq__(self, other) and all(_imap(_eq, self, other))
            return dict.__eq__(self, other)

        def __ne__(self, other):
            'od.__ne__(y) <==> od!=y'
            return not self == other

        # -- the following methods support python 3.x style dictionary views --

        def viewkeys(self):
            "od.viewkeys() -> a set-like object providing a view on od's keys"
            return KeysView(self)

        def viewvalues(self):
            "od.viewvalues() -> an object providing a view on od's values"
            return ValuesView(self)

        def viewitems(self):
            "od.viewitems() -> a set-like object providing a view on od's items"
            return ItemsView(self)

### Ancestors (in MRO)

- OrderedDict
- __builtin__.dict
- __builtin__.object

### Methods

def __init__(

*args, **kwds)

Initialize an ordered dictionary. The signature is the same as regular dictionaries, but keyword arguments are not recommended because their insertion order is arbitrary.

Show source ≡

    def __init__(*args, **kwds):
        '''Initialize an ordered dictionary.  The signature is the same as
        regular dictionaries, but keyword arguments are not recommended because
        their insertion order is arbitrary.
        '''
        if not args:
            raise TypeError("descriptor '__init__' of 'OrderedDict' object "
                            "needs an argument")
        self = args[0]
        args = args[1:]
        if len(args) > 1:
            raise TypeError('expected at most 1 arguments, got %d' % len(args))
        try:
            self.__root
        except AttributeError:
            self.__root = root = []                     # sentinel node
            root[:] = [root, root, None]
            self.__map = {}
        self.__update(*args, **kwds)

def clear(

self)

od.clear() -> None. Remove all items from od.

Show source ≡

    def clear(self):
        'od.clear() -> None.  Remove all items from od.'
        root = self.__root
        root[:] = [root, root, None]
        self.__map.clear()
        dict.clear(self)

def copy(

self)

od.copy() -> a shallow copy of od

Show source ≡

    def copy(self):
        'od.copy() -> a shallow copy of od'
        return self.__class__(self)

def fromkeys(

cls, iterable, value=None)

OD.fromkeys(S[, v]) -> New ordered dictionary with keys from S. If not specified, the value defaults to None.

Show source ≡

    @classmethod
    def fromkeys(cls, iterable, value=None):
        '''OD.fromkeys(S[, v]) -> New ordered dictionary with keys from S.
        If not specified, the value defaults to None.
        '''
        self = cls()
        for key in iterable:
            self[key] = value
        return self

def items(

self)

od.items() -> list of (key, value) pairs in od

Show source ≡

    def items(self):
        'od.items() -> list of (key, value) pairs in od'
        return [(key, self[key]) for key in self]

def iteritems(

self)

od.iteritems -> an iterator over the (key, value) pairs in od

Show source ≡

    def iteritems(self):
        'od.iteritems -> an iterator over the (key, value) pairs in od'
        for k in self:
            yield (k, self[k])

def iterkeys(

self)

od.iterkeys() -> an iterator over the keys in od

Show source ≡

    def iterkeys(self):
        'od.iterkeys() -> an iterator over the keys in od'
        return iter(self)

def itervalues(

self)

od.itervalues -> an iterator over the values in od

Show source ≡

    def itervalues(self):
        'od.itervalues -> an iterator over the values in od'
        for k in self:
            yield self[k]

def keys(

self)

od.keys() -> list of keys in od

Show source ≡

    def keys(self):
        'od.keys() -> list of keys in od'
        return list(self)

def pop(

self, key, default=<object object at 0x1081ca0a0>)

od.pop(k[,d]) -> v, remove specified key and return the corresponding value. If key is not found, d is returned if given, otherwise KeyError is raised.

Show source ≡

    def pop(self, key, default=__marker):
        '''od.pop(k[,d]) -> v, remove specified key and return the corresponding
        value.  If key is not found, d is returned if given, otherwise KeyError
        is raised.
        '''
        if key in self:
            result = self[key]
            del self[key]
            return result
        if default is self.__marker:
            raise KeyError(key)
        return default

def popitem(

self, last=True)

od.popitem() -> (k, v), return and remove a (key, value) pair. Pairs are returned in LIFO order if last is true or FIFO order if false.

Show source ≡

    def popitem(self, last=True):
        '''od.popitem() -> (k, v), return and remove a (key, value) pair.
        Pairs are returned in LIFO order if last is true or FIFO order if false.
        '''
        if not self:
            raise KeyError('dictionary is empty')
        key = next(reversed(self) if last else iter(self))
        value = self.pop(key)
        return key, value

def setdefault(

self, key, default=None)

od.setdefault(k[,d]) -> od.get(k,d), also set od[k]=d if k not in od

Show source ≡

    def setdefault(self, key, default=None):
        'od.setdefault(k[,d]) -> od.get(k,d), also set od[k]=d if k not in od'
        if key in self:
            return self[key]
        self[key] = default
        return default

def update(

*args, **kwds)

D.update([E, ]**F) -> None. Update D from mapping/iterable E and F. If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v

Show source ≡

    def update(*args, **kwds):
        ''' D.update([E, ]**F) -> None.  Update D from mapping/iterable E and F.
            If E present and has a .keys() method, does:     for k in E: D[k] = E[k]
            If E present and lacks .keys() method, does:     for (k, v) in E: D[k] = v
            In either case, this is followed by: for k, v in F.items(): D[k] = v
        '''
        if not args:
            raise TypeError("descriptor 'update' of 'MutableMapping' object "
                            "needs an argument")
        self = args[0]
        args = args[1:]
        if len(args) > 1:
            raise TypeError('update expected at most 1 arguments, got %d' %
                            len(args))
        if args:
            other = args[0]
            if isinstance(other, Mapping):
                for key in other:
                    self[key] = other[key]
            elif hasattr(other, "keys"):
                for key in other.keys():
                    self[key] = other[key]
            else:
                for key, value in other:
                    self[key] = value
        for key, value in kwds.items():
            self[key] = value

def values(

self)

od.values() -> list of values in od

Show source ≡

    def values(self):
        'od.values() -> list of values in od'
        return [self[key] for key in self]

def viewitems(

self)

od.viewitems() -> a set-like object providing a view on od's items

Show source ≡

    def viewitems(self):
        "od.viewitems() -> a set-like object providing a view on od's items"
        return ItemsView(self)

def viewkeys(

self)

od.viewkeys() -> a set-like object providing a view on od's keys

Show source ≡

    def viewkeys(self):
        "od.viewkeys() -> a set-like object providing a view on od's keys"
        return KeysView(self)

def viewvalues(

self)

od.viewvalues() -> an object providing a view on od's values

Show source ≡

    def viewvalues(self):
        "od.viewvalues() -> an object providing a view on od's values"
        return ValuesView(self)