django-object-preferences 0.1.0__py3-none-any.whl

django_object_preferences-0.1.0.dist-info/METADATA

@@ -0,0 +1,512 @@
+Metadata-Version: 2.5
+Name: django-object-preferences
+Version: 0.1.0
+Summary: Preferences stored on any Django model instance, declared with forms
+Project-URL: Homepage, https://github.com/django-mvp/django-object-preferences
+Project-URL: Repository, https://github.com/django-mvp/django-object-preferences
+Project-URL: Issues, https://github.com/django-mvp/django-object-preferences/issues
+Author-email: Samuel Jennings <samuel.scott.jennings@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: django,forms,jsonfield,preferences,settings
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 5.2
+Classifier: Framework :: Django :: 6.0
+Classifier: Framework :: Django :: 6.1
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Requires-Python: <4.0,>=3.12
+Requires-Dist: django>=5.2
+Description-Content-Type: text/markdown
+
+# django-object-preferences
+
+[![Tests](https://github.com/django-mvp/django-object-preferences/actions/workflows/tests.yml/badge.svg)](https://github.com/django-mvp/django-object-preferences/actions/workflows/tests.yml)
+[![Build](https://github.com/django-mvp/django-object-preferences/actions/workflows/build.yml/badge.svg)](https://github.com/django-mvp/django-object-preferences/actions/workflows/build.yml)
+[![Publish](https://github.com/django-mvp/django-object-preferences/actions/workflows/publish.yml/badge.svg)](https://github.com/django-mvp/django-object-preferences/actions/workflows/publish.yml)
+[![Coverage](https://codecov.io/gh/django-mvp/django-object-preferences/branch/main/graph/badge.svg)](https://codecov.io/gh/django-mvp/django-object-preferences)
+[![PyPI](https://img.shields.io/pypi/v/django-object-preferences)](https://pypi.org/project/django-object-preferences/)
+[![Development status](https://img.shields.io/pypi/status/django-object-preferences)](https://pypi.org/project/django-object-preferences/)
+[![Python](https://img.shields.io/pypi/pyversions/django-object-preferences)](https://pypi.org/project/django-object-preferences/)
+[![Django](https://img.shields.io/pypi/djversions/django-object-preferences)](https://pypi.org/project/django-object-preferences/)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Licence](https://img.shields.io/github/license/django-mvp/django-object-preferences)](https://github.com/django-mvp/django-object-preferences/blob/main/LICENSE)
+
+Preferences stored on any Django model instance, declared with forms.
+
+A person's theme, language and profile visibility, or how a project's or a
+dataset's pages behave: settings like these belong to one record and are read
+far more often than they are changed. This package keeps them in a single JSON
+field on the record itself. Any installed app can declare its own group of
+preferences without adding a model, a table or a migration.
+
+> **Status:** early development. Nothing is published yet, and the first
+> release will be 0.1.0.
+
+## Scope & philosophy
+
+django-object-preferences stores small, per-record settings and gives people a
+page to change them. A record can be any model: the user model, or something
+like a project or a dataset. Each app declares the preferences it needs with
+an ordinary Django form, which already says what type each value is, how it is
+validated, what its choices are and what it defaults to. Reading a preference
+costs no extra query, because the values travel with the record.
+
+What it deliberately is not:
+
+- **A home for data the server selects records by.** A value the project filters
+  or orders on belongs in a real column with an index. Whether a profile is
+  public is the usual example. Preferences are read from a record already in
+  hand.
+- **Site-wide settings.** Values that apply to the whole site belong in Django
+  settings or in a package built for that, such as django-constance.
+- **A place for anything that sits between two records.** A person's choice
+  about one particular project relates two records, and needs a model of its own.
+- **A user interface framework.** The page it ships is plain Django template
+  markup, which a project or a UI package restyles.
+
+When two designs conflict, the one an experienced Django developer would
+recognise wins over the cleverer one. Forms, model fields and class-based views
+are used the way Django intends, and nothing is added that a project could do
+just as well with what Django already provides.
+
+## Requirements
+
+- Python 3.12 or later.
+- Django 5.2, 6.0 or 6.1.
+
+## Installation
+
+```bash
+pip install django-object-preferences
+```
+
+Then add it to `INSTALLED_APPS`:
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "object_preferences",
+]
+```
+
+## Usage
+
+### Turning preferences on for a model
+
+Add a `PreferencesField` to the model whose records should carry preferences,
+then make and run the migration:
+
+```python
+from django.db import models
+
+from object_preferences.fields import PreferencesField
+
+
+class Project(models.Model):
+    name = models.CharField(max_length=100)
+    preferences = PreferencesField()
+```
+
+The field takes no arguments. It is one JSON column, and a model needs only
+one. Its migration reads `PreferencesField()`, and it is the only migration
+this package ever asks of your project: declaring preferences later adds no
+table and no migration.
+
+Reading `project.preferences` returns a `RecordPreferences`, which belongs to
+that one record and is installed by the field's `PreferencesDescriptor`. It
+knows its `record` and its `field`, and its `stored` property is the
+dictionary the record keeps. A new record stores an empty dictionary, because
+a record holds only the values someone has changed from their defaults:
+
+```python
+project = Project(name="Atlas")
+project.preferences.stored  # {}
+```
+
+The field is not editable, so a `ModelForm` for the model leaves it out.
+
+### Declaring a group of preferences
+
+A group of preferences is an ordinary Django form, and each of its fields is
+one preference. Register it for the model the way you would register a model
+admin, in a module called `preferences.py` inside any installed app. The
+package imports that module for every installed app when Django starts, so the
+project's settings never list it:
+
+```python
+# projects/preferences.py
+from django import forms
+
+from object_preferences.registry import register
+
+from .models import Project
+
+
+@register(Project, name="display")
+class DisplayPreferences(forms.Form):
+    theme = forms.ChoiceField(
+        choices=[("light", "Light"), ("dark", "Dark")], initial="light"
+    )
+    page_size = forms.IntegerField(initial=25, min_value=5, max_value=100)
+    show_archived = forms.BooleanField(required=False)
+```
+
+`register` is the decorator form of `registry.register(model, name, form_class)`,
+where `registry` is the project-wide `PreferenceRegistry`. A group's name is
+unique for its model. Registering returns a `PreferenceGroup`, which knows its
+`model`, its `name` and its `form_class`.
+
+Startup stops with an `ImproperlyConfigured` error that names the problem when
+two groups for one model share a name, when the model has no `PreferencesField`,
+or when the form has a field that refers to other records or carries an upload
+(`ModelChoiceField`, `FileField` and `MultiValueField`, with their subclasses).
+
+To look groups up, ask the registry:
+
+```python
+from object_preferences.registry import registry
+
+registry.get_groups(Project)           # every PreferenceGroup, in registration order
+registry.get_group(Project, "display")  # one group, or a KeyError naming it
+registry.get_field(Project)             # the model's PreferencesField
+```
+
+Groups belong to exactly the model they were registered for. A subclass or a
+proxy of that model does not inherit them.
+
+### Reading preferences
+
+`project.preferences` maps each group's name to a read-only mapping of that
+group's values:
+
+```python
+project.preferences["display"]["theme"]      # "light"
+project.preferences["display"]["page_size"]  # 25
+list(project.preferences)                    # ["display"]
+```
+
+Reading never queries the database, however many preferences it reads, because
+the values travel with the record. Asking for a group or a preference that was
+never declared raises a `KeyError` that names it.
+
+A preference nobody has changed reads its default, and the default comes from
+the field. It is the field's `initial` value. A field with no `initial` reads
+the value an empty submission of the form would give it, so a `BooleanField`
+reads `False`, an optional `DurationField` reads `None` and an optional
+`MultipleChoiceField` reads an empty list. A required field with no `initial`
+reads as empty: an empty string, or `None` for a number or a date. Reading never
+raises for want of a default.
+
+A changed value reads back as the type its field produces, so a `DateField`
+gives a `datetime.date` and a `DecimalField` a `decimal.Decimal`, although the
+record stores them as JSON. Change a field's `initial` and every record that has
+not stored its own value reads the new default, with no migration and no data
+change.
+
+### Changing preferences from code
+
+`change` sets some of a group's preferences and leaves the rest as they were.
+It validates the values with the group's form, and it changes the record in
+memory only, so `save` writes it:
+
+```python
+project.preferences.change("display", theme="dark", page_size=50)
+project.preferences.save()
+```
+
+`save` writes only the preferences, with `update_fields`, so another field you
+changed on the record and have not saved is left alone. Calling it on a record
+that has no primary key raises a `ValueError`, and on one whose key is set but
+that has no row (a UUID key is set before the first save) raises a
+`DatabaseError`. A preference changed to its default
+has no stored value afterwards, so `change("display", theme="light")` removes
+`theme` from what the record stores. Asking to change a preference or a group
+that was never declared raises a `KeyError` that names it.
+
+A value the form rejects raises Django's `ValidationError`, and the record is
+left as it was. Its `error_dict` is keyed by field name, and an error from the
+form's own `clean()` is under `NON_FIELD_ERRORS`. Each error carries the code
+the form gave it, which is what to test for rather than the message:
+
+```python
+from django.core.exceptions import ValidationError
+
+try:
+    project.preferences.change("display", page_size=3)
+except ValidationError as error:
+    error.error_dict["page_size"][0].code  # "min_value"
+```
+
+To work with a whole submission, use the group's form itself. `get_form`
+returns the group's form starting from the record's current values, bound to
+`data` when you pass it, and `apply` validates a bound form and stores its
+values on the record. Both work on their own, so a page can bind the form of
+every group, check them all, then `apply` each and `save` once:
+
+```python
+form = project.preferences.get_form("display", data=request.POST, prefix="display")
+if form.is_valid():
+    project.preferences.apply("display", form)
+    project.preferences.save()
+```
+
+`apply` raises a `TypeError` for a form that is not the group's own, a
+`ValueError` for a form bound to no data, and the same `ValidationError` as
+`change` for an invalid one. Applying a group
+replaces that group's stored values and leaves every other group alone, and it
+drops stored keys that the group no longer declares. A `JSONField` preference is
+stored as the JSON text its form field shows, and reads back as the value you
+set.
+
+### Changing a declaration
+
+Records keep what they stored when you change a form, so removing, renaming or
+tightening a preference never needs a data migration. Reading never raises
+because of what is stored:
+
+- A stored value the field no longer accepts reads the default. That covers a
+  choice you removed, a number above a lowered maximum and a value of a changed
+  type, including one the new field would only accept by converting it, such as
+  a list stored for what is now a text field.
+- A stored preference or group that is no longer declared is ignored. It stays
+  in the stored dictionary until its group is saved.
+- A stored dictionary, or a group's entry in it, that is not a dictionary reads
+  as if nothing were stored.
+- Values are read one by one, so a stored combination that the form's `clean()`
+  would now reject still reads value by value.
+
+Saving a group with `change` or `apply` rewrites that group's stored values
+from the form, so its stale values are cleared. Other groups are left alone.
+Renaming a preference therefore reads the new name's default until a person sets
+it again.
+
+## The preferences page
+
+`PreferencesView` is a page where a person changes a record's preferences. The
+package ships no URL, so you route it in your own `urls.py` and name the model
+with `as_view(model=...)`:
+
+```python
+# urls.py
+from django.urls import path
+from object_preferences.views import PreferencesView
+from projects.models import Project
+
+urlpatterns = [
+    path(
+        "projects/<int:pk>/preferences/",
+        PreferencesView.as_view(model=Project),
+        name="project-preferences",
+    ),
+]
+```
+
+It is a Django `DetailView`, so the record is found by `pk` or `slug`, an
+unknown record is a 404, and `queryset` or `get_queryset()` limits which
+records the page can open. The page shows every group declared for the model as
+a fieldset of its own, each control starting from the stored value or the
+default. A model with no preference field raises `ImproperlyConfigured` naming
+the model, and a record whose model declares no groups opens with no controls.
+
+Saving is all or nothing. The page validates every group with its own form. If
+any is invalid it saves nothing and shows the page again with the values the
+person entered and every error at once. Otherwise it applies each group and
+writes the preferences with one `save`, which touches no other field. Groups
+that declare a preference of the same name keep separate values, because each
+group's controls are prefixed with the group's name.
+
+After a save the person is sent back to the same page. Set `success_url` to
+send them elsewhere:
+
+```python
+PreferencesView.as_view(model=Project, success_url="/projects/")
+```
+
+A success message is added at the `SUCCESS` level when Django's messages
+framework is installed, and saving works without it. Change the wording with
+`success_message`.
+
+The page is the template `object_preferences/preferences_form.html`, a plain
+HTML document with no styling. To use your own, put a template of that name
+earlier on the template path, or set `template_name` on the view. It receives
+`record`, the record, and `forms`, a dictionary of each group's form by group
+name. Render each form inside its own `<fieldset>`, and include
+`{% csrf_token %}` in the `<form>`. The view checks the token itself, so a
+forged post is refused even when the CSRF middleware is not installed.
+
+### Deciding who may use the page
+
+The page applies no access rule of its own. A page you route with no rule is
+open to anyone who can reach its address, who can then read and change that
+record's preferences. Decide who may use it before you route it.
+
+Because `PreferencesView` is an ordinary Django class-based view, Django's own
+tools do the deciding and refuse the way they always do. To require a signed-in
+person, add `LoginRequiredMixin` first:
+
+```python
+from django.contrib.auth.mixins import LoginRequiredMixin
+from object_preferences.views import PreferencesView
+
+
+class ProjectPreferencesView(LoginRequiredMixin, PreferencesView):
+    model = Project
+```
+
+To require a permission, use `PermissionRequiredMixin`. A person without it
+gets a 403 response, and an anonymous visitor is sent to sign in:
+
+```python
+from django.contrib.auth.mixins import PermissionRequiredMixin
+
+
+class ProjectPreferencesView(PermissionRequiredMixin, PreferencesView):
+    model = Project
+    permission_required = "projects.change_project"
+```
+
+To let a person change only some records, test them against the record with
+`UserPassesTestMixin`. Here only the person whose record it is may use the
+page:
+
+```python
+from django.contrib.auth.mixins import UserPassesTestMixin
+
+
+class OwnPreferencesView(UserPassesTestMixin, PreferencesView):
+    model = User
+
+    def test_func(self):
+        return self.request.user == self.get_object()
+```
+
+A test that looks the record up runs before the refusal, so a person who is
+refused can still tell a record that exists (403, or a redirect to sign in)
+from one that does not (404). Where that matters, limit the records in
+`get_queryset()` as below, and every record a person may not use is a 404.
+
+To limit which records the page can open at all, limit them in
+`get_queryset()`. A record outside the queryset is a 404:
+
+```python
+class OwnProjectPreferencesView(LoginRequiredMixin, PreferencesView):
+    model = Project
+
+    def get_queryset(self):
+        return Project.objects.filter(owner=self.request.user)
+```
+
+If you route the view with `as_view()` instead of subclassing it, wrap it with
+Django's decorators:
+
+```python
+from django.contrib.auth.decorators import login_required, permission_required
+
+path(
+    "projects/<int:pk>/preferences/",
+    login_required(
+        permission_required("projects.change_project", raise_exception=True)(
+            PreferencesView.as_view(model=Project)
+        )
+    ),
+    name="project-preferences",
+)
+```
+
+### A page for each person's own preferences
+
+The common case is a page where each signed-in person changes their own
+preferences, at one address with no record id. Return the signed-in person from
+`get_object()`, so the page needs no `model`, and require sign-in:
+
+```python
+from django.contrib.auth.mixins import LoginRequiredMixin
+from object_preferences.views import PreferencesView
+
+
+class MyPreferencesView(LoginRequiredMixin, PreferencesView):
+    """Show the signed-in person their own preferences."""
+
+    def get_object(self, queryset=None):
+        """Return the signed-in person as the record the page is for.
+
+        Args:
+            queryset: Unused, as the record is not looked up.
+
+        Returns:
+            The signed-in person.
+        """
+        return self.request.user
+```
+
+Route it at a path with no record id:
+
+```python
+# urls.py
+urlpatterns = [
+    path("preferences/", MyPreferencesView.as_view(), name="my-preferences"),
+]
+```
+
+Your user model must carry a `PreferencesField`, and the groups must be
+registered for it. An anonymous visitor is sent to `LOGIN_URL`, and a signed-in
+person can only ever reach their own record, because no other is looked up.
+
+## Example project
+
+The repository holds a small Django project in `example/`. It declares groups
+for a project and for a person, reads them, changes them from code, and routes
+both kinds of preferences page: a project's page behind a permission, and each
+person's own page. From a checkout:
+
+```bash
+uv run python manage.py migrate
+uv run python manage.py seed_example
+uv run python manage.py runserver
+```
+
+Open the address it prints to see four projects, the preferences each one
+reads and the dictionary each one stores, which holds only what was changed.
+The last project stored a theme that the form no longer offers, so it reads the
+default theme while the stored column still shows the old value. Each project
+links to its preferences page, and "Your preferences" opens the page for the
+person signed in.
+
+`seed_example` also creates four accounts, each with the password `password`:
+
+| Email | Who they are |
+| --- | --- |
+| `regular.user@example.com` | A person with no permissions. A project's page refuses them. |
+| `regular.user2@example.com` | The same, with a stored notification choice of their own. |
+| `staff.user@example.com` | May change projects, so may use a project's page. |
+| `super.user@example.com` | A superuser. |
+
+Running it again deletes and recreates the projects and the accounts.
+
+## Contributing
+
+Standards for this repository live in
+[CONSTITUTION.md](https://github.com/django-mvp/django-object-preferences/blob/main/CONSTITUTION.md),
+and the vocabulary to use in issues and commits lives in
+[CONTEXT.md](https://github.com/django-mvp/django-object-preferences/blob/main/CONTEXT.md).
+
+```bash
+uv sync
+uv run pytest
+uv run pre-commit install
+```
+
+## Changelog
+
+See [CHANGELOG.md](https://github.com/django-mvp/django-object-preferences/blob/main/CHANGELOG.md).
+
+## License
+
+MIT. See [LICENSE](https://github.com/django-mvp/django-object-preferences/blob/main/LICENSE).

django_object_preferences-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+object_preferences/__init__.py,sha256=c1DlKcKrwMHjcW5ViiZ85p4vVD1LiPTCL9DNxk9ZOJI,76
+object_preferences/apps.py,sha256=8awk4MYgkfMZoFCx555XMmudywFIaUWxv7ouHMgeGTc,910
+object_preferences/fields.py,sha256=ei1Ig2ZfjCmSCC1X0oaKaEAxZyTk1JPXew9SQdOXvto,9909
+object_preferences/registry.py,sha256=fahKSQpLh07zHC8705j_EEGjShfyYEjx25T3vLNN97Q,10421
+object_preferences/views.py,sha256=fFVfNg6mNMtzD7KL9QOm3OfbIDOP48KpMVIVmPd0zBc,4761
+object_preferences/locale/en/LC_MESSAGES/django.po,sha256=mJqA3Vgj9Npv2qzfsafziHQyDy9M0Axrp3ZSRQDX5-w,1174
+object_preferences/templates/object_preferences/preferences_form.html,sha256=R-3zJ74raSDALwWbAkVrcv_e_xkVVWZZ3aP_3ZW2RmE,879
+django_object_preferences-0.1.0.dist-info/METADATA,sha256=yycDq39lnsMqcI9n7C_NscTT7JcQin1ZJsQXbJX0ni0,20828
+django_object_preferences-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+django_object_preferences-0.1.0.dist-info/licenses/LICENSE,sha256=qemtG2b6JtnfvKfiv-3gDEqeaJDv7GBWvcC4a7Qkb74,1072
+django_object_preferences-0.1.0.dist-info/RECORD,,

django_object_preferences-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

django_object_preferences-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Samuel Jennings
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

object_preferences/__init__.py

@@ -0,0 +1 @@
+"""Preferences stored on any Django model instance, declared with forms."""

object_preferences/apps.py

@@ -0,0 +1,24 @@
+"""App configuration for django-object-preferences."""
+
+from django.apps import AppConfig
+from django.utils.module_loading import autodiscover_modules
+from django.utils.translation import gettext_lazy as _
+
+
+class ObjectPreferencesConfig(AppConfig):
+    """What a project gets when it adds this package to INSTALLED_APPS.
+
+    The label is set explicitly rather than left to Django's default, which is
+    the last segment of the module path. Two installed apps whose paths end in
+    the same word collide on that default, and the error names neither of them
+    clearly.
+    """
+
+    name = "object_preferences"
+    label = "object_preferences"
+    verbose_name = _("Object Preferences")
+    default_auto_field = "django.db.models.BigAutoField"
+
+    def ready(self) -> None:
+        """Import each installed app's ``preferences`` module to register its groups."""
+        autodiscover_modules("preferences")

object_preferences/fields.py

@@ -0,0 +1,252 @@
+"""The model field that turns preferences on for a model."""
+
+from collections.abc import Iterator, Mapping, Sequence
+from types import MappingProxyType
+from typing import Any
+
+from django import forms
+from django.core.exceptions import ValidationError
+from django.core.serializers.json import DjangoJSONEncoder
+from django.db import models
+from django.db.models.query_utils import DeferredAttribute
+from django.utils.translation import gettext_lazy as _
+
+from object_preferences.registry import registry
+
+
+class RecordPreferences(Mapping[str, Mapping[str, Any]]):
+    """One record's preferences, as the record's attribute returns them.
+
+    It maps each group name declared for the record's model to a read-only
+    mapping of that group's values.
+
+    Attributes:
+        record: The record the preferences belong to.
+        field: The field that stores them.
+    """
+
+    def __init__(self, record: models.Model, field: "PreferencesField") -> None:
+        """Bind the accessor to a record and the field that stores its preferences.
+
+        Args:
+            record: The record the preferences belong to.
+            field: The field that stores them.
+        """
+        self.record = record
+        self.field = field
+
+    @property
+    def stored(self) -> Any:
+        """The record's stored dictionary, as it is stored."""
+        return self.record.__dict__[self.field.attname]
+
+    def __getitem__(self, name: str) -> Mapping[str, Any]:
+        """Return one group's values, read-only.
+
+        Args:
+            name: The group's name.
+
+        Returns:
+            Each of the group's preferences by name, stored or default.
+
+        Raises:
+            KeyError: If no group of that name is declared for the record's model.
+        """
+        group = registry.get_group(type(self.record), name)
+        stored = self.stored
+        return MappingProxyType(
+            group.read(
+                stored.get(name, {}) if isinstance(stored, dict) else {},
+                self.field.encoder,
+            )
+        )
+
+    def get_form(
+        self, name: str, /, data: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> forms.BaseForm:
+        """Return one group's form, starting from the record's current values.
+
+        Args:
+            name: The group's name.
+            data: Submitted data to bind the form to. The form is unbound when
+                omitted.
+            **kwargs: Further keyword arguments for the form. An ``initial``
+                is laid over the record's current values.
+
+        Returns:
+            An instance of the group's form.
+
+        Raises:
+            KeyError: If no group of that name is declared for the record's model.
+        """
+        group = registry.get_group(type(self.record), name)
+        initial = {**self[name], **kwargs.pop("initial", {})}
+        return group.form_class(data=data, initial=initial, **kwargs)
+
+    def apply(self, name: str, form: forms.BaseForm) -> None:
+        """Replace one group's stored values with those of a submitted form.
+
+        The record is changed in memory only. The group's stored values are
+        rewritten from the form, so a value the form does not declare is
+        dropped. Every other group's stored values are left as they are.
+
+        Args:
+            name: The group's name.
+            form: A bound form of the group's form class.
+
+        Raises:
+            KeyError: If no group of that name is declared for the record's model.
+            TypeError: If the form is not an instance of the group's form class.
+            ValueError: If the form is not bound to submitted data.
+            ValidationError: If the form is not valid, with the form's errors.
+        """
+        group = registry.get_group(type(self.record), name)
+        if not isinstance(form, group.form_class):
+            raise TypeError(
+                f"Expected a {group.form_class.__name__} for group {name!r}, "
+                f"not a {type(form).__name__}."
+            )
+        if not form.is_bound:
+            raise ValueError(f"The form for group {name!r} is not bound to any data.")
+        if not form.is_valid():
+            raise ValidationError(form.errors.as_data())
+        stored = self.stored
+        changed = dict(stored) if isinstance(stored, dict) else {}
+        values = group.to_stored(form, self.field.encoder)
+        if values:
+            changed[name] = values
+        else:
+            changed.pop(name, None)
+        setattr(self.record, self.field.attname, changed)
+
+    def change(self, name: str, /, **values: Any) -> None:
+        """Change some of one group's preferences, keeping the rest as they are.
+
+        The values are validated by the group's form. The record is changed in
+        memory only.
+
+        Args:
+            name: The group's name.
+            **values: The new value of each preference to change, by name.
+
+        Raises:
+            KeyError: If no group of that name is declared for the record's
+                model, or a value names a preference the group does not declare.
+            ValidationError: If the form does not accept a value.
+        """
+        group = registry.get_group(type(self.record), name)
+        fields = group.form_class().fields
+        unknown = [key for key in values if key not in fields]
+        if unknown:
+            raise KeyError(
+                f"No preference {', '.join(map(repr, unknown))} is declared in "
+                f"group {name!r} of {type(self.record)._meta.label}."
+            )
+        data = {**self[name], **values}
+        # Typed values go to the form as they are: a datetime prepared as text
+        # in the active timezone can land in an hour that is ambiguous there.
+        # Only a JSONField needs its value as JSON text.
+        for key, field in fields.items():
+            if isinstance(field, forms.JSONField):
+                data[key] = field.prepare_value(data[key])
+        self.apply(name, self.get_form(name, data=data))
+
+    def save(self) -> None:
+        """Write the record's preferences to the database, and nothing else.
+
+        Raises:
+            ValueError: If the record has no primary key.
+            django.db.DatabaseError: If it has one but no row exists.
+        """
+        self.record.save(update_fields=[self.field.attname], force_update=True)
+
+    def __iter__(self) -> Iterator[str]:
+        """Iterate over the names of the groups declared for the record's model."""
+        return iter(group.name for group in registry.get_groups(type(self.record)))
+
+    def __len__(self) -> int:
+        """Return how many groups are declared for the record's model."""
+        return len(registry.get_groups(type(self.record)))
+
+
+class PreferencesDescriptor(DeferredAttribute):
+    """Return a record's preferences accessor instead of the raw stored value."""
+
+    field: "PreferencesField"
+
+    def __get__(self, instance: models.Model | None, cls: Any = None) -> Any:
+        """Return the accessor for a record, or the descriptor on the class."""
+        if instance is None:
+            return self
+        super().__get__(instance, cls)
+        return RecordPreferences(instance, self.field)
+
+    def __set__(self, instance: models.Model, value: Any) -> None:
+        """Store a dictionary, or the stored dictionary of an accessor."""
+        instance.__dict__[self.field.attname] = PreferencesField.unwrap(value)
+
+
+class PreferencesField(models.JSONField):
+    """The one field a model needs to carry preferences.
+
+    It holds only the values a person has changed, as a dictionary of groups.
+    A record with nothing changed stores an empty dictionary.
+    """
+
+    own_defaults: dict[str, Any] = {
+        "default": dict,
+        "blank": True,
+        "editable": False,
+        "encoder": DjangoJSONEncoder,
+        "verbose_name": _("preferences"),
+        "help_text": _("The preferences this record has changed from their defaults."),
+    }
+
+    descriptor_class = PreferencesDescriptor
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        """Apply this field's defaults to whatever the host did not set.
+
+        Args:
+            *args: Positional arguments for ``JSONField``.
+            **kwargs: Keyword arguments for ``JSONField``, which win over the
+                defaults.
+        """
+        for key, value in self.own_defaults.items():
+            kwargs.setdefault(key, value)
+        super().__init__(*args, **kwargs)
+
+    def deconstruct(self) -> tuple[str, str, Sequence[Any], dict[str, Any]]:
+        """Leave out each keyword argument that still holds the field's own value."""
+        name, path, args, kwargs = super().deconstruct()
+        # Django omits these when they equal its own default, which differs from ours.
+        for key in ("blank", "editable"):
+            kwargs.setdefault(key, getattr(self, key))
+        for key, value in self.own_defaults.items():
+            if key in kwargs and kwargs[key] == value:
+                del kwargs[key]
+        return name, path, args, kwargs
+
+    @staticmethod
+    def unwrap(value: Any) -> Any:
+        """Return the stored dictionary when given an accessor, else the value.
+
+        Args:
+            value: A stored value or a ``RecordPreferences``.
+
+        Returns:
+            The value that is stored.
+        """
+        return value.stored if isinstance(value, RecordPreferences) else value
+
+    def get_prep_value(self, value: Any) -> Any:
+        """Unwrap an accessor before Django prepares the value for the database."""
+        return super().get_prep_value(self.unwrap(value))
+
+    def to_python(self, value: Any) -> Any:
+        """Unwrap an accessor before Django converts the value."""
+        return super().to_python(self.unwrap(value))
+
+    def value_from_object(self, obj: models.Model) -> Any:
+        """Return the stored dictionary rather than the accessor."""
+        return self.unwrap(super().value_from_object(obj))

object_preferences/locale/en/LC_MESSAGES/django.po

@@ -0,0 +1,48 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) YEAR THE PACKAGE'S COPYRIGHT HOLDER
+# This file is distributed under the same license as the PACKAGE package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: PACKAGE VERSION\n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-10-15 07:20-0500\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language-Team: LANGUAGE <LL@li.org>\n"
+"Language: \n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Plural-Forms: nplurals=2; plural=(n != 1);\n"
+
+#: apps.py:19
+msgid "Object Preferences"
+msgstr ""
+
+#: fields.py:201
+msgid "preferences"
+msgstr ""
+
+#: fields.py:202
+msgid "The preferences this record has changed from their defaults."
+msgstr ""
+
+#: templates/object_preferences/preferences_form.html:7
+msgid "Preferences"
+msgstr ""
+
+#: templates/object_preferences/preferences_form.html:11
+#, python-format
+msgid "Preferences for %(record)s"
+msgstr ""
+
+#: templates/object_preferences/preferences_form.html:25
+msgid "Save"
+msgstr ""
+
+#: views.py:35
+msgid "The preferences were saved."
+msgstr ""

object_preferences/registry.py

@@ -0,0 +1,288 @@
+"""Preference groups and the registry that holds them."""
+
+import contextlib
+import json
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from django import forms
+from django.core.exceptions import ImproperlyConfigured, ValidationError
+from django.db import models
+from django.utils.dateparse import parse_date, parse_datetime, parse_time
+
+if TYPE_CHECKING:
+    from object_preferences.fields import PreferencesField
+
+UNSUPPORTED_FIELDS = (
+    forms.ModelChoiceField,
+    forms.FileField,
+    forms.MultiValueField,
+)
+
+# The encoder stores these as ISO strings, which a field with its own
+# input_formats may not accept, so they are parsed before the field cleans them.
+TEMPORAL_PARSERS = (
+    (forms.DateTimeField, parse_datetime),
+    (forms.DateField, parse_date),
+    (forms.TimeField, parse_time),
+)
+
+
+@dataclass(frozen=True)
+class PreferenceGroup:
+    """A named form, declared by one app for one model, whose fields are preferences.
+
+    Attributes:
+        model: The model whose records carry the group.
+        name: The group's name, unique for the model.
+        form_class: The form that declares the group's preferences.
+    """
+
+    model: type[models.Model]
+    name: str
+    form_class: type[forms.BaseForm]
+
+    def defaults(self, form: forms.BaseForm | None = None) -> dict[str, Any]:
+        """Return what each preference reads when nothing is stored for it.
+
+        A preference's default is its field's initial value, or the value the
+        field gives an empty submission when it has none. A required field with
+        neither reads as empty rather than raising.
+
+        Args:
+            form: A form of the group to read the fields from. A fresh one is
+                made when omitted.
+
+        Returns:
+            Each preference's default by name.
+        """
+        if form is None:
+            form = self.form_class()
+        defaults = {}
+        for name, field in form.fields.items():
+            value = form.get_initial_for_field(field, name)
+            if value is None:
+                value = field.widget.value_from_datadict({}, {}, name)
+            try:
+                defaults[name] = field.clean(value)
+            except ValidationError:
+                defaults[name] = field.to_python(value)
+        return defaults
+
+    def read(
+        self, stored: Any, encoder: type[json.JSONEncoder] | None
+    ) -> dict[str, Any]:
+        """Return every preference of the group, typed as its field produces it.
+
+        Args:
+            stored: The values stored for this group. Anything but a dictionary
+                reads as nothing stored. A stored value the field no longer
+                accepts, or would only accept by converting it, reads as the
+                default.
+            encoder: The JSON encoder of the record's preferences field.
+
+        Returns:
+            Each preference's value by name, stored or default.
+        """
+        form = self.form_class()
+        values = self.defaults(form)
+        if not isinstance(stored, dict):
+            return values
+        for name, field in form.fields.items():
+            if name in stored:
+                # Stored data is untrusted and cleaning can raise more than
+                # ValidationError, so no value may break a read (FR-016, SC-004).
+                with contextlib.suppress(Exception):
+                    value = stored[name]
+                    for field_class, parser in TEMPORAL_PARSERS:
+                        if isinstance(field, field_class) and isinstance(value, str):
+                            value = parser(value) or value
+                    cleaned = field.clean(value)
+                    # A field converts some values it was never given, such as a
+                    # list for a CharField, so only a value that stores back the
+                    # same is the one that was written.
+                    if self.encode(field, cleaned, encoder) == stored[name]:
+                        values[name] = cleaned
+        return values
+
+    @staticmethod
+    def encode(
+        field: forms.Field, value: Any, encoder: type[json.JSONEncoder] | None
+    ) -> Any:
+        """Return a cleaned value as the database returns it once stored.
+
+        Args:
+            field: The form field the value was cleaned by.
+            value: The cleaned value.
+            encoder: The JSON encoder of the record's preferences field.
+
+        Returns:
+            The value after a round trip through JSON.
+        """
+        # A JSONField value is kept as its JSON text, so a plain string reads
+        # back as itself. Every other value goes through the encoder whole,
+        # which keeps a datetime's offset.
+        if isinstance(field, forms.JSONField):
+            value = field.prepare_value(value)
+        return json.loads(json.dumps(value, cls=encoder))
+
+    def to_stored(
+        self, form: forms.BaseForm, encoder: type[json.JSONEncoder] | None
+    ) -> dict[str, Any]:
+        """Return what a valid form of the group leaves stored on a record.
+
+        Only values that differ from their default are kept, in the form the
+        database returns them, so that the record reads the same before and
+        after it is saved.
+
+        Args:
+            form: A valid form of the group.
+            encoder: The JSON encoder of the record's preferences field.
+
+        Returns:
+            The values to store, by preference name.
+        """
+        defaults = self.defaults()
+        stored = {}
+        for name, field in form.fields.items():
+            value = form.cleaned_data[name]
+            if value != defaults[name]:
+                stored[name] = self.encode(field, value, encoder)
+        return stored
+
+
+class PreferenceRegistry:
+    """The preference groups declared for each model.
+
+    Attributes:
+        declarations: Each model's groups by name, in registration order.
+    """
+
+    def __init__(self) -> None:
+        """Start with nothing declared."""
+        self.declarations: dict[type[models.Model], dict[str, PreferenceGroup]] = {}
+
+    def get_field(self, model: type[models.Model]) -> "PreferencesField":
+        """Return the one preferences field a model carries.
+
+        Args:
+            model: The model to look at.
+
+        Returns:
+            The model's ``PreferencesField``.
+
+        Raises:
+            ImproperlyConfigured: If the model has none, or more than one.
+        """
+        # fields.py imports this module, so the import cannot sit at the top.
+        from object_preferences.fields import PreferencesField
+
+        fields = [
+            field
+            for field in model._meta.get_fields()
+            if isinstance(field, PreferencesField)
+        ]
+        if len(fields) != 1:
+            raise ImproperlyConfigured(
+                f"{model._meta.label} must have exactly one PreferencesField "
+                f"to carry preferences, but has {len(fields)}."
+            )
+        return fields[0]
+
+    def register(
+        self, model: type[models.Model], name: str, form_class: type[forms.BaseForm]
+    ) -> PreferenceGroup:
+        """Declare a group of preferences for a model.
+
+        Args:
+            model: The model whose records carry the group.
+            name: The group's name, unique for the model.
+            form_class: The form whose fields are the group's preferences.
+
+        Returns:
+            The registered group.
+
+        Raises:
+            ImproperlyConfigured: If the model has no single preferences field,
+                the name is taken, or the form has a field that refers to other
+                records or carries an upload.
+        """
+        try:
+            self.get_field(model)
+        except ImproperlyConfigured as error:
+            raise ImproperlyConfigured(
+                f"Cannot register group {name!r} with {form_class!r}: {error}"
+            ) from error
+        taken = self.declarations.get(model, {}).get(name)
+        if taken is not None:
+            raise ImproperlyConfigured(
+                f"A preference group named {name!r} is already registered for "
+                f"{model._meta.label} with {taken.form_class!r}, so "
+                f"{form_class!r} cannot be registered under it."
+            )
+        for field_name, field in form_class().fields.items():
+            if isinstance(field, UNSUPPORTED_FIELDS):
+                raise ImproperlyConfigured(
+                    f"{form_class.__name__}.{field_name} is a "
+                    f"{type(field).__name__}, which cannot be a preference in "
+                    f"group {name!r} of {model._meta.label}."
+                )
+        group = PreferenceGroup(model, name, form_class)
+        self.declarations.setdefault(model, {})[name] = group
+        return group
+
+    def get_groups(self, model: type[models.Model]) -> list[PreferenceGroup]:
+        """List the groups declared for a model.
+
+        Args:
+            model: The model to list for. Parents and proxies are not included.
+
+        Returns:
+            The groups, in registration order.
+        """
+        return list(self.declarations.get(model, {}).values())
+
+    def get_group(self, model: type[models.Model], name: str) -> PreferenceGroup:
+        """Return one group declared for a model.
+
+        Args:
+            model: The model the group was declared for.
+            name: The group's name.
+
+        Returns:
+            The group.
+
+        Raises:
+            KeyError: If no group of that name was declared for the model.
+        """
+        try:
+            return self.declarations[model][name]
+        except KeyError:
+            raise KeyError(
+                f"No preference group {name!r} is declared for {model._meta.label}."
+            ) from None
+
+
+registry = PreferenceRegistry()
+
+
+def register(
+    model: type[models.Model], *, name: str
+) -> Callable[[type[forms.Form]], type[forms.Form]]:
+    """Register the decorated form as a preference group of the module registry.
+
+    Args:
+        model: The model whose records carry the group.
+        name: The group's name, unique for the model.
+
+    Returns:
+        A decorator that registers the form and returns it unchanged.
+    """
+
+    def decorator(form_class: type[forms.Form]) -> type[forms.Form]:
+        """Register the form and hand it back."""
+        registry.register(model, name, form_class)
+        return form_class
+
+    return decorator

object_preferences/templates/object_preferences/preferences_form.html

@@ -0,0 +1,29 @@
+{% load i18n %}{% get_current_language as language_code %}
+<!DOCTYPE html>
+<html lang="{{ language_code }}">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>{% translate "Preferences" %}</title>
+  </head>
+  <body>
+    <main>
+      <h1>{% blocktranslate %}Preferences for {{ record }}{% endblocktranslate %}</h1>
+      {% if messages %}
+        <ul role="status">
+          {% for message in messages %}<li>{{ message }}</li>{% endfor %}
+        </ul>
+      {% endif %}
+      <form method="post">
+        {% csrf_token %}
+        {% for name, form in forms.items %}
+          <fieldset>
+            <legend>{{ name|capfirst }}</legend>
+            {{ form }}
+          </fieldset>
+        {% endfor %}
+        <button type="submit">{% translate "Save" %}</button>
+      </form>
+    </main>
+  </body>
+</html>

object_preferences/views.py

@@ -0,0 +1,129 @@
+"""The page where a person changes a record's preferences."""
+
+from typing import Any
+
+from django.contrib import messages
+from django.forms import BaseForm
+from django.http import HttpRequest, HttpResponse, HttpResponseRedirect
+from django.utils.decorators import method_decorator
+from django.utils.translation import gettext_lazy as _
+from django.views.decorators.csrf import csrf_protect
+from django.views.generic import DetailView
+
+from object_preferences.fields import RecordPreferences
+from object_preferences.registry import registry
+
+
+@method_decorator(csrf_protect, name="dispatch")
+class PreferencesView(DetailView):
+    """Show every preference group of a record's model and save them together.
+
+    Route it with ``as_view(model=...)``. The view applies no access rule, so a
+    host project composes Django's own mixins or decorators with it.
+
+    Attributes:
+        template_name: The template that renders the page.
+        context_object_name: The name of the record in the template context.
+        success_url: Where to send the person after saving. The page itself
+            when ``None``.
+        success_message: The message added after a save.
+    """
+
+    template_name = "object_preferences/preferences_form.html"
+    context_object_name = "record"
+    success_url: str | None = None
+    success_message = _("The preferences were saved.")
+
+    def get_preferences(self) -> RecordPreferences:
+        """Return the preferences of the record the page is for.
+
+        Returns:
+            The record's preferences accessor.
+
+        Raises:
+            ImproperlyConfigured: If the record's model has no preferences field.
+        """
+        model = self.object._meta.model
+        preferences: RecordPreferences = getattr(
+            self.object, registry.get_field(model).attname
+        )
+        return preferences
+
+    def get_forms(self, data: Any = None) -> dict[str, BaseForm]:
+        """Build the form of every group, prefixed with the group's name.
+
+        Args:
+            data: Submitted data to bind the forms to. They are unbound when
+                omitted.
+
+        Returns:
+            Each group's form by group name, in registration order.
+        """
+        preferences = self.get_preferences()
+        return {
+            name: preferences.get_form(name, data=data, prefix=name)
+            for name in preferences
+        }
+
+    def get_context_data(self, **kwargs: Any) -> dict[str, Any]:
+        """Add the forms of the record's groups unless they were passed in."""
+        if "forms" not in kwargs:
+            kwargs["forms"] = self.get_forms()
+        return super().get_context_data(**kwargs)
+
+    def post(self, request: HttpRequest, *args: Any, **kwargs: Any) -> HttpResponse:
+        """Validate every group's form, then save them all or none.
+
+        Args:
+            request: The request, whose POST data holds every group's values.
+            *args: Positional arguments from the URL.
+            **kwargs: Keyword arguments from the URL.
+
+        Returns:
+            A redirect when every group is valid, else the page with the errors.
+        """
+        self.object = self.get_object()
+        forms = self.get_forms(data=request.POST)
+        # A list rather than all() over a generator, so that every form is
+        # validated before deciding, not only those up to the first invalid one.
+        valid = [form.is_valid() for form in forms.values()]
+        if all(valid):
+            return self.forms_valid(forms)
+        return self.forms_invalid(forms)
+
+    def forms_valid(self, forms: dict[str, BaseForm]) -> HttpResponse:
+        """Apply every group's form to the record, save once and redirect.
+
+        Args:
+            forms: Each group's valid form by group name.
+
+        Returns:
+            A redirect to the success URL.
+        """
+        preferences = self.get_preferences()
+        for name, form in forms.items():
+            preferences.apply(name, form)
+        preferences.save()
+        messages.success(self.request, self.success_message, fail_silently=True)
+        return HttpResponseRedirect(self.get_success_url())
+
+    def forms_invalid(self, forms: dict[str, BaseForm]) -> HttpResponse:
+        """Show the page again with the forms and their errors.
+
+        Args:
+            forms: Each group's bound form by group name.
+
+        Returns:
+            The rendered page.
+        """
+        return self.render_to_response(self.get_context_data(forms=forms))
+
+    def get_success_url(self) -> str:
+        """Send the person to ``success_url``, or back to this page.
+
+        Returns:
+            The URL to redirect to after a save.
+        """
+        if self.success_url:
+            return str(self.success_url)
+        return self.request.path