or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

decorators-hooks.mdexceptions-utils.mdfield-types.mdindex.mdschema-definition.mdvalidation.md
tile.json

tessl/pypi-marshmallow

A lightweight library for converting complex datatypes to and from native Python datatypes

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/marshmallow@4.0.x

To install, run

npx @tessl/cli install tessl/pypi-marshmallow@4.0.0

index.mddocs/

Marshmallow

An ORM/ODM/framework-agnostic Python library for converting complex datatypes to and from native Python datatypes. Marshmallow provides object serialization and deserialization with comprehensive schema definition, validation, and data transformation capabilities.

Package Information

  • Package Name: marshmallow
  • Language: Python
  • Installation: pip install marshmallow

Core Imports

import marshmallow
from marshmallow import Schema, fields, ValidationError

Common pattern for schema definition:

from marshmallow import Schema, fields
from marshmallow import validate

Basic Usage

from datetime import date
from marshmallow import Schema, fields

class ArtistSchema(Schema):
    name = fields.Str()

class AlbumSchema(Schema):
    title = fields.Str()
    release_date = fields.Date()
    artist = fields.Nested(ArtistSchema())

# Create schema instance
schema = AlbumSchema()

# Serialize (dump) Python objects to JSON-compatible data
album = {
    "artist": {"name": "David Bowie"}, 
    "title": "Hunky Dory", 
    "release_date": date(1971, 12, 17)
}
result = schema.dump(album)
# {"artist": {"name": "David Bowie"}, "title": "Hunky Dory", "release_date": "1971-12-17"}

# Deserialize (load) JSON-compatible data to Python objects
json_data = {"artist": {"name": "Pink Floyd"}, "title": "Dark Side of the Moon", "release_date": "1973-03-01"}
result = schema.load(json_data)

# Validate data without loading
errors = schema.validate({"title": "Invalid Album"})  # Missing required fields

Architecture

Marshmallow's design centers around Schemas and Fields:

  • Schema: Defines the structure and rules for serialization/deserialization of complex objects
  • Fields: Handle conversion and validation of individual data elements
  • Validation: Comprehensive validation framework with built-in and custom validators
  • Processing Hooks: Decorators for custom data transformation before/after serialization
  • Error Handling: Structured validation errors with detailed field-level messages

This architecture enables flexible data transformation pipelines suitable for web APIs, data persistence, configuration management, and integration with frameworks like Flask, Django, and FastAPI.

Capabilities

Schema Definition and Management

Core schema functionality for defining object serialization/deserialization rules, including schema configuration, field management, and data processing methods.

class Schema:
    def dump(self, obj, many=None): ...
    def dumps(self, obj, many=None): ...
    def load(self, json_data, many=None, partial=None, unknown=None): ...
    def loads(self, json_str, many=None, partial=None, unknown=None): ...
    def validate(self, json_data, many=None, partial=None, unknown=None): ...

class SchemaOpts:
    def __init__(self, meta, **kwargs): ...

Schema Definition

Field Types and Data Conversion

Comprehensive field types for handling strings, numbers, dates, containers, relationships, and specialized data formats with validation and transformation capabilities.

class Field:
    def __init__(self, *, dump_default=missing, load_default=missing, data_key=None, 
                 attribute=None, validate=None, required=False, allow_none=None, 
                 load_only=False, dump_only=False, error_messages=None, metadata=None): ...

# String and Text Fields
class String(Field): ...
class Email(Field): ...
class URL(Field): ...
class UUID(Field): ...

# Numeric Fields  
class Integer(Field): ...
class Float(Field): ...
class Decimal(Field): ...

# Date/Time Fields
class DateTime(Field): ...
class Date(Field): ...
class Time(Field): ...

# Container Fields
class List(Field): ...
class Dict(Field): ...
class Nested(Field): ...

Field Types

Validation Framework

Built-in validators for common patterns and custom validation support, including string validation, numeric ranges, collection constraints, and schema-level validation.

class Validator:
    def __call__(self, value): ...

# String Validators
class Email(Validator): ...
class URL(Validator): ...
class Regexp(Validator): ...

# Numeric Validators
class Range(Validator): ...

# Collection Validators
class Length(Validator): ...
class OneOf(Validator): ...
class ContainsOnly(Validator): ...

Validation

Processing Decorators and Hooks

Decorators for custom data transformation and validation logic that execute before and after serialization/deserialization operations.

def pre_dump(pass_collection=False): ...
def post_dump(pass_collection=False, pass_original=False): ...
def pre_load(pass_collection=False): ...
def post_load(pass_collection=False, pass_original=False): ...
def validates(*field_names): ...
def validates_schema(pass_collection=False, pass_original=False, skip_on_field_errors=True): ...

Decorators and Hooks

Error Handling and Utilities

Exception types for validation errors, utility functions for data manipulation, and helper classes for advanced use cases.

class ValidationError(Exception):
    def __init__(self, message, field_name=None, data=None, valid_data=None, **kwargs): ...

class MarshmallowError(Exception): ...
class RegistryError(Exception): ...

# Utility Functions
def get_value(obj, key, default=missing): ...
def set_value(dct, key, value): ...
def pluck(dictlist, key): ...

Exceptions and Utilities

Constants

Unknown Field Handling

EXCLUDE = "exclude"  # Ignore unknown fields
INCLUDE = "include"  # Include unknown fields in output
RAISE = "raise"      # Raise ValidationError for unknown fields

Missing Value Sentinel

missing = <missing>  # Sentinel for missing/undefined values