Models¶
BaseModel¶
Nearly all concrete models should inherit from BaseModel (or
DateModel/DateRangeModel, which extend it):
from django.db import models
from rn_forge.django.models import BaseModel
class Product(BaseModel):
sku = models.CharField(max_length=32, unique=True)
name = models.CharField(max_length=255)
validate_on_save = True
def natural_keys(self) -> list[str]:
return ["sku"]
BaseModel adds:
status— anEnumFieldover theStatusenum (Active/Inactive/Error/Deleted/Expired), defaulting toActivecreated_by/create_time/updated_by/update_timeaudit columns (snake_case Python fields and columns)objects = NaturalKeyLookupManager()— enablesget_by_natural_key()for fixture loading, driven bynatural_keys()TruncateModelMixin.truncate()—TRUNCATE TABLE(orDELETE FROMon SQLite), handy for test teardown- opt-in validation-on-save: set
validate_on_save = Trueto havesave()callfull_clean(); overrideget_full_clean_exclude()to control which fields are excluded on a partialupdate_fieldssave
Concurrency and immutability¶
Two opt-in mixins, listed before the base so BaseModel's validation still
runs:
from rn_forge.django.models import BaseModel, ImmutableModelMixin, VersionedModelMixin
class Order(VersionedModelMixin, BaseModel):
"""`version` starts at 1 and is bumped by every save of an existing row."""
class LedgerEntry(ImmutableModelMixin, BaseModel):
"""Any change outside the audit columns, and any delete, raises DomainConflict (409)."""
The version bump survives a partial save(update_fields=[...]). The UPDATE
only matches the row at the version the instance was loaded at, so a save from a
stale instance — another request saved in between — raises
rn_forge.web.VersionConflict (412) rather than silently overwriting it.
ImmutableModelMixin re-reads the row on every update — one extra query — and
does not guard queryset-level update()/delete().
Turn a stale write into a 412 from a DRF view, and emit the ETag the client
sends back:
from rn_forge.django.drf import enforce_version, etag_for
def partial_update(self, request, *args, **kwargs):
order = self.get_object()
enforce_version(request, order, required=True) # If-Match, or a body "version" key
response = super().partial_update(request, *args, **kwargs)
order.refresh_from_db()
response["ETag"] = etag_for(order)
return response
A mismatch is 412, a missing required precondition 428, an unparseable
one 400 — decided by rn_forge.web.check_precondition, not here. The
body-version fallback is a Django-only convenience; an API meant to be
swappable with a FastAPI one should require the header.
Soft delete¶
SoftDeleteModelMixin adds a nullable, indexed delete_time. List it
before BaseModel so that its manager becomes the default one; that manager
keeps get_by_natural_key() and adds .live() and .deleted():
from rn_forge.django.models import BaseModel, SoftDeleteModelMixin, VersionedModelMixin
class Note(SoftDeleteModelMixin, VersionedModelMixin, BaseModel):
text = models.CharField(max_length=255)
note.soft_delete(actor="alice") # sets delete_time and updated_by, then saves
note.undelete(actor="bob") # clears delete_time and sets updated_by
Note.objects.live() # delete_time IS NULL
Note.objects.deleted() # delete_time IS NOT NULL
The default manager is not filtered, so the admin, related-object lookups
and a GET of a deleted resource keep working; the view decides what is
visible. A versioned model bumps its version on soft_delete and undelete
as on any save. Override get_delete_time() to supply the recorded time.
delete_time is independent of status, and Status.Deleted does not mean
soft-deleted. The view side is in DRF Views.
Generating human-readable codes¶
from rn_forge.django.models import AbstractSequenceCounter, SequenceGenerator
class SequenceCounter(AbstractSequenceCounter):
"""Your app owns this model and its migration."""
ORDER_CODES = SequenceGenerator("order_code", counter_model=SequenceCounter, prefix="PO-")
ORDER_CODES.generate() # "PO-000001"
ORDER_CODES.ensure_at_least(5_000) # after an import: the next code is PO-005001
The counter model is abstract because this package ships no migrations; you
declare the concrete model and own its migration. A shape like PO-2026-0001 is
a formatter= you pass, not a default.
What is and is not proven. On PostgreSQL a real sequence (nextval)
allocates the value; elsewhere the counter row is locked with
select_for_update(). The test suite runs on sqlite, which has no row locks, so
only the arithmetic is tested — neither the PostgreSQL path nor behaviour under
concurrent allocation is covered by this package's suite.
Date-based variants¶
from rn_forge.django.models import DateModel, DateRangeModel
class Holiday(DateModel):
"""Adds a single `date` field."""
class Discount(DateRangeModel):
"""Adds `start_date`/`end_date` plus `is_date_range_active`."""
DateRangeModel.is_date_range_active is True when today falls within
[start_date, end_date]; an unset end_date means the range is open-ended.
EnumField¶
from django.db import models
from rn_forge.django.models import BaseEnum, EnumField
class Priority(BaseEnum):
Low = "L"
Medium = "M"
High = "H"
class Task(models.Model):
priority = EnumField.build(enum_type=Priority, default=Priority.Medium)
EnumField is a CharField that round-trips database values through the enum
type. BaseEnum.get_choices() / BaseEnum.lookup(code) return
{"code", "name"} dicts, which pairs with EnumChoiceField on the DRF side
(see Auth and DRF Views).
Other helpers¶
ModelUtils.as_dict(instance)/.to_json(instance)— recursively serialize a model instance (including related objects) to JSON-safe primitives.ModelLookupCache— load a reference table once and resolve foreign keys in O(1) instead of per-row queries:
from rn_forge.django.models import ModelLookupCache
cache = ModelLookupCache()
cache.load(Country, "iso_code")
country = cache.get(Country, "AU")