django-form-matrix 0.1.0__tar.gz

django_form_matrix-0.1.0/.github/workflows/compat-matrix.yml

@@ -0,0 +1,27 @@
+name: Compatibility Matrix
+
+on:
+  push:
+    branches: [master, main]
+  pull_request:
+    branches: [master, main]
+
+jobs:
+  tox:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Install Python versions
+        run: uv python install 3.10 3.12 3.13 3.14
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Run compatibility matrix (tox)
+        run: uv run tox run

django_form_matrix-0.1.0/.github/workflows/js-tests.yml

@@ -0,0 +1,24 @@
+name: JavaScript Tests
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run Tests & Coverage
+        run: npm run coverage

django_form_matrix-0.1.0/.github/workflows/pre-commit.yml

@@ -0,0 +1,28 @@
+name: Pre-commit
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      # The hooks run on python3.14 (default_language_version), found
+      # through the venv's bin on PATH under `uv run`.
+      - name: Set up Python
+        run: uv python install 3.14
+
+      - name: Install dependencies
+        run: uv sync --python 3.14
+
+      - name: Run pre-commit
+        run: uv run pre-commit run --all-files

django_form_matrix-0.1.0/.github/workflows/pytest.yml

@@ -0,0 +1,31 @@
+name: Python and Playwright Tests
+
+on:
+  push:
+    branches: [master, main]
+  pull_request:
+    branches: [master, main]
+
+jobs:
+  test-python:
+    name: Python Tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Install Playwright browsers
+        run: uv run playwright install --with-deps chromium
+
+      - name: Run Pytest
+        run: uv run pytest

django_form_matrix-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,55 @@
+name: Release
+
+on:
+  release:
+    types:
+      - published
+
+jobs:
+  release-build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Show project version
+        run: |
+          grep "version" pyproject.toml
+
+      - name: Build release distributions
+        run: uv build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+  pypi-publish:
+    runs-on: ubuntu-latest
+    needs:
+      - release-build
+    permissions:
+      id-token: write
+      contents: read
+
+    environment:
+      name: pypi
+      url: https://pypi.org/project/django-form-matrix/
+
+    steps:
+      - name: Retrieve release distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+      - name: Publish release distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

django_form_matrix-0.1.0/.gitignore

@@ -0,0 +1,42 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Testing / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+coverage/
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+.tox/
+
+# Django
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+media/
+
+# Node / JS
+node_modules/
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store
+
+# Docs
+docs/_build/

django_form_matrix-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,66 @@
+default_language_version:
+  python: &python-version python3.14
+
+repos:
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: 3e8a8703264a2f4a69428a0aa4dcb512790b2c8c  # frozen: v6.0.0
+  hooks:
+  - id: check-added-large-files
+  - id: check-case-conflict
+  - id: check-json
+  - id: check-merge-conflict
+  - id: check-symlinks
+  - id: check-toml
+  - id: debug-statements
+  - id: end-of-file-fixer
+  - id: trailing-whitespace
+
+- repo: https://github.com/biomejs/pre-commit
+  rev: d1ce4972fb5ad09afd33b432bca71e8c5dfbb2b5  # frozen: v2.5.6
+  hooks:
+  - id: biome-check
+    additional_dependencies:
+    - '@biomejs/biome@2.3.8'
+    language_version: default
+
+- repo: https://github.com/adamchainz/django-upgrade
+  rev: bdcc9646c249f00ec9781751791e7b75b48b3722  # frozen: 1.31.1
+  hooks:
+  - id: django-upgrade
+    args: [--target-version, "4.2"]
+
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  rev: 39d9ac5938dadb73df0564a45f163e25ff9fa6e2  # frozen: v0.16.1
+  hooks:
+  - id: ruff-check
+    args: [--fix]
+  - id: ruff-format
+
+- repo: local
+  hooks:
+  - id: mypy
+    name: mypy
+    entry: mypy
+    language: python
+    additional_dependencies:
+    - mypy>=1.10
+    - django-stubs[compatible-mypy]>=5
+    - django>=4.2
+    - pytest-django>=4.8
+    types: [python]
+    files: ^(src|example)/
+    pass_filenames: false
+    args: [src/django_form_matrix, example]
+
+# Only needed if the library ships Django templates (src/<pkg>/templates/).
+# Remove this hook if it doesn't.
+- repo: https://github.com/adamchainz/djade-pre-commit
+  rev: 52a7ce253113456c2a1113186a4a19b15c8b68af  # frozen: 1.9.0
+  hooks:
+  - id: djade
+    files: '(/|^)templates/'
+
+- repo: https://github.com/tox-dev/pyproject-fmt
+  rev: d600c142bb19f521ae6a6a345f94a2efd7937759  # frozen: v2.26.0
+  hooks:
+  - id: pyproject-fmt

django_form_matrix-0.1.0/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-10-17
+
+### Added
+
+- `MatrixField`, `MatrixWidget`, `Row` and `Column`: a table of rows and
+  columns with a form field in every cell, optional collapsible sections and
+  shortcuts to check a row, a column or a section.
+- `django_form_matrix.contrib.permissions`: `PermissionMultipleChoiceField`,
+  the permissions of an app/model/action in a matrix.
+- Blocks in `matrix.html` and `permissions.html` (`section_summary`,
+  `column_heading`, `cell`...) to extend them changing only a piece.
+- `django_form_matrix.contrib.unfold.UnfoldMatrixMixin`: the matrix on
+  django-unfold's palette (light and dark).
+- Spanish translation.

django_form_matrix-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,113 @@
+# Contributing
+
+## Development setup
+
+With [uv](https://docs.astral.sh/uv/) (recommended):
+
+```bash
+uv sync
+uv run playwright install --with-deps chromium
+npm install
+uv run pre-commit install
+```
+
+Without uv:
+
+```bash
+pip install -e ".[dev]"
+playwright install --with-deps chromium
+npm install
+pre-commit install
+```
+
+## Running the example project
+
+```bash
+cd example
+python manage.py migrate
+python manage.py createsuperuser
+python manage.py runserver
+```
+
+## Tests
+
+Python (pytest + pytest-django, coverage always on via `addopts`):
+
+```bash
+uv run pytest
+```
+
+`tests/e2e/` (real-browser tests via pytest-playwright, driving a real
+Chromium against `live_server`) runs as part of that same `uv run pytest`
+— no separate command. They need `uv run playwright install chromium`
+once (see Setup above) and are slower than the rest of the suite;
+everything else under `tests/` is unit/integration-level and doesn't
+touch a browser.
+
+JavaScript (vitest + jsdom):
+
+```bash
+npm test
+npm run coverage
+```
+
+## Compatibility matrix (tox)
+
+`uv run pytest` above only runs against whatever Django version `uv.lock`
+resolved (the newest one satisfying `dependencies`). To check the full
+supported range — every Django series in `classifiers`, against the
+oldest and newest Python it supports (within this package's own
+`requires-python` floor) — run the tox matrix instead:
+
+```bash
+uv run tox run-parallel   # every env, in parallel
+uv run tox -e py314-dj52  # a single env, e.g. to debug one failure
+```
+
+`[tool.tox]` in `pyproject.toml` lists the exact envs. Each one gets its own ephemeral venv (via
+[tox-uv](https://github.com/tox-dev/tox-uv), using uv's own Python
+builds — `uv python install <version>` once for any you don't have yet)
+with only `pytest`/`pytest-django`/`pytest-cov` and that env's pinned
+Django, not the full `dev` group, and skips `tests/e2e/` (no Playwright
+in those envs). This only tests boundaries (oldest + newest Python per
+Django series), not every valid combination — that catches most real
+breakage while staying fast. Runs in CI as a separate
+`compat-matrix.yml` workflow, alongside the regular `pytest.yml`. Update
+the `env_list` here whenever `classifiers` gains or drops a Django
+series.
+
+## Lint / format / type-check
+
+```bash
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy src example
+# or, everything at once:
+uv run pre-commit run --all-files
+```
+
+The mypy pre-commit hook runs against the project venv (it needs
+django-stubs to resolve model types), not an isolated pre-commit env.
+
+## Before opening a PR
+
+- [ ] `uv run pytest`
+- [ ] `npm test`
+- [ ] `uv run pre-commit run --all-files`
+
+## Translations
+
+Catalogs live in `src/django_form_matrix/locale/`. After changing
+translatable text, from that package directory:
+
+```bash
+cd src/django_form_matrix
+DJANGO_SETTINGS_MODULE=tests.settings PYTHONPATH=../..:../../example \
+  uv run django-admin makemessages -l es --no-obsolete --add-location file --no-wrap
+# translate the new/changed entries in locale/es/LC_MESSAGES/django.po, then:
+DJANGO_SETTINGS_MODULE=tests.settings PYTHONPATH=../..:../../example \
+  uv run django-admin compilemessages
+```
+
+Commit both the `.po` and the compiled `.mo`. `tests/test_i18n.py` fails if
+an entry is untranslated or fuzzy, or if the `.mo` doesn't match the `.po`.

django_form_matrix-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rodolfo Becerra
+
+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.

django_form_matrix-0.1.0/PKG-INFO

@@ -0,0 +1,217 @@
+Metadata-Version: 2.5
+Name: django-form-matrix
+Version: 0.1.0
+Summary: A form field to fill a table of rows and columns, with a form field in every cell (checkboxes, numbers, choices...), plus a ready-made permission matrix.
+Project-URL: Homepage, https://github.com/rodolvbg/django-form-matrix
+Project-URL: Issues, https://github.com/rodolvbg/django-form-matrix/issues
+Project-URL: Repository, https://github.com/rodolvbg/django-form-matrix
+Author-email: Rodolfo Valentín Becerra García <rodolvbg@gmail.com>
+Maintainer-email: Rodolfo Valentín Becerra García <rodolvbg@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: admin,checkbox,django,form,grid,matrix,permissions,widget
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Framework :: Django :: 5.1
+Classifier: Framework :: Django :: 5.2
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: django>=4.2
+Provides-Extra: dev
+Requires-Dist: coverage[toml]>=7.4; extra == 'dev'
+Requires-Dist: django-stubs[compatible-mypy]>=5; extra == 'dev'
+Requires-Dist: django-unfold>=0.60; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pre-commit>=4; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest-django>=4.8; extra == 'dev'
+Requires-Dist: pytest-playwright>=0.5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: tox-uv>=1; extra == 'dev'
+Requires-Dist: tox>=4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# django-form-matrix
+
+[![Build status](https://github.com/rodolvbg/django-form-matrix/actions/workflows/pytest.yml/badge.svg)](https://github.com/rodolvbg/django-form-matrix/actions/workflows/pytest.yml)
+[![PyPI version](https://img.shields.io/pypi/v/django-form-matrix.svg)](https://pypi.org/project/django-form-matrix/)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/django-form-matrix)](https://pypi.org/project/django-form-matrix/)
+[![PyPI - Django Version](https://img.shields.io/pypi/djversions/django-form-matrix)](https://pypi.org/project/django-form-matrix/)
+[![Downloads](https://static.pepy.tech/personalized-badge/django-form-matrix?period=month&units=international_system&left_color=black&right_color=blue&left_text=Downloads/month)](https://pepy.tech/project/django-form-matrix)
+
+A Django form field to fill a **table**: one row per item, one column per property and, in every cell, a form field of its own — a checkbox, a number, a choice, text. Rows can be grouped in collapsible sections, and checkbox columns get shortcuts to check a row, a column or a whole section.
+
+It works in any Django form and in the admin. A ready-made **permission matrix** (apps → models → add/view/change/delete) is included as a use case.
+
+![A matrix with checkboxes, numbers and choices in its cells, in two sections](https://raw.githubusercontent.com/rodolvbg/django-form-matrix/HEAD/docs/screenshots/hero.png)
+
+## Installation
+
+```bash
+pip install django-form-matrix
+```
+
+Add `django_form_matrix` to `INSTALLED_APPS` (it ships a template, a script and a stylesheet):
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "django_form_matrix",
+]
+```
+
+## Quick start
+
+```python
+from django import forms
+from django_form_matrix import Column, MatrixField, Row
+
+
+class PlanForm(forms.Form):
+    features = MatrixField(
+        rows=[
+            Row("invoices", "Invoices", section="Billing"),
+            Row("quotes", "Quotes", section="Billing"),
+            Row("exports", "Exports", section="Analytics", columns=["enabled"]),
+        ],
+        columns=[
+            Column("enabled", "Enabled"),  # a checkbox unless said otherwise
+            Column(
+                "limit",
+                "Monthly limit",
+                forms.IntegerField(min_value=0, required=False),
+            ),
+        ],
+    )
+```
+
+Render the form as usual and add `{{ form.media }}` (the admin does it for you). The cleaned value has one entry per row with the cells that exist:
+
+```python
+form.cleaned_data["features"]
+# {"invoices": {"enabled": True, "limit": 50},
+#  "quotes": {"enabled": False, "limit": None},
+#  "exports": {"enabled": False}}
+```
+
+That is what a `JSONField` stores, so a `ModelForm` can save it directly.
+
+### Rows and columns
+
+- `Column(key, label, field=BooleanField(required=False))`: the form field of the column. Its validation and its widget are Django's own, and a failing cell is reported with its row and column ("Invoices, Monthly limit: …").
+- `Row(key, label, section=None, columns=None)`: `section` groups rows under a collapsible heading (rows without one go in a plain table); `columns` are the keys of the columns that have a cell in this row, the rest show a dash.
+- `MatrixField(rows=…, columns=…)` is not required by default; with `required=True` at least one cell needs a value. `rows` and `columns` can be reassigned in a form's `__init__` to build the matrix dynamically.
+
+Each cell is submitted as `<name>__<row key>__<column key>`, so it reads like any other widget.
+
+### Shortcuts
+
+Checkbox columns get a checkbox in their heading, every row with checkboxes gets one at its start, and each section gets an "All". They show whether their cells are all, some or none checked, and the heading of a section counts the checked ones. A section opens by itself when something in it is filled.
+
+## Permissions
+
+```python
+from django_form_matrix.contrib.permissions import PermissionMultipleChoiceField
+
+
+class RoleAdmin(admin.ModelAdmin):
+    def formfield_for_manytomany(self, db_field, request, **kwargs):
+        if db_field.name == "permissions":
+            kwargs["form_class"] = PermissionMultipleChoiceField
+        return super().formfield_for_manytomany(db_field, request, **kwargs)
+```
+
+![The permission matrix in the admin](https://raw.githubusercontent.com/rodolvbg/django-form-matrix/HEAD/docs/screenshots/permissions.png)
+
+One section per app, one row per model and a column per action; the other permissions of a model go in an "Others" column. It submits like a `CheckboxSelectMultiple`, so validation and saving do not change, and the names of the permissions are shown translated. Needs `django.contrib.auth`. [docs/examples/permissions.md](https://github.com/rodolvbg/django-form-matrix/blob/HEAD/docs/examples/permissions.md) shows how to build the same matrix by hand with `MatrixField`, with rows that come from the database, for when you need more control.
+
+## Customizing the HTML
+
+Both templates are split in blocks, so a template of yours can extend one and change only a piece, without copying the rest:
+
+```django
+{% extends "django_form_matrix/matrix.html" %}
+{% block section_summary %}<strong>{{ section.name }}</strong>{% endblock %}
+{% block cell %}<div class="my-cell">{{ cell.html }}</div>{% endblock %}
+```
+
+Point a widget to it with `template_name`:
+
+```python
+class MyMatrixWidget(MatrixWidget):
+    template_name = "myapp/my_matrix.html"
+```
+
+| Block | `matrix.html` | `permissions.html` | What it is |
+| --- | --- | --- | --- |
+| `section_summary` | ✓ | ✓ | The heading of a section (its name and count) |
+| `section_toggle` | ✓ | ✓ | The "All" checkbox of a section |
+| `column_heading` | ✓ | ✓ | The heading of a column |
+| `others_heading` | | ✓ | The heading of the "Others" column |
+| `row_heading` | ✓ | ✓ | The heading of a row |
+| `cell` | ✓ | | The widget of a cell (`{{ cell.html }}`) |
+| `permission` | | ✓ | The checkbox of a permission |
+| `other_permission` | | ✓ | A permission of the "Others" column |
+| `missing_cell` | ✓ | ✓ | A cell a row does not have |
+| `empty` | ✓ | ✓ | What shows when there is nothing to fill |
+
+`{{ block.super }}` keeps the original of a block. The classes (`.form-matrix-*`) and the `data-form-matrix-*` attributes are what the stylesheet and the script look for: keep them in your blocks and the shortcuts keep working.
+
+Django looks for the widget templates of a form in the `templates/` of the installed apps, **not** in the `DIRS` of your project. To override `django_form_matrix/matrix.html` itself by name from the project's templates, set `FORM_RENDERER = "django.forms.renderers.TemplatesSetting"`, or put the template in an app listed before `django_form_matrix` in `INSTALLED_APPS`. Extending it with your own `template_name`, as above, needs neither.
+
+## Styling
+
+The stylesheet uses the colours of the Django admin when it is there. Anywhere else, set `--form-matrix-border`, `--form-matrix-heading-bg` and `--form-matrix-quiet` on `.form-matrix`.
+
+### Unfold
+
+[django-unfold](https://github.com/unfoldadmin/django-unfold) does not define the variables of Django's admin, so add `UnfoldMatrixMixin` to the admin: it puts the matrix on Unfold's palette, light and dark, and styles the number, text and select cells like Unfold's own inputs.
+
+```python
+from unfold.admin import ModelAdmin
+from django_form_matrix.contrib.unfold import UnfoldMatrixMixin
+
+
+@admin.register(Plan)
+class PlanAdmin(UnfoldMatrixMixin, ModelAdmin):
+    form = PlanForm
+```
+
+![The matrix in Unfold](https://raw.githubusercontent.com/rodolvbg/django-form-matrix/HEAD/docs/screenshots/unfold.png)
+
+The permission matrix, the use case this library started from, in Unfold:
+
+![The permission matrix in Unfold](https://raw.githubusercontent.com/rodolvbg/django-form-matrix/HEAD/docs/screenshots/unfold-permissions.png)
+
+And in Unfold's dark mode:
+
+![The matrix in Unfold, dark](https://raw.githubusercontent.com/rodolvbg/django-form-matrix/HEAD/docs/screenshots/unfold-dark.png)
+
+## Translations
+
+Ships a Spanish (`es`) translation: the matrix's headings ("Add", "View",
+"Change", "Delete", "Others"), the permissions' names ("Can view plan") and
+its messages follow the active language, like the rest of the admin.
+
+## Development
+
+```bash
+uv sync && npm install
+uv run pytest            # Python + end-to-end (needs `uv run playwright install chromium`)
+npm test                 # JS
+cd example && uv run python manage.py runserver   # demo: Plans and Roles in the admin
+DJANGO_SETTINGS_MODULE=example.settings_unfold uv run python manage.py runserver   # the same, in Unfold
+```