API Reference

class PydanticJSONField[T: BaseModel](JSONField[dict[str, object]]):
    """JSONField that round-trips values through a Pydantic model.

    On save, serializes ``BaseModel`` instances with ``model_dump(mode="json")``
    before JSON encoding. On load, validates decoded data with the configured
    Pydantic model, including:

    - JSON strings or bytes (typical for SQLite).
    - Plain dicts returned by PostgreSQL JSONB drivers such as asyncpg.

    Examples:
        >>> class MyModel(Model):
        ...     data: PydanticJSONField[MyPydanticModel] = PydanticJSONField(
        ...         MyPydanticModel, default=MyPydanticModel
        ...     )
    """

    def __init__(self, model_class: type[T], **kwargs: Any) -> None:
        """Initialize the field.

        Args:
            model_class: Pydantic model class used for validation.
            **kwargs: Additional arguments forwarded to ``JSONField``.
        """
        self._pydantic_model: type[T] = model_class
        super().__init__(**kwargs)

    @override
    def to_python_value(self, value: Any) -> T | None:  # pyright: ignore[reportExplicitAny, reportIncompatibleMethodOverride]
        """Convert a database value to a Pydantic model instance.

        Args:
            value: Raw value from the database driver.

        Returns:
            A validated Pydantic model, or ``None`` when the value is null.
        """
        if value is None:
            return None
        if isinstance(value, self._pydantic_model):
            return value
        if isinstance(value, (str, bytes)):
            raw = value if isinstance(value, str) else value.decode()
            return self._pydantic_model.model_validate_json(raw)
        return self._pydantic_model.model_validate(value)

    @override
    def to_db_value(self, value: Any, instance: type[Model] | Model) -> str | None:  # pyright: ignore[reportExplicitAny]
        """Convert a Python value to a JSON string for storage.

        Args:
            value: Model instance or JSON-serializable data.
            instance: Tortoise model class or instance (unused).

        Returns:
            Encoded JSON string, or ``None`` when the value is null.
        """
        if isinstance(value, BaseModel):
            value = value.model_dump(mode="json")
        return super().to_db_value(value, instance)

class FutureUUIDField(fields.Field[UUID], UUID):  # pyright: ignore[reportUnsafeMultipleInheritance]
    """UUID field compatible with UUID v6+ and the ``uuid6`` package.

    Stores UUIDs as ``CHAR(36)`` on most backends and as native ``UUID`` on
    PostgreSQL. When used as a primary key without an explicit ``default``,
    assigns UUID7 via ``uuid6.uuid7``.

    Examples:
        >>> class Item(Model):
        ...     id: FutureUUIDField = FutureUUIDField(primary_key=True)
        ...     class Meta:
        ...         table = "items"
    """

    SQL_TYPE = "CHAR(36)"

    class _db_postgres:
        SQL_TYPE = "UUID"

    def __init__(self, **kwargs: Any) -> None:  # pyright: ignore[reportExplicitAny]
        """Initialize the field.

        Args:
            **kwargs: Tortoise field options. Primary keys without ``default``
                receive ``uuid7`` automatically.
        """
        if kwargs.pop("pk", False):
            kwargs["primary_key"] = True
        if kwargs.get("primary_key") and "default" not in kwargs:
            kwargs["default"] = uuid7
        super().__init__(**kwargs)

    @override
    def to_db_value(self, value: Any, instance: type[Model] | Model) -> str | None:  # pyright: ignore[reportExplicitAny]
        """Convert a UUID to its string database representation.

        Args:
            value: UUID value or other supported input.
            instance: Tortoise model class or instance (unused).

        Returns:
            String UUID, or ``None`` when the value is falsy.
        """
        return value and str(value)

    @override
    def to_python_value(self, value: Any) -> UUID | None:  # pyright: ignore[reportExplicitAny]
        """Convert a database value to a ``uuid6.UUID`` instance.

        Args:
            value: Raw value from the database driver.

        Returns:
            Parsed UUID, or ``None`` when the value is null.
        """
        if value is None:
            return None
        if isinstance(value, UUID):
            return value
        return UUID(str(value))