tessl/pypi-djangorestframework
Web APIs for Django, made easy.
—
Pending
serializers.mddocs/
Serializers
Core serialization framework for converting between Python objects and JSON/XML data formats. Serializers handle validation, type conversion, nested relationships, and provide extensive customization options for data transformation.
Capabilities
Base Serializer
Foundation class providing minimal serialization interface with core validation and save functionality.
class BaseSerializer(Field):
"""
Base serializer class providing core serialization functionality.
Args:
instance: Object instance to serialize (for updates)
data: Input data to validate and deserialize
many (bool): Handle multiple objects if True
context (dict): Additional context for serialization
"""
def __init__(self, instance=None, data=empty, **kwargs): ...
def is_valid(self, raise_exception=False):
"""
Validate input data.
Args:
raise_exception (bool): Raise ValidationError if invalid
Returns:
bool: True if data is valid
"""
def save(self, **kwargs):
"""
Save validated data by calling create() or update().
Returns:
Object instance created or updated
"""
def create(self, validated_data):
"""
Create new object instance from validated data.
Args:
validated_data (dict): Validated input data
Returns:
Object instance created
"""
def update(self, instance, validated_data):
"""
Update existing object instance with validated data.
Args:
instance: Existing object to update
validated_data (dict): Validated input data
Returns:
Updated object instance
"""
@property
def data(self):
"""Serialized representation of the object."""
@property
def errors(self):
"""Dictionary of validation errors."""
@property
def validated_data(self):
"""Dictionary of validated input data."""Main Serializer
Full-featured serializer class with field declaration, validation, and customization capabilities.
class Serializer(BaseSerializer):
"""
Main serializer class with declarative field definitions.
"""
def to_representation(self, instance):
"""
Convert object instance to native Python datatypes.
Args:
instance: Object to serialize
Returns:
dict: Serialized representation
"""
def to_internal_value(self, data):
"""
Validate and transform input data to internal Python representation.
Args:
data: Input data to validate
Returns:
dict: Validated data
"""
def validate(self, attrs):
"""
Perform object-level validation.
Args:
attrs (dict): Field values after individual validation
Returns:
dict: Validated attributes
"""Model Serializer
Automatically generates fields from Django model definitions with intelligent defaults and relationships.
class ModelSerializer(Serializer):
"""
Serializer that automatically generates fields from Django models.
"""
serializer_field_mapping = {
# Django field -> DRF field mappings
}
class Meta:
model = None # Django model class
fields = None # Fields to include ('__all__' or list)
exclude = None # Fields to exclude
read_only_fields = None # Read-only field names
extra_kwargs = None # Additional field arguments
def build_field(self, field_name, info, model_class, nested_depth):
"""
Build individual serializer field from model field.
Returns:
tuple: (field_class, field_kwargs)
"""
def build_relational_field(self, field_name, relation_info):
"""
Build relational field for model relationships.
Returns:
tuple: (field_class, field_kwargs)
"""
def build_nested_field(self, field_name, relation_info, nested_depth):
"""
Build nested serializer for related objects.
Returns:
tuple: (field_class, field_kwargs)
"""Hyperlinked Model Serializer
Model serializer using hyperlinks for object references instead of primary keys.
class HyperlinkedModelSerializer(ModelSerializer):
"""
ModelSerializer that uses hyperlinked relationships instead of primary keys.
"""
serializer_related_field = HyperlinkedRelatedField
serializer_url_field = HyperlinkedIdentityField
url_field_name = 'url' # Field name for object URL
def build_nested_field(self, field_name, relation_info, nested_depth):
"""Build nested field using hyperlinks."""List Serializer
Handles serialization of lists/querysets of objects with bulk operations support.
class ListSerializer(BaseSerializer):
"""
Serializer for handling lists of objects.
"""
child = None # Child serializer class
allow_empty = True # Allow empty lists
max_length = None # Maximum list length
min_length = None # Minimum list length
def create(self, validated_data):
"""
Create multiple objects from list of validated data.
Args:
validated_data (list): List of validated data dicts
Returns:
list: Created object instances
"""
def update(self, instance, validated_data):
"""
Update multiple objects from list of validated data.
Args:
instance (list): Existing objects to update
validated_data (list): List of validated data dicts
Returns:
list: Updated object instances
"""Validation Methods
Custom validation methods for serializers provide field-level and object-level validation.
# Field-level validation method pattern
def validate_<field_name>(self, value):
"""
Validate individual field value.
Args:
value: Field value to validate
Returns:
Validated value
Raises:
ValidationError: If validation fails
"""
# Object-level validation
def validate(self, attrs):
"""
Validate entire object after field validation.
Args:
attrs (dict): Dictionary of field values
Returns:
dict: Validated attributes dictionary
Raises:
ValidationError: If validation fails
"""Usage Examples
Basic Serializer Usage
from rest_framework import serializers
class BookSerializer(serializers.Serializer):
title = serializers.CharField(max_length=100)
author = serializers.CharField(max_length=50)
publication_date = serializers.DateField()
isbn = serializers.CharField(max_length=13)
def validate_isbn(self, value):
if len(value) != 13:
raise serializers.ValidationError("ISBN must be 13 characters")
return value
def validate(self, data):
if data['publication_date'] > timezone.now().date():
raise serializers.ValidationError("Publication date cannot be in the future")
return data
# Serializing data
book_data = {'title': 'Django Guide', 'author': 'Jane Doe', 'publication_date': '2023-01-01', 'isbn': '1234567890123'}
serializer = BookSerializer(data=book_data)
if serializer.is_valid():
print(serializer.validated_data)Model Serializer Usage
from django.db import models
from rest_framework import serializers
class Book(models.Model):
title = models.CharField(max_length=100)
author = models.CharField(max_length=50)
publication_date = models.DateField()
isbn = models.CharField(max_length=13, unique=True)
class BookSerializer(serializers.ModelSerializer):
class Meta:
model = Book
fields = ['id', 'title', 'author', 'publication_date', 'isbn']
read_only_fields = ['id']
extra_kwargs = {
'isbn': {'validators': [isbn_validator]}
}
# Create object
serializer = BookSerializer(data=book_data)
if serializer.is_valid():
book = serializer.save()
# Update object
book = Book.objects.get(pk=1)
serializer = BookSerializer(book, data=updated_data, partial=True)
if serializer.is_valid():
updated_book = serializer.save()Nested Serialization
class AuthorSerializer(serializers.ModelSerializer):
class Meta:
model = Author
fields = ['id', 'name', 'email']
class BookSerializer(serializers.ModelSerializer):
author = AuthorSerializer(read_only=True)
author_id = serializers.IntegerField(write_only=True)
class Meta:
model = Book
fields = ['id', 'title', 'author', 'author_id', 'publication_date']Constants
# Special values
ALL_FIELDS = '__all__' # Include all model fields
LIST_SERIALIZER_KWARGS = [ # Arguments passed to ListSerializer
'allow_empty', 'child', 'max_length', 'min_length'
]
# Utility functions
def as_serializer_error(exc):
"""Convert exception to serializer error format."""
def raise_errors_on_nested_writes(method_name, serializer, validated_data):
"""Prevent nested writes without explicit handling."""Install with Tessl CLI
npx tessl i tessl/pypi-djangorestframework