Models¶
Base¶
rn_forge.django.models.base
¶
Abstract Django model building blocks.
BaseModel
¶
Bases: Model, TruncateModelMixin, FixtureModelMixin
Abstract base model with status field and audit timestamps.
Uses :class:NaturalKeyLookupManager; database columns take the field names.
get_attrs(attr_getter)
¶
Return a tuple of attribute values extracted by attr_getter.
get_full_clean_exclude(update_fields=None)
classmethod
¶
Return the field names to exclude from full_clean().
natural_key()
¶
Return the current instance values for :meth:natural_keys.
Supports dotted paths and legacy "relation__field" paths. A single
value is returned as a one-element tuple.
natural_keys()
classmethod
¶
Return the list of field names that form this model's natural key.
The corresponding :meth:natural_key always returns a tuple.
save(*, force_insert=False, force_update=False, using=None, update_fields=None)
¶
Optionally validate the model before saving it.
should_validate_on_save()
classmethod
¶
Return whether this model opts into full_clean() during save.
truncate()
classmethod
¶
Truncate the table backing this model.
SQLite falls back to DELETE FROM because it lacks TRUNCATE.
DateModel
¶
Bases: BaseModel
Abstract model that adds a single date field to :class:BaseModel.
get_attrs(attr_getter)
¶
Return a tuple of attribute values extracted by attr_getter.
get_full_clean_exclude(update_fields=None)
classmethod
¶
Return the field names to exclude from full_clean().
natural_key()
¶
Return the current instance values for :meth:natural_keys.
Supports dotted paths and legacy "relation__field" paths. A single
value is returned as a one-element tuple.
natural_keys()
classmethod
¶
Return the list of field names that form this model's natural key.
The corresponding :meth:natural_key always returns a tuple.
save(*, force_insert=False, force_update=False, using=None, update_fields=None)
¶
Optionally validate the model before saving it.
should_validate_on_save()
classmethod
¶
Return whether this model opts into full_clean() during save.
truncate()
classmethod
¶
Truncate the table backing this model.
SQLite falls back to DELETE FROM because it lacks TRUNCATE.
DateRangeModel
¶
Bases: BaseModel
Abstract model with an inclusive date range and an activity property.
end_date is optional; an open-ended range is considered active
indefinitely once start_date is reached.
is_date_range_active
property
¶
Return True when today falls within [start_date, end_date].
get_attrs(attr_getter)
¶
Return a tuple of attribute values extracted by attr_getter.
get_full_clean_exclude(update_fields=None)
classmethod
¶
Return the field names to exclude from full_clean().
natural_key()
¶
Return the current instance values for :meth:natural_keys.
Supports dotted paths and legacy "relation__field" paths. A single
value is returned as a one-element tuple.
natural_keys()
classmethod
¶
Return the list of field names that form this model's natural key.
The corresponding :meth:natural_key always returns a tuple.
save(*, force_insert=False, force_update=False, using=None, update_fields=None)
¶
Optionally validate the model before saving it.
should_validate_on_save()
classmethod
¶
Return whether this model opts into full_clean() during save.
truncate()
classmethod
¶
Truncate the table backing this model.
SQLite falls back to DELETE FROM because it lacks TRUNCATE.
FixtureModelMixin
¶
Abstract mixin that declares the natural_keys() contract.
natural_key()
¶
Return the current instance values for :meth:natural_keys.
Supports dotted paths and legacy "relation__field" paths. A single
value is returned as a one-element tuple.
natural_keys()
classmethod
¶
Return the list of field names that form this model's natural key.
The corresponding :meth:natural_key always returns a tuple.
NaturalKeyLookupManager
¶
Bases: Manager['BaseModel']
Manager that supports natural-key deserialization in Django fixtures.
The model must implement :meth:FixtureModelMixin.natural_keys.
TruncateModelMixin
¶
Mixin that adds a truncate() class method for DDL-level table clearing.
Useful for test teardown. Issues a raw TRUNCATE TABLE statement; use
with care in production.
truncate()
classmethod
¶
Truncate the table backing this model.
SQLite falls back to DELETE FROM because it lacks TRUNCATE.
Concurrency and immutability¶
rn_forge.django.models.concurrency
¶
Opt-in optimistic-concurrency and immutability model mixins.
ImmutableModelMixin
¶
Bases: Model
Abstract mixin that rejects post-creation mutation and deletion.
Saving a changed row raises :class:rn_forge.web.DomainConflict; deleting
always raises. Queryset-level update() and delete() bypass the guard.
VersionedModelMixin
¶
Bases: Model
Abstract mixin adding an optimistic-concurrency version counter.
Existing rows increment from the loaded version, including partial saves.
A concurrent update raises :class:rn_forge.web.VersionConflict.
save(*, force_insert=False, force_update=False, using=None, update_fields=None)
¶
Bump version on update, then delegate to super().save().
Soft delete¶
rn_forge.django.models.soft_delete
¶
Soft-delete model mixin and queryset (AIP-164).
SoftDeleteModelMixin
¶
Bases: Model
Abstract mixin adding a nullable, indexed delete_time column.
List it before :class:~rn_forge.django.models.BaseModel so that its
manager, which adds .live() and .deleted() to the natural-key
manager, is the model's default. That manager is not filtered.
Saving a :class:~rn_forge.django.models.VersionedModelMixin model through
:meth:soft_delete or :meth:undelete bumps its version as any save does.
Sequences¶
rn_forge.django.models.sequences
¶
Database-backed generation of human-readable sequence codes.
AbstractSequenceCounter
¶
Bases: Model
Abstract counter table backing the non-PostgreSQL sequence path.
SequenceGenerator(name, *, counter_model, prefix='', formatter=None, using=None)
¶
Allocate gap-free, human-readable codes from a named database sequence.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
The sequence name. Must match |
required |
counter_model
|
type[AbstractSequenceCounter]
|
The consumer's concrete :class: |
required |
prefix
|
str
|
Passed to formatter. |
''
|
formatter
|
Callable[[str, int], str] | None
|
|
None
|
using
|
str | None
|
A database alias. Defaults to the router's write database for counter_model. |
None
|
Raises:
| Type | Description |
|---|---|
AppException
|
name is not a valid sequence name, at construction or
when :meth: |
default_code_formatter(prefix, value)
¶
Return a six-digit value with a prefix, or the raw value without one.
Fields¶
rn_forge.django.models.fields
¶
Custom Django model fields for rn-forge-django.
EnumField
¶
Bases: EnumFieldBase
CharField that round-trips values through a BaseEnum subclass.
enum_type
property
¶
Return the enum class bound to this field.
build(*, enum_type, default=None, **kwargs)
classmethod
¶
Build an enum-backed field with sensible defaults.
from_db_value(value, expression, connection)
¶
Convert raw database values to enum members.
get_prep_value(value)
¶
Convert enum members to their raw database values.
to_python(value)
¶
Convert assigned values to enum members when possible.
Enums¶
Cache¶
rn_forge.django.models.cache
¶
Caching helpers for model instance lookup.
ModelLookupCache()
¶
Bulk-load model instances for in-memory lookup by selected fields.
Typical use: load a reference table once at startup, then resolve foreign-key values in O(1) rather than issuing per-row queries.
Example::
cache = ModelLookupCache()
cache.load(Country, "iso_code")
country = cache.get(Country, "AU")
Utils¶
rn_forge.django.models.utils
¶
Model serialization helpers for rn-forge-django.
ModelUtils
¶
Utilities for serialising Django model instances.
All methods are static.
as_dict(instance, _seen=None)
staticmethod
¶
Return a plain dict of all concrete fields on instance.
Related model instances are recursively converted. Cycles are broken
by tracking id() of visited instances; a repeated instance is
represented as its string repr instead of being expanded again.
as_json_value(value)
staticmethod
¶
Coerce a model field value to a JSON-safe primitive.
- Primitives (
str,int,float,bool,None) are returned unchanged. - :class:
~datetime.datetime, :class:~datetime.date, and :class:~datetime.timevalues are converted via.isoformat(). - All other types fall back to
str(value).
to_json(instance, *, indent=None)
staticmethod
¶
Serialise instance to a JSON string.