222

How do I serialise a Python Enum member to JSON, so that I can deserialise the resulting JSON back into a Python object?

For example, this code:

from enum import Enum    
import json

class Status(Enum):
    success = 0

json.dumps(Status.success)

results in the error:

TypeError: <Status.success: 0> is not JSON serializable

How can I avoid that?

0

9 Answers 9

316

I know this is old but I feel this will help people. I just went through this exact problem and discovered if you're using string enums, declaring your enums as a subclass of str works well for almost all situations:

import json
from enum import Enum

class LogLevel(str, Enum):
    DEBUG = 'DEBUG'
    INFO = 'INFO'

print(LogLevel.DEBUG)
print(json.dumps(LogLevel.DEBUG))
print(json.loads('"DEBUG"'))
print(LogLevel('DEBUG'))

Will output:

LogLevel.DEBUG
"DEBUG"
DEBUG
LogLevel.DEBUG

As you can see, loading the JSON outputs the string DEBUG but it is easily castable back into a LogLevel object. A good option if you don't want to create a custom JSONEncoder.

6
  • 7
    Thanks. Even though I am mostly against multiple inheritances, that's pretty neat and that's the way I am going with. No extra encoder needed :) Commented Nov 2, 2019 at 23:17
  • @madjardi, can you elaborate on the problem you are having? I have never had a problem with the value of the string being different than the name of the attribute in the enum. Am I misunderstanding your comment? Commented Nov 21, 2019 at 12:59
  • 4
    class LogLevel(str, Enum): DEBUG = 'Дебаг' INFO = 'Инфо' in this case enum with str no work properly (
    – madjardi
    Commented Nov 22, 2019 at 6:35
  • 1
    You can also do this trick with other base types, for example (I don't know how to format this in the comments, but the gist is clear: "class Shapes(int, Enum): square=1 circle=2" works great w/o need for an encoder. Thanks, this is a great approach!
    – NoCake
    Commented Sep 23, 2020 at 19:25
  • 2
    This str mixin can have unintended side effects: See this question. Commented Jan 18, 2021 at 7:07
121
+100

The correct answer depends on what you intend to do with the serialized version.

If you are going to unserialize back into Python, see Zero's answer.

If your serialized version is going to another language then you probably want to use an IntEnum instead, which is automatically serialized as the corresponding integer:

from enum import IntEnum
import json

class Status(IntEnum):
    success = 0
    failure = 1

json.dumps(Status.success)

and this returns:

'0'
9
  • 5
    @AShelly: The question was tagged with Python3.4, and this answer is 3.4+ specific. Commented Sep 3, 2014 at 15:35
  • 2
    Perfect. If you Enum is a string, you would use EnumMeta instead of IntEnum
    – gabbar0x
    Commented Apr 16, 2018 at 7:41
  • 8
    @bholagabbar: No, you would use Enum, possibly with a str mixin -- class MyStrEnum(str, Enum): ... Commented Apr 16, 2018 at 20:28
  • 3
    @bholagabbar, interesting. You should post your solution as an answer. Commented Apr 17, 2018 at 16:41
  • 4
    I would avoid inheriting directly from EnumMeta, which was intended as a metaclass only. Instead, note that the implementation of IntEnum is a one-liner and you can achieve the same for str with class StrEnum(str, Enum): ....
    – yungchin
    Commented Jul 4, 2019 at 1:22
77

If you want to encode an arbitrary enum.Enum member to JSON and then decode it as the same enum member (rather than simply the enum member's value attribute), you can do so by writing a custom JSONEncoder class, and a decoding function to pass as the object_hook argument to json.load() or json.loads():

PUBLIC_ENUMS = {
    'Status': Status,
    # ...
}

class EnumEncoder(json.JSONEncoder):
    def default(self, obj):
        if type(obj) in PUBLIC_ENUMS.values():
            return {"__enum__": str(obj)}
        return json.JSONEncoder.default(self, obj)

def as_enum(d):
    if "__enum__" in d:
        name, member = d["__enum__"].split(".")
        return getattr(PUBLIC_ENUMS[name], member)
    else:
        return d

The as_enum function relies on the JSON having been encoded using EnumEncoder, or something which behaves identically to it.

The restriction to members of PUBLIC_ENUMS is necessary to avoid a maliciously crafted text being used to, for example, trick calling code into saving private information (e.g. a secret key used by the application) to an unrelated database field, from where it could then be exposed (see https://chat.stackoverflow.com/transcript/message/35999686#35999686).

Example usage:

>>> data = {
...     "action": "frobnicate",
...     "status": Status.success
... }
>>> text = json.dumps(data, cls=EnumEncoder)
>>> text
'{"status": {"__enum__": "Status.success"}, "action": "frobnicate"}'
>>> json.loads(text, object_hook=as_enum)
{'status': <Status.success: 0>, 'action': 'frobnicate'}
8
  • If you have your code in a module(enumencoder.py, for example), you must import the class that you parse from JSON to dict. For example, in this case, you must import the class Status in the module enumencoder.py. Commented May 12, 2016 at 16:17
  • My concern was not about malicious calling code, but malicious requests to a web server. As you mentioned, the private data could be exposed in a response, or it could be used to manipulate code flow. Thank you for updating your answer. It would be even better if the main code example was secure though. Commented Mar 7, 2017 at 15:39
  • 1
    @JaredDeckard my apologies, you were right, and I was wrong. I've updated the answer accordingly. Thanks for your input! This has been educational (and chastening). Commented Mar 7, 2017 at 18:50
  • would this option be more appropriate if isinstance(obj, Enum): ? Commented Apr 16, 2020 at 17:02
  • 1
    Is there a way to somehow 'annotate' the enum with the encoder class so that the encoder is used by default?
    – ed22
    Commented Jul 17, 2020 at 2:46
42

In Python >= 3.7, can just use json.dumps(enum_obj, default=str)

If you want to use the enum value, you can do

json.dumps(enum_obj, default=lambda x: x.value)

or if you want to use the enum name,

json.dumps(enum_obj, default=lambda x: x.name)

3
  • Looks nice but it will write the name of enum into the json string. The better way will be to use value of the enum.
    – eNca
    Commented Oct 4, 2020 at 7:43
  • 2
    Enum value can be used by json.dumps(enum_obj, default=lambda x: x.value)
    – eNca
    Commented Oct 4, 2020 at 7:49
  • 3
    However, this would not work if an Enum is used as a key. It would still complain of "TypeError: keys must be str, int, float, bool or None" - Most of the solutions above do not take care of the usage as key. Enum is supposed to be hashable.
    – wr200m
    Commented Apr 30, 2021 at 23:02
38

You just need to inherit from str or int class:

from enum import Enum, unique

@unique            
class StatusEnum(int, Enum):
    pending: int = 11                                      
    approved: int = 15                                       
    declined: int = 266

That's it, it will be serialised using any JSON encoder.

2
  • 1
    Note that this serializes to the enum value, in string form, e.g. "11" or "15".
    – rjh
    Commented Aug 27, 2021 at 20:51
  • 1
    This saved me a ton of time, thanks... Commented Sep 2, 2023 at 23:03
15

I liked Zero Piraeus' answer, but modified it slightly for working with the API for Amazon Web Services (AWS) known as Boto.

class EnumEncoder(json.JSONEncoder):
    def default(self, obj):
        if isinstance(obj, Enum):
            return obj.name
        return json.JSONEncoder.default(self, obj)

I then added this method to my data model:

    def ToJson(self) -> str:
        return json.dumps(self.__dict__, cls=EnumEncoder, indent=1, sort_keys=True)

I hope this helps someone.

1
  • Why do you need to add ToJson to your data model?
    – Yu Chen
    Commented Oct 28, 2020 at 23:34
5

If you are using jsonpickle the easiest way should look as below.

from enum import Enum
import jsonpickle


@jsonpickle.handlers.register(Enum, base=True)
class EnumHandler(jsonpickle.handlers.BaseHandler):

    def flatten(self, obj, data):
        return obj.value  # Convert to json friendly format


if __name__ == '__main__':
    class Status(Enum):
        success = 0
        error = 1

    class SimpleClass:
        pass

    simple_class = SimpleClass()
    simple_class.status = Status.success

    json = jsonpickle.encode(simple_class, unpicklable=False)
    print(json)

After Json serialization you will have as expected {"status": 0} instead of

{"status": {"__objclass__": {"py/type": "__main__.Status"}, "_name_": "success", "_value_": 0}}
1

You can even combine the solutions mentioned above with the automatic value creation for Enums. I use this in combination with Pydantic and FastAPI to provide lower case names for a REST API:

from enum import Enum, auto
import json

class StrEnum(str, Enum):
    pass

# this creates nice lowercase and JSON serializable names
# https://docs.python.org/3/library/enum.html#using-automatic-values
class AutoNameLower(StrEnum):
    def _generate_next_value_(name, start, count, last_values):
        return name.lower()

class AutoNameLowerStrEnum(AutoNameLower):
    pass

class MyActualEnum(AutoNameLowerStrEnum):
    THIS = auto()
    THAT = auto()
    FOO = auto()
    BAR = auto()

print(MyActualEnum.THIS)
print(json.dumps(MyActualEnum.THIS))
print(list(MyActualEnum))

Console:

>>> MyActualEnum.THIS
>>> "this"
>>> [<MyActualEnum.THIS: 'this'>, <MyActualEnum.THAT: 'that'>, <MyActualEnum.FOO: 'foo'>, <MyActualEnum.BAR: 'bar'>]
-4

This worked for me:

class Status(Enum):
    success = 0

    def __json__(self):
        return self.value

Didn't have to change anything else. Obviously, you'll only get the value out of this and will need to do some other work if you want to convert the serialized value back into the enum later.

2
  • 3
    I don't see anything in the docs describing that magic method. Are you using some other JSON library, or do you have a custom JSONEncoder somewhere?
    – 0x5453
    Commented Aug 4, 2020 at 20:04
  • Possibly this user is importing simplejson?
    – FSCKur
    Commented Feb 17, 2021 at 12:09

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.