NasaGeek / marshmallow_enum

Enum handling for Marshmallow

marshmallow-enum

Enum field for use with Marshmallow.

Installation

pip install --user marshmallow_enum

If you're on a version before 3.4, you'll also need to install enum34.

Using The Field

To make use of the field, you must have an existing Enum:

from enum import Enum


class StopLight(Enum):
    green = 1
    yellow = 2
    red = 3

Then, declare it as a field in a schema:

from marshmallow import Schema
from marshmallow_enum import EnumField


class TrafficStop(Schema):
    light_color = EnumField(StopLight)

By default, the field will load and dump based on the name given to an enum value.

schema = TrafficStop()
schema.dump({'light_color': EnumField.red}).data
# {'light_color': 'red'}

schema.load({'light_color': 'red'}).data
# {'light_color': StopLight.red}

Customizing loading and dumping behavior

To customize how an enum is serialized or deserialized, there are three options:

• Setting by_value=True. This will cause both dumping and loading to use the value of the enum.
• Setting load_by=EnumField.VALUE. This will cause loading to use the value of the enum.
• Setting dump_by=EnumField.VALUE. This will cause dumping to use the value of the enum.

If either load_by or dump_by are unset, they will follow from by_value.

Additionally, there is EnumField.NAME to be explicit about the load and dump behavior, this is the same as leaving both by_value and either load_by and/or dump_by unset.

Custom Error Message

A custom error message can be provided via the error keyword argument. It can accept three format values:

• {input}: The value provided to the schema field
• {names}: The names of the individual enum members
• {values}: The values of the individual enum members

Previously, the following inputs were also available but are deprecated and will be removed in 1.6:

• {name}
• {value}
• {choices}