Skip to content

Home Information - Your home, your data, organized.

Python
9.7 KB
Raw Blame
"""
Custom Django model fields for common patterns.
"""
from django.core.exceptions import ValidationError
from django.db import models

from .enums import LabeledEnum


class LabeledEnumDescriptor:
    """
    A descriptor that automatically converts values to enum instances.
    
    This handles the automatic conversion when setting/getting field values
    on model instances.
    """
    
    def __init__(self, field):
        self.field = field
    
    def __get__(self, instance, owner):
        if instance is None:
            return self.field
        
        # Get the raw value from the instance's __dict__
        value = instance.__dict__.get(self.field.attname)
        
        if value is None:
            return None
        
        # Convert to enum if it's a string
        if isinstance(value, str):
            try:
                return self.field._convert_from_string(value)
            except (ValueError, ValidationError):
                # If conversion fails with safe mode, it returns default
                # If conversion fails with strict mode, return the string
                # (will fail on validation)
                if self.field.use_safe_conversion:
                    return self.field.enum_class.default()
                return value
        
        # If it's already an enum, return it
        if isinstance(value, self.field.enum_class):
            return value
        
        # Try to convert other types
        try:
            return self.field.to_python(value)
        except (ValueError, ValidationError):
            if self.field.use_safe_conversion:
                return self.field.enum_class.default()
            return value
    
    def __set__(self, instance, value):
        # Store the raw value for now, conversion happens on get
        # This matches Django's behavior for other fields
        instance.__dict__[self.field.attname] = value


class LabeledEnumField(models.CharField):
    """
    A Django model field for storing LabeledEnum values.
    
    This field:
    - Stores enum values as lowercase strings in the database (VARCHAR)
    - Accepts enum instances or strings when setting values
    - Returns enum instances when accessing values
    - Validates that values are valid enum members
    - Does NOT require migrations when enum values change
    
    Usage:
        class MyModel(models.Model):
            # Use safe conversion (returns default for invalid values)
            status = LabeledEnumField(StatusType, max_length=32)
            
            # Use strict conversion (raises ValueError for invalid values)
            priority = LabeledEnumField(PriorityType, max_length=32, use_safe_conversion=False)
            
        # Can set with enum instance
        obj.status = StatusType.ACTIVE
        
        # Can set with string (case-insensitive)
        obj.status = 'active'
        obj.status = 'ACTIVE'
        
        # Always returns enum instance
        assert obj.status == StatusType.ACTIVE
        assert isinstance(obj.status, StatusType)
    """
    
    description = "A field for storing LabeledEnum values as lowercase strings"
    
    def __init__(self, enum_class, *args, use_safe_conversion=True, **kwargs):
        """
        Initialize the field.
        
        Args:
            enum_class: The LabeledEnum subclass this field stores
            use_safe_conversion: If True, use from_name_safe() which returns default for invalid values.
                               If False, use from_name() which raises ValueError for invalid values.
                               Default is True for backward compatibility and safety.
        """
        if not issubclass(enum_class, LabeledEnum):
            raise TypeError(f"{enum_class} must be a subclass of LabeledEnum")
        
        self.enum_class = enum_class
        self.use_safe_conversion = use_safe_conversion
        
        # Set default max_length if not provided
        if 'max_length' not in kwargs:
            # Calculate max length from enum values
            max_len = max(len(str(e)) for e in enum_class)
            kwargs['max_length'] = max(32, max_len + 10)  # Add buffer, min 32
        
        # Set choices for Django admin
        kwargs['choices'] = enum_class.choices()
        
        # Set default if the enum has one and no default was provided
        if 'default' not in kwargs and hasattr(enum_class, 'default'):
            kwargs['default'] = str(enum_class.default())
        
        super().__init__(*args, **kwargs)
    
    def _convert_from_string(self, value):
        """
        Convert string value to enum instance using configured conversion method.
        
        Args:
            value: String value to convert
            
        Returns:
            Enum instance
            
        Raises:
            ValueError: If use_safe_conversion is False and value is invalid
        """
        if self.use_safe_conversion:
            return self.enum_class.from_name_safe(value)
        else:
            return self.enum_class.from_name(value)
    
    def deconstruct(self):
        """
        Return enough information to recreate the field.
        Required for migrations.
        """
        name, path, args, kwargs = super().deconstruct()
        # Store the enum class path for reconstruction
        kwargs['enum_class'] = self.enum_class
        kwargs['use_safe_conversion'] = self.use_safe_conversion
        return name, path, args, kwargs
    
    def from_db_value(self, value, expression, connection):
        """
        Convert database value to Python enum instance.
        Called when fetching from database.
        """
        if value is None:
            return None
        
        try:
            return self._convert_from_string(value)
        except ValueError as e:
            # This should rarely happen with database values
            # but if it does, we want to know about it
            raise ValidationError(
                f"Invalid database value '{value}' for {self.enum_class.__name__}: {e}"
            )
    
    def to_python(self, value):
        """
        Convert input value to Python enum instance.
        Called during deserialization and clean().
        """
        if value is None:
            return None
        
        if isinstance(value, self.enum_class):
            return value
        
        if isinstance(value, str):
            try:
                return self._convert_from_string(value)
            except ValueError as e:
                raise ValidationError(
                    f"Invalid value '{value}' for {self.enum_class.__name__}: {e}"
                )
        
        # Try to convert other types to string first
        try:
            return self._convert_from_string(str(value))
        except (TypeError, ValueError) as e:
            raise ValidationError(
                f"Cannot convert {value!r} to {self.enum_class.__name__}: {e}"
            )
    
    def get_prep_value(self, value):
        """
        Convert Python value to database value.
        Called before saving to database.
        """
        if value is None:
            return None
        
        if isinstance(value, self.enum_class):
            # Convert enum to lowercase string
            return str(value)
        
        if isinstance(value, str):
            # Ensure lowercase
            # First validate it's a valid enum value
            try:
                enum_instance = self._convert_from_string(value)
                return str(enum_instance)
            except ValueError as e:
                raise ValidationError(
                    f"Invalid value '{value}' for {self.enum_class.__name__}: {e}"
                )
        
        # Try to convert to enum first for validation
        try:
            enum_instance = self.to_python(value)
            return str(enum_instance) if enum_instance else None
        except ValidationError:
            # Re-raise with clear message
            raise ValidationError(
                f"Value {value!r} is not valid for {self.enum_class.__name__}"
            )
    
    def value_to_string(self, obj):
        """
        Convert value to string for serialization.
        Used by dumpdata and other serializers.
        """
        value = self.value_from_object(obj)
        if value is None:
            return None
        return str(value)
    
    def validate(self, value, model_instance):
        """
        Validate that the value is a valid enum member.
        Called during model validation.
        """
        super().validate(value, model_instance)
        
        if value is None and not self.null:
            raise ValidationError("This field cannot be null.")
        
        if value is not None:
            # Ensure it's a valid enum value
            if not isinstance(value, self.enum_class):
                try:
                    # Try to convert it
                    self.to_python(value)
                except ValidationError as e:
                    raise ValidationError(
                        f"Invalid value for {self.enum_class.__name__}: {e}"
                    )
    
    def contribute_to_class(self, cls, name, **kwargs):
        """
        Add field to model class with custom descriptor for automatic conversion.
        """
        super().contribute_to_class(cls, name, **kwargs)
        # Set up the descriptor for this field
        setattr(cls, name, LabeledEnumDescriptor(self))


class NullableLabeledEnumField(LabeledEnumField):
    """
    A nullable version of LabeledEnumField.
    
    Convenience class that sets null=True, blank=True by default.
    """
    
    def __init__(self, enum_class, *args, **kwargs):
        kwargs.setdefault('null', True)
        kwargs.setdefault('blank', True)
        super().__init__(enum_class, *args, **kwargs)