from django.db import models
from django.utils import timezone


class TimeStampedModel(models.Model):
    """
    Abstract base model that adds created_at and updated_at to every model
    that inherits from it. Never creates its own database table.

    ``created_at`` is ``default=timezone.now`` rather than ``auto_now_add``, and
    the difference is the whole point: ``auto_now_add`` makes the field
    ``editable=False``, so Django *silently discards* any value handed to it.
    That is right for a row the server originates and wrong for the desktop
    client's two whole-list operations.

    Undo of a "clear all" and "fill with example data" both go through
    ``PUT /api/<x>/bulk/``, which deletes the page's rows and re-creates them. If
    the stamp cannot be supplied, every restored row is re-dated to the moment
    of the undo — so anything ordered by creation quietly reorders itself, and
    Quick Capture's inbox is ordered by exactly that. The client now sends
    ``created_at`` on every whole-row write (``rowMeta`` in the front repo's
    ``lib/wire.js``).

    Behaviour is unchanged when the field is absent, which is every other caller:
    ``timezone.now`` is evaluated at insert. Write access is granted per
    serializer — only ``lifey_api``'s drop it from ``read_only_fields``; the
    ``users``, ``waitlist`` and ``newsletter`` serializers keep it read-only, so
    the surface widens exactly where it was meant to.

    ``updated_at`` stays ``auto_now``. Nobody has an argument for backdating a
    modification, and a client that could would be able to lie about it.
    """
    created_at = models.DateTimeField(default=timezone.now)
    updated_at = models.DateTimeField(auto_now=True)

    class Meta:
        abstract = True