Marshmallow OneOfSchema

Warnings

• breaking marshmallow-oneofschema v2.0.0 and later require Marshmallow v3.x. Attempting to use it with Marshmallow v2.x will result in `ImportError` or other runtime errors due to API changes in Marshmallow.
  Fix: Ensure your project's Marshmallow dependency is `marshmallow>=3.0.0`. Upgrade Marshmallow if necessary (e.g., `pip install 'marshmallow>=3.0.0'`).
• breaking The API for defining polymorphic schemas changed significantly in v2.0.0. The `type_map` attribute was removed and replaced by `type_schemas` and `type_field` for clearer definition of type mappings and the discriminator field.
  Fix: If migrating from v1.x, update your schema definition from `type_map = {'type_name': SchemaClass}` to `type_schemas = {'type_name': SchemaClass}` and explicitly set `type_field = 'discriminator_field_name'`.
• gotcha Incorrectly specifying or omitting the `type_field` attribute or providing data without this field will lead to deserialization failures (`ValidationError`), as `OneOfSchema` won't know which sub-schema to use.
  Fix: Always define `type_field` in your `OneOfSchema` subclass, ensuring it matches the field name in your input data that determines the object's type. For input data, make sure the `type_field` is present and its value exactly matches a key in `type_schemas`.
• gotcha Attempting to serialize or deserialize an object whose type (as indicated by `type_field`) is not present as a key in the `type_schemas` dictionary will result in an error (`ValueError` for dump, `ValidationError` for load).
  Fix: Ensure all possible object types that your `OneOfSchema` might encounter are explicitly listed as keys in `type_schemas`, mapped to their respective Marshmallow schema classes. Handle unknown types upstream if they are not expected to be processed by this schema.

Install

• pip install marshmallow-oneofschema Install stable version

Imports

• OneOfSchema

  from marshmallow_oneofschema import OneOfSchema

Quickstart

This quickstart demonstrates how to define a `OneOfSchema` to handle different types of pet objects (Cat and Dog). It shows how to map type identifiers to specific Marshmallow schemas using `type_schemas` and how to specify the discriminator field using `type_field`. It also includes examples of both serialization (`dump`) and deserialization (`load`), and demonstrates handling an unknown type during deserialization.

from marshmallow import Schema, fields
from marshmallow_oneofschema import OneOfSchema

class CatSchema(Schema):
    name = fields.String(required=True)
    lives = fields.Integer(load_default=9)

class DogSchema(Schema):
    name = fields.String(required=True)
    breed = fields.String()

class PetSchema(OneOfSchema):
    type_schemas = {
        "cat": CatSchema,
        "dog": DogSchema,
    }
    type_field = "pet_type" # Discriminator field in input data

# Example data
cat_data = {"pet_type": "cat", "name": "Whiskers", "lives": 7}
dog_data = {"pet_type": "dog", "name": "Buddy", "breed": "Golden Retriever"}
unknown_pet_data = {"pet_type": "fish", "name": "Nemo"}

# Instantiate the polymorphic schema
pet_schema = PetSchema()

# Serialization (dump)
serialized_cat = pet_schema.dump(cat_data)
print(f"Serialized Cat: {serialized_cat}")

serialized_dog = pet_schema.dump(dog_data)
print(f"Serialized Dog: {serialized_dog}")

# Deserialization (load)
loaded_cat = pet_schema.load(serialized_cat)
print(f"Loaded Cat: {loaded_cat}")

loaded_dog = pet_schema.load(serialized_dog)
print(f"Loaded Dog: {loaded_dog}")

try:
    # This will raise a ValidationError because 'fish' is not in type_schemas
    pet_schema.load(unknown_pet_data)
except Exception as e:
    print(f"Error loading unknown type: {e}")