{"id":1545,"library":"marshmallow-enum","title":"Marshmallow Enum Field","description":"marshmallow-enum provides a dedicated `EnumField` for Marshmallow schemas, enabling seamless serialization and deserialization of Python `enum.Enum` members. It ensures type safety and proper validation when working with enumeration types in your API payloads. The current version is 1.5.1, and it typically follows the Marshmallow release cycle for compatibility updates, with minor releases as needed.","status":"active","version":"1.5.1","language":"en","source_language":"en","source_url":"https://github.com/floqqi/marshmallow-enum","tags":["marshmallow","enum","serialization","validation"],"install":[{"cmd":"pip install marshmallow-enum","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core dependency for schema definition and serialization logic.","package":"marshmallow"}],"imports":[{"symbol":"EnumField","correct":"from marshmallow_enum import EnumField"}],"quickstart":{"code":"import enum\nfrom marshmallow import Schema, fields\nfrom marshmallow_enum import EnumField\n\nclass Color(enum.Enum):\n    RED = 'red'\n    GREEN = 'green'\n    BLUE = 'blue'\n\nclass ItemSchema(Schema):\n    name = fields.String(required=True)\n    color = EnumField(Color, by_value=True, required=True)\n\n# Example usage:\nschema = ItemSchema()\n\n# Serialization (Python Enum to string/value)\nitem_obj = {'name': 'Apple', 'color': Color.RED}\nserialized_data = schema.dump(item_obj)\nprint(f\"Serialized: {serialized_data}\")\n# Expected: {'name': 'Apple', 'color': 'red'}\n\n# Deserialization (string/value to Python Enum)\ninput_data = {'name': 'Sky', 'color': 'blue'}\ndeser_obj = schema.load(input_data)\nprint(f\"Deserialized: {deser_obj['color'] == Color.BLUE}\")\nprint(f\"Deserialized Type: {type(deser_obj['color'])}\")\n# Expected: True\n# Expected Type: <enum 'Color'>","lang":"python","description":"This quickstart demonstrates how to define an `EnumField` in a Marshmallow schema. It uses `by_value=True` to specify that the enum should be serialized/deserialized by its member's value. The example shows both dumping (serializing) a Python `Enum` instance to a string and loading (deserializing) a string back into an `Enum` instance."},"warnings":[{"fix":"Always explicitly set `by_value=True` or `by_name=True` (or use `load_by` / `dump_by`) to ensure predictable behavior, especially when upgrading or sharing schemas across different `marshmallow-enum` versions.","message":"The default behavior of `EnumField` regarding `by_value` and `by_name` changed significantly in version 1.0.0. Before 1.0.0, the default was `by_value=True`. From 1.0.0 onwards, if neither `by_value` nor `by_name` is explicitly set, it attempts to load by value first, then by name.","severity":"breaking","affected_versions":"< 1.0.0 to 1.0.0+"},{"fix":"Always explicitly choose `by_value=True` or `by_name=True` (or use the more granular `load_by` and `dump_by` parameters) to make your serialization logic explicit and prevent ambiguity.","message":"When neither `by_value` nor `by_name` is explicitly specified for `EnumField`, it will attempt to deserialize by the enum member's value first, and if that fails, then by the member's name. This implicit behavior can lead to unexpected results if your enum values or names overlap with other valid inputs.","severity":"gotcha","affected_versions":"1.0.0+"},{"fix":"For strict validation, consider setting `unknown=RAISE` on your Marshmallow schema if you want to explicitly reject unknown input fields. Always implement proper error handling for `schema.load()` to catch `ValidationError` when an invalid enum value is provided.","message":"If you are using `marshmallow-enum` with Marshmallow 3+, ensure you are correctly handling validation errors. Marshmallow 3 defaults to `unknown=EXCLUDE` for `Schema` which means unexpected fields are ignored, but invalid enum values will still raise validation errors. Misconfiguring `unknown` on the schema level can mask or misdirect issues.","severity":"gotcha","affected_versions":"All versions with Marshmallow 3+"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}