Models & Fields

from django.core.exceptions import ValidationError


def validate_isbn13(value):
    """Reject anything that is not a well-formed ISBN-13 (hyphens allowed)."""
    digits = value.replace("-", "")
    if len(digits) != 13 or not digits.isdigit():
        raise ValidationError("An ISBN-13 has exactly 13 digits.", code="invalid_isbn")
    total = sum(int(d) * (3 if i % 2 else 1) for i, d in enumerate(digits[:12]))
    if (10 - total % 10) % 10 != int(digits[12]):
        raise ValidationError("The ISBN-13 check digit is wrong.", code="invalid_isbn")

class Author(models.Model):
    name = models.CharField(max_length=200)
    slug = models.SlugField(max_length=200, unique=True)
    born = models.DateField(null=True, blank=True)
    bio = models.TextField(blank=True)
    website = models.URLField(blank=True)
    orcid = models.CharField(max_length=19, unique=True, null=True, blank=True)
    created_at = models.DateTimeField(auto_now_add=True)

    class Meta:
        ordering = ["name"]

    def __str__(self):
        return self.name

    @classmethod
    def from_db(cls, db, field_names, values, **kwargs):
        instance = super().from_db(db, field_names, values, **kwargs)
        # remember what was loaded; __dict__ is safe even if "name" is deferred
        instance._loaded_name = instance.__dict__.get("name")
        return instance

    @property
    def renamed(self):
        loaded = getattr(self, "_loaded_name", None)
        return loaded is not None and self.__dict__.get("name") != loaded

    def get_absolute_url(self):
        return reverse("catalog:author-detail", kwargs={"slug": self.slug})

class Book(models.Model):
    class Status(models.TextChoices):
        DRAFT = "draft", "Draft"
        PUBLISHED = "published", "Published"
        OUT_OF_PRINT = "out_of_print", "Out of print"

    class Binding(models.IntegerChoices):
        PAPERBACK = 1, "Paperback"
        HARDCOVER = 2, "Hardcover"
        EBOOK = 3, "E-book"

    public_id = models.UUIDField(default=uuid.uuid4, editable=False, unique=True)
    title = models.CharField(max_length=300, help_text="As printed on the cover.")
    slug = models.SlugField(max_length=300, unique=True, blank=True)
    author = models.ForeignKey(Author, on_delete=models.PROTECT, related_name="books")
    isbn = models.CharField(
        "ISBN",
        max_length=17,
        unique=True,
        validators=[validate_isbn13],
        db_comment="ISBN-13, with or without hyphens",
    )
    status = models.CharField(max_length=20, choices=Status, default=Status.DRAFT)
    binding = models.PositiveSmallIntegerField(
        choices=Binding, default=Binding.PAPERBACK
    )
    price = models.DecimalField(
        max_digits=8, decimal_places=2, validators=[MinValueValidator(0)]
    )
    pages = models.PositiveSmallIntegerField(null=True, blank=True)
    published_on = models.DateField(null=True, blank=True)
    tags = TagListField()
    metadata = models.JSONField(default=dict, blank=True)
    stock = models.PositiveIntegerField(db_default=0)
    created_at = models.DateTimeField(db_default=Now(), editable=False)
    updated_at = models.DateTimeField(auto_now=True)
    title_lower = models.GeneratedField(
        expression=Lower("title"),
        output_field=models.CharField(max_length=300),
        db_persist=True,
    )
    cover = models.FileField(upload_to="covers/%Y/%m/", blank=True)

    class Meta:
        ordering = ["-published_on", "title"]
        get_latest_by = "published_on"
        db_table_comment = "Catalogue of books"
        indexes = [
            models.Index(fields=["status", "-published_on"], name="book_status_pub_idx"),
        ]
        constraints = [
            models.CheckConstraint(
                condition=Q(price__gte=0), name="book_price_gte_0"
            ),
        ]

    def __str__(self):
        return self.title

    def get_absolute_url(self):
        return reverse("catalog:book-detail", kwargs={"slug": self.slug})

    @property
    def is_published(self):
        return self.status == self.Status.PUBLISHED

    def clean(self):
        if self.status == self.Status.PUBLISHED and self.published_on is None:
            raise ValidationError(
                {"published_on": "A published book needs a publication date."}
            )

    def save(self, **kwargs):
        if not self.slug:
            self.slug = slugify(self.title)
            update_fields = kwargs.get("update_fields")
            if update_fields is not None:
                kwargs["update_fields"] = {*update_fields, "slug"}
        super().save(**kwargs)

    def delete(self, *args, **kwargs):
        cover = self.cover
        result = super().delete(*args, **kwargs)
        if cover:
            transaction.on_commit(lambda: cover.storage.delete(cover.name))
        return result

import uuid

from django.core.exceptions import ValidationError
from django.core.validators import MinValueValidator
from django.db import models, transaction
from django.db.models import Q
from django.db.models.functions import Lower, Now
from django.urls import reverse
from django.utils.text import slugify

from .fields import TagListField
from .validators import validate_isbn13

INSTALLED_APPS = [
    # ... the default Django apps ...
    "catalog",
]

urlpatterns = [
    path("admin/", admin.site.urls),
    path("catalog/", include("catalog.urls")),
]

$ python manage.py makemigrations catalog
Migrations for 'catalog':
  catalog/migrations/0001_initial.py
    + Create model Author
    + Create model Book
$ python manage.py sqlmigrate catalog 0001

CREATE TABLE "catalog_book" ("id" integer NOT NULL PRIMARY KEY AUTOINCREMENT, "public_id" char(32) NOT NULL UNIQUE,
  "title" varchar(300) NOT NULL, "slug" varchar(300) NOT NULL UNIQUE, "isbn" varchar(17) NOT NULL UNIQUE,
  "status" varchar(20) NOT NULL, "binding" smallint unsigned NOT NULL CHECK ("binding" >= 0),
  "price" decimal NOT NULL, "pages" smallint unsigned NULL CHECK ("pages" >= 0), "published_on" date NULL,
  "tags" text NOT NULL, "metadata" text NOT NULL CHECK ((JSON_VALID("metadata") OR "metadata" IS NULL)),
  "stock" integer unsigned DEFAULT 0 NOT NULL CHECK ("stock" >= 0),
  "created_at" datetime DEFAULT (STRFTIME('%Y-%m-%d %H:%M:%f', 'NOW')) NOT NULL, "updated_at" datetime NOT NULL,
  "title_lower" varchar(300) GENERATED ALWAYS AS (LOWER("title")) STORED, "cover" varchar(100) NOT NULL,
  "author_id" bigint NOT NULL REFERENCES "catalog_author" ("id") DEFERRABLE INITIALLY DEFERRED,
  CONSTRAINT "book_price_gte_0" CHECK ("price" >= '0'));
CREATE INDEX "catalog_book_author_id_b7811fba" ON "catalog_book" ("author_id");
CREATE INDEX "book_status_pub_idx" ON "catalog_book" ("status", "published_on" DESC);

>>> from decimal import Decimal
>>> from catalog.models import Author, Book
>>> author = Author.objects.create(name="Ursula K. Le Guin", slug="ursula-k-le-guin")
>>> book = Book(title="The Dispossessed", author=author, isbn="978-0-306-40615-7",
...             price=Decimal("9.99"), tags=["sf", "classic"])
>>> book.pk, repr(book.slug), type(book.stock).__name__
(None, "''", 'DatabaseDefault')
>>> book.save()
>>> book.pk, book.slug, book.stock, book.title_lower
(1, 'the-dispossessed', 0, 'the dispossessed')
>>> book.refresh_from_db()
>>> book.tags, book.status, book.get_status_display(), book.get_absolute_url()
(['sf', 'classic'], 'draft', 'Draft', '/catalog/books/the-dispossessed/')

$ curl -s -w '\n%{http_code}\n' http://127.0.0.1:8000/catalog/books/the-dispossessed/
book the-dispossessed
200

$ python manage.py test catalog
Found 54 test(s).
System check identified no issues (2 silenced).
Ran 54 tests in 0.088s

OK

class Bad(models.Model):
    foo__bar = models.IntegerField()
    trailing_ = models.IntegerField()

    class Meta:
        app_label = "catalog"

fields.E002: Field names must not contain "__".
fields.E001: Field names must not end with an underscore.

def cover_path(instance, filename):
    return f"covers/{instance.public_id}/{filename}"

class Cover(models.Model):
    public_id = models.UUIDField(default=uuid.uuid4, editable=False)
    image = models.FileField(upload_to=cover_path)

    class Meta:
        app_label = "catalog"

from django.core.validators import RegexValidator

class Review(models.Model):
    headline = models.CharField(
        max_length=100,
        unique_for_date="posted_on",
        error_messages={"unique_for_date": "One review per headline and day."},
    )
    code = models.CharField(
        max_length=8,
        validators=[RegexValidator(r"^[A-Z]{3}-\d{4}$", "Use the form ABC-1234.")],
    )
    posted_on = models.DateField(default=datetime.date.today)

    class Meta:
        app_label = "catalog"

class Measurement(models.Model):
    value = models.DecimalField()  # 6.1+: optional on PostgreSQL, SQLite, Oracle; MySQL still needs both

    class Meta:
        app_label = "catalog"

class NullBlankTests(TestCase):
    @isolate_apps("catalog")
    def test_the_four_combinations(self):
        class Probe(models.Model):
            neither = models.CharField(max_length=5)
            blank_only = models.CharField(max_length=5, blank=True)
            null_only = models.CharField(max_length=5, null=True)
            both = models.CharField(max_length=5, null=True, blank=True)

            class Meta:
                app_label = "catalog"

        def failing_fields(**overrides):
            values = {"neither": "x", "blank_only": "x", "null_only": "x", "both": "x"}
            try:
                Probe(**{**values, **overrides}).full_clean()
            except ValidationError as error:
                return sorted(error.message_dict)
            return []

        self.assertEqual(failing_fields(neither=""), ["neither"])
        self.assertEqual(failing_fields(neither=None), ["neither"])
        self.assertEqual(failing_fields(blank_only=""), [])
        self.assertEqual(failing_fields(null_only=""), ["null_only"])
        self.assertEqual(failing_fields(null_only=None), ["null_only"])
        self.assertEqual(failing_fields(both=None), [])
        self.assertEqual(failing_fields(both=""), [])

    def test_blank_is_validation_null_is_storage(self):
        Author(name="x", slug="x", bio="").full_clean()  # blank=True accepts ""
        with self.assertRaises(ValidationError) as caught:
            Author(name="", slug="x").full_clean()
        self.assertEqual(caught.exception.message_dict["name"], ["This field cannot be blank."])
        with self.assertRaises(IntegrityError), transaction.atomic():
            Author.objects.create(name=None, slug="y")  # save() validates nothing

    def test_unique_and_blank_needs_null(self):
        Author.objects.create(name="a", slug="")
        with self.assertRaises(IntegrityError), transaction.atomic():
            Author.objects.create(name="b", slug="")  # "" collides with ""
        Author.objects.create(name="c", slug="c", orcid=None)
        Author.objects.create(name="d", slug="d", orcid=None)  # NULLs never collide
        self.assertEqual(Author.objects.filter(orcid__isnull=True).count(), 3)

    def test_modelform_stores_none_for_null_char_fields(self):
        class AuthorForm(forms.ModelForm):
            class Meta:
                model = Author
                fields = ["name", "slug", "orcid"]

        form = AuthorForm({"name": "n", "slug": "n", "orcid": ""})
        self.assertTrue(form.is_valid())
        self.assertIsNone(form.cleaned_data["orcid"])

class Status(models.TextChoices):
    DRAFT = "draft", "Draft"
    PUBLISHED = "published", "Published"
    OUT_OF_PRINT = "out_of_print", "Out of print"

class Binding(models.IntegerChoices):
    PAPERBACK = 1, "Paperback"
    HARDCOVER = 2, "Hardcover"
    EBOOK = 3, "E-book"

class ChoicesTests(TestCase):
    def test_enumeration_api(self):
        self.assertEqual(Book.Status.choices[0], ("draft", "Draft"))
        self.assertEqual(Book.Status.values, ["draft", "published", "out_of_print"])
        self.assertEqual(Book.Status.labels, ["Draft", "Published", "Out of print"])
        self.assertEqual(Book.Status.names, ["DRAFT", "PUBLISHED", "OUT_OF_PRINT"])
        self.assertEqual(Book.Status("published").label, "Published")
        self.assertEqual(Book.Binding.HARDCOVER.value, 2)
        self.assertEqual(Book.Status.DRAFT, "draft")  # a str as well as an enum member

    def test_display_and_filtering(self):
        make_book(status=Book.Status.PUBLISHED, published_on=datetime.date(1974, 5, 1),
                  binding=Book.Binding.EBOOK)
        book = Book.objects.get(status=Book.Status.PUBLISHED)
        self.assertEqual(book.get_status_display(), "Published")
        self.assertEqual(book.get_binding_display(), "E-book")
        self.assertTrue(book.is_published)

    def test_choices_are_enforced_by_validation_not_by_save(self):
        book = make_book()
        book.status = "bogus"
        book.save()  # no error: save() does not validate
        with self.assertRaises(ValidationError) as caught:
            book.full_clean()
        self.assertEqual(caught.exception.error_dict["status"][0].code, "invalid_choice")
        self.assertEqual(book.get_status_display(), "bogus")  # falls back to the raw value

    def test_blank_choice_label_in_6_1(self):
        class StatusForm(forms.ModelForm):
            class Meta:
                model = Book
                fields = ["status"]

        self.assertNotIn("Select an option", str(StatusForm()["status"]))  # has a default

        @isolate_apps("catalog")
        def render_without_default():
            class Probe(models.Model):
                kind = models.CharField(max_length=5, choices=Book.Status)

                class Meta:
                    app_label = "catalog"

            return Probe._meta.get_field("kind").formfield().widget.render("kind", None)

        self.assertIn("- Select an option -", render_without_default())

def currencies():
    return {"EUR": "Euro", "USD": "US dollar"}

MEDIA_CHOICES = {
    "Audio": {"vinyl": "Vinyl", "cd": "CD"},
    "Video": {"vhs": "VHS Tape", "dvd": "DVD"},
    "unknown": "Unknown",
}

class Purchase(models.Model):
    currency = models.CharField(max_length=3, choices=currencies)
    media = models.CharField(max_length=7, choices=MEDIA_CHOICES, default="cd")

    class Meta:
        app_label = "catalog"

class Vehicle(models.TextChoices):
    CAR = "C"
    JET_SKI = "J"

class Answer(models.IntegerChoices):
    NO = 0, _("No")
    YES = 1, _("Yes")
    __empty__ = _("(Unknown)")

Medal = models.TextChoices("Medal", "GOLD SILVER BRONZE")

BEGIN;
--
-- Alter field status on book
--
-- (no-op)
COMMIT;

class Broken(models.Model):
    payload = models.JSONField(default={})  # one dict shared by every instance

    class Meta:
        app_label = "catalog"

fields.E010: JSONField default should be a callable instead of an instance so that it's not shared between all field instances.

class Event(models.Model):
    payload = models.JSONField(default=dict, encoder=DjangoJSONEncoder)

    class Meta:
        app_label = "catalog"

class JsonFieldTests(TestCase):
    def test_round_trip_and_key_lookups(self):
        make_book(metadata={"awards": ["Hugo", "Nebula"], "series": {"name": "Hainish", "no": 5}})
        book = Book.objects.get()
        self.assertEqual(book.metadata["series"]["no"], 5)
        self.assertTrue(Book.objects.filter(metadata__has_key="awards").exists())
        self.assertTrue(Book.objects.filter(metadata__series__name="Hainish").exists())
        self.assertTrue(Book.objects.filter(metadata__awards__0="Hugo").exists())
        self.assertTrue(Book.objects.filter(metadata__series__no__gte=3).exists())

    def test_json_null_is_not_sql_null(self):
        book = make_book(metadata=JSONNull())  # the JSON scalar null (6.1)
        book.refresh_from_db()
        self.assertIsNone(book.metadata)
        self.assertTrue(Book.objects.filter(metadata=JSONNull()).exists())
        self.assertFalse(Book.objects.filter(metadata__isnull=True).exists())

class Square(models.Model):
    side = models.IntegerField()
    label = models.CharField(max_length=20, db_default="Square")
    created = models.DateTimeField(db_default=Now())
    circumference = models.FloatField(db_default=2 * Pi())
    area = models.GeneratedField(
        expression=F("side") * F("side"),
        output_field=models.BigIntegerField(),
        db_persist=True,
    )
    shout = models.GeneratedField(
        expression=Lower("label"),
        output_field=models.CharField(max_length=20),
        db_persist=False,  # virtual: computed on read (PostgreSQL 18+, SQLite, MySQL)
    )

    class Meta:
        app_label = "catalog"

CREATE TABLE "catalog_square" ("id" integer NOT NULL PRIMARY KEY AUTOINCREMENT, "side" integer NOT NULL,
  "label" varchar(20) DEFAULT 'Square' NOT NULL,
  "created" datetime DEFAULT (STRFTIME('%Y-%m-%d %H:%M:%f', 'NOW')) NOT NULL,
  "circumference" real DEFAULT ((2 * PI())) NOT NULL,
  "area" bigint GENERATED ALWAYS AS (("side" * "side")) STORED,
  "shout" varchar(20) GENERATED ALWAYS AS (LOWER("label")) VIRTUAL);

class DefaultsTests(TestCase):
    def test_defaults_slug_and_database_computed_values(self):
        book = make_book()
        book.refresh_from_db()
        self.assertEqual(book.slug, "the-dispossessed")  # set by save()
        self.assertEqual(book.status, Book.Status.DRAFT)  # default=
        self.assertEqual(book.stock, 0)  # db_default=0
        self.assertIsNotNone(book.created_at)  # db_default=Now()
        self.assertEqual(book.title_lower, "the dispossessed")  # GeneratedField
        self.assertEqual(book.tags, [])  # callable default
        self.assertEqual(book.metadata, {})

    def test_unsaved_instance_holds_a_database_default_placeholder(self):
        book = Book(title="t")
        self.assertIsInstance(book.stock, DatabaseDefault)
        self.assertFalse(book._is_pk_set())

    def test_generated_field_is_refreshed_and_read_only(self):
        book = make_book()
        self.assertEqual(book.title_lower, "the dispossessed")  # no refresh needed (6.0+)
        book.title = "THE LEFT HAND OF DARKNESS"
        book.save()
        self.assertEqual(book.title_lower, "the left hand of darkness")
        book.title_lower = "ignored"  # the database owns this column
        book.save()
        book.refresh_from_db()
        self.assertEqual(book.title_lower, "the left hand of darkness")

    def test_auto_now_only_runs_for_fields_that_are_saved(self):
        book = make_book()
        first = book.updated_at
        book.pages = 400
        book.save()
        self.assertGreater(book.updated_at, first)
        stamp = Book.objects.get().updated_at
        book.pages = 401
        book.save(update_fields=["pages"])  # updated_at not listed: not touched
        Book.objects.update(pages=5)  # update() never calls pre_save()
        self.assertEqual(Book.objects.get().updated_at, stamp)

class Edition(models.Model):
    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
    label = models.CharField(max_length=50)

    class Meta:
        app_label = "catalog"

class Release(models.Model):
    pk = models.CompositePrimaryKey("version", "name")
    version = models.IntegerField()
    name = models.CharField(max_length=20)

    class Meta:
        app_label = "catalog"

class ValidationTests(TestCase):
    def test_validators(self):
        validate_isbn13(ISBN)
        validate_isbn13("9780306406157")
        book = Book(title="t", isbn="978-0-306-40615-8", price=Decimal("-1"), author=make_author())
        with self.assertRaises(ValidationError) as caught:
            book.full_clean(exclude=["slug"])
        self.assertEqual(caught.exception.error_dict["isbn"][0].code, "invalid_isbn")
        self.assertIn("price", caught.exception.message_dict)  # MinValueValidator(0)

    def test_clean_reports_a_field_error(self):
        book = make_book(status=Book.Status.PUBLISHED)
        with self.assertRaises(ValidationError) as caught:
            book.full_clean()
        self.assertEqual(
            caught.exception.message_dict,
            {"published_on": ["A published book needs a publication date."]},
        )
        book.published_on = datetime.date(1974, 5, 1)
        book.full_clean()

    def test_validate_unique_is_part_of_full_clean(self):
        make_book()
        duplicate = Book(title="Other", slug="other", isbn=ISBN, price=1, author=Author.objects.get())
        with self.assertRaises(ValidationError) as caught:
            duplicate.full_clean()
        self.assertEqual(caught.exception.message_dict["isbn"], ["Book with this ISBN already exists."])

    def test_check_constraint_in_python_and_in_the_database(self):
        book = make_book()
        book.price = Decimal("-5")
        with self.assertRaises(ValidationError):
            book.validate_constraints()
        with self.assertRaises(IntegrityError), transaction.atomic():
            Book.objects.filter(pk=book.pk).update(price=-5)  # update() skips Python checks

class Book(models.Model):
    title = models.CharField(max_length=300)

    class Meta:
        app_label = "catalog"

class Edition(models.Model):
    book = models.ForeignKey(Book, on_delete=models.CASCADE)
    number = models.PositiveSmallIntegerField()
    released = models.DateField(null=True)

    class Meta:
        app_label = "catalog"
        db_table = "catalog_edition"
        verbose_name = "edition"
        verbose_name_plural = "editions"
        ordering = [F("released").desc(nulls_last=True), "number"]
        default_related_name = "editions"
        permissions = [("can_reprint", "Can reprint an edition")]
        default_permissions = ("add", "change", "view")
        constraints = [
            models.UniqueConstraint(fields=["book", "number"], name="edition_book_number_uniq"),
        ]

class LegacyBook(models.Model):
    isbn = models.CharField(max_length=17, primary_key=True)
    title = models.CharField(max_length=300)

    class Meta:
        app_label = "catalog"
        managed = False  # a table or view created by someone else
        db_table = "legacy_books"

class Hardback(LegacyBook):
    class Meta:
        app_label = "catalog"
        proxy = True
        ordering = ["title"]

class Novel(models.Model):
    title = models.CharField(max_length=300)

    class Meta:
        app_label = "catalog"

class Chapter(models.Model):
    novel = models.ForeignKey(Novel, on_delete=models.CASCADE)
    title = models.CharField(max_length=100)

    class Meta:
        app_label = "catalog"
        order_with_respect_to = "novel"

class Seat(models.Model):
    row = models.CharField(max_length=2)
    number = models.PositiveSmallIntegerField()

    class Meta:
        app_label = "catalog"
        unique_together = [["row", "number"]]  # older spelling, still supported

class MetaTests(TestCase):
    def test_meta_options(self):
        opts = Book._meta
        self.assertEqual(opts.db_table, "catalog_book")
        self.assertEqual(opts.label, "catalog.Book")
        self.assertEqual(opts.ordering, ["-published_on", "title"])
        self.assertEqual(opts.get_latest_by, "published_on")
        self.assertEqual(opts.get_field("isbn").verbose_name, "ISBN")
        self.assertEqual(opts.get_field("isbn").db_comment, "ISBN-13, with or without hyphens")
        self.assertIn("title_lower", [field.name for field in opts.get_fields()])
        self.assertEqual(Book.objects.all().query.order_by, ())  # Meta.ordering applies at compile time

class AsyncTests(TestCase):
    async def test_async_methods(self):
        author = await Author.objects.acreate(name="n", slug="n")
        book = Book(title="Async", isbn=ISBN, price=1, author=author)
        await book.asave()
        book.pages = 7
        await book.asave(update_fields=["pages"])
        await book.arefresh_from_db()
        self.assertEqual(book.pages, 7)
        loaded = await Book.objects.select_related("author").aget(pk=book.pk)
        self.assertEqual(loaded.author.name, "n")
        await book.adelete()
        self.assertEqual(await Book.objects.acount(), 0)

    async def test_synchronous_orm_calls_are_refused_in_async_code(self):
        with self.assertRaises(SynchronousOnlyOperation):
            Author.objects.count()
        self.assertEqual(await Author.objects.acount(), 0)

    async def test_validation_that_queries_must_run_in_a_thread(self):
        author = await Author.objects.acreate(name="n", slug="n")
        book = Book(title="t", slug="t", isbn=ISBN, price=1, author=author)
        with self.assertRaises(SynchronousOnlyOperation):
            book.full_clean()  # validate_unique() and validate_constraints() hit the database
        await sync_to_async(book.full_clean)()

from django import forms
from django.db import models


class TagListFormField(forms.CharField):
    """Shows a list of tags as 'a, b, c' in a text input."""

    def prepare_value(self, value):
        if isinstance(value, (list, tuple)):
            return ", ".join(value)
        return value

    def to_python(self, value):
        value = super().to_python(value)
        return [tag.strip() for tag in value.split(",") if tag.strip()]


class TagListField(models.TextField):
    """A list of short tags stored in one TEXT column, joined by a separator."""

    description = "A list of tags stored as one separated string"

    def __init__(self, *args, separator=",", **kwargs):
        self.separator = separator
        kwargs.setdefault("default", list)
        kwargs.setdefault("blank", True)
        super().__init__(*args, **kwargs)

    def deconstruct(self):
        name, path, args, kwargs = super().deconstruct()
        if self.separator != ",":
            kwargs["separator"] = self.separator
        return name, path, args, kwargs

    def from_db_value(self, value, expression, connection):
        return self.to_python(value)

    def to_python(self, value):
        if value is None:
            return []
        if isinstance(value, (list, tuple)):
            return list(value)
        return [tag.strip() for tag in value.split(self.separator) if tag.strip()]

    def get_prep_value(self, value):
        if value is None or isinstance(value, str):
            return value
        return self.separator.join(tag.strip() for tag in value if tag.strip())

    def value_to_string(self, obj):
        return self.get_prep_value(self.value_from_object(obj))

    def formfield(self, **kwargs):
        kwargs.setdefault("form_class", TagListFormField)
        return super().formfield(**kwargs)

class SeparatedField(models.TextField):
    def __init__(self, *args, separator=",", **kwargs):
        self.separator = separator
        super().__init__(*args, **kwargs)

    @property
    def non_db_attrs(self):
        return super().non_db_attrs + ("separator",)

class Money(models.Field):
    def db_type(self, connection):
        return "numeric(12, 2)" if connection.vendor == "postgresql" else "decimal"

class CustomFieldTests(TestCase):
    def test_round_trip_and_storage(self):
        book = make_book(tags=["sf", " classic ", ""])
        self.assertEqual(book.tags, ["sf", " classic ", ""])  # unchanged until reloaded
        book.refresh_from_db()
        self.assertEqual(book.tags, ["sf", "classic"])
        with connection.cursor() as cursor:
            cursor.execute("SELECT tags FROM catalog_book")
            self.assertEqual(cursor.fetchone()[0], "sf,classic")
        self.assertTrue(Book.objects.filter(tags__contains="classic").exists())
        self.assertTrue(Book.objects.filter(tags="sf,classic").exists())

    def test_deconstruct(self):
        field = Book._meta.get_field("tags")
        _name, path, _args, kwargs = field.deconstruct()
        self.assertEqual(path, "catalog.fields.TagListField")
        self.assertNotIn("separator", kwargs)
        self.assertEqual(TagListField(separator=";").deconstruct()[3]["separator"], ";")
        clone = TagListField(**TagListField(separator=";").deconstruct()[3])
        self.assertEqual(clone.separator, ";")

    def test_serialization_uses_value_to_string(self):
        data = serializers.serialize("json", [make_book(tags=["sf", "classic"])])
        self.assertIn('"tags": "sf,classic"', data)
        self.assertEqual(next(serializers.deserialize("json", data)).object.tags, ["sf", "classic"])

    def test_form_field_round_trip(self):
        class BookForm(forms.ModelForm):
            class Meta:
                model = Book
                fields = ["title", "isbn", "price", "author", "tags", "status"]

        form = BookForm({"title": "T", "isbn": ISBN, "price": "3", "author": make_author().pk,
                         "tags": "a, b ,c", "status": "draft"})
        self.assertTrue(form.is_valid(), form.errors)
        self.assertEqual(form.cleaned_data["tags"], ["a", "b", "c"])
        self.assertEqual(form.fields["tags"].prepare_value(["a", "b"]), "a, b")