django-modelsheet 0.3.0__tar.gz

django_modelsheet-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,92 @@
+name: CI
+on:
+  push:
+  pull_request:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  python:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - {python: '3.11', django: '5.2', db: sqlite}
+          - {python: '3.12', django: '5.2', db: sqlite}
+          - {python: '3.13', django: '5.2', db: sqlite}
+          - {python: '3.14', django: '5.2', db: sqlite}
+          - {python: '3.12', django: '6.0', db: sqlite}
+          - {python: '3.13', django: '6.0', db: sqlite}
+          - {python: '3.14', django: '6.0', db: sqlite}
+          - {python: '3.12', django: '6.1', db: sqlite}
+          - {python: '3.13', django: '6.1', db: sqlite}
+          - {python: '3.14', django: '6.1', db: sqlite}
+          - {python: '3.13', django: '5.2', db: postgres}
+          - {python: '3.13', django: '6.0', db: postgres}
+          - {python: '3.13', django: '6.1', db: postgres}
+          - {python: '3.13', django: '5.2', db: mysql}
+          - {python: '3.13', django: '6.0', db: mysql}
+          - {python: '3.13', django: '6.1', db: mysql}
+    services:
+      postgres:
+        image: postgres:16
+        env: {POSTGRES_DB: modelsheet, POSTGRES_USER: modelsheet, POSTGRES_PASSWORD: modelsheet}
+        ports: ['5432:5432']
+        options: >-
+          --health-cmd "pg_isready -U modelsheet"
+          --health-interval 10s --health-timeout 5s --health-retries 10
+      mysql:
+        image: mysql:8.4
+        env: {MYSQL_DATABASE: modelsheet, MYSQL_ROOT_PASSWORD: modelsheet}
+        ports: ['3306:3306']
+        options: >-
+          --health-cmd "mysqladmin ping -h localhost -pmodelsheet"
+          --health-interval 10s --health-timeout 5s --health-retries 10
+    env:
+      MODELSHEET_DB: '${{ matrix.db }}'
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: {python-version: '${{ matrix.python }}'}
+      - run: pip install -e '.[test,postgres,mysql]' 'Django~=${{ matrix.django }}.0'
+      - run: python manage.py check && python manage.py makemigrations --check --dry-run
+      - run: python -m ruff check .
+      - run: python -m pytest -q
+
+  browser-and-package:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: {python-version: '3.13'}
+      - uses: actions/setup-node@v4
+        with: {node-version: '22', cache: npm, cache-dependency-path: frontend/package-lock.json}
+      - run: pip install -e '.[test]' twine
+      - run: python scripts/check_release.py --stable
+      - run: npm ci && npm test && npm run build
+        working-directory: frontend
+      - run: git diff --exit-code -- modelsheet/static
+      - run: npx playwright install --with-deps chromium && npm run test:e2e
+        working-directory: frontend
+      - run: python -m build && python -m twine check dist/*
+      - run: python scripts/package_smoke.py
+      - run: python scripts/package_smoke.py --upgrade-from 0.3.0a2
+      - uses: actions/upload-artifact@v4
+        with:
+          name: pypi-distributions
+          path: dist/
+          if-no-files-found: error
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: browser-reports-and-distributions
+          path: |
+            frontend/test-results
+            frontend/playwright-report
+            dist
+
+  documentation:
+    uses: ./.github/workflows/docs-checks.yml

django_modelsheet-0.3.0/.github/workflows/docs-checks.yml

@@ -0,0 +1,31 @@
+name: Documentation checks
+on:
+  workflow_call:
+permissions:
+  contents: read
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.13'
+          cache: pip
+          cache-dependency-path: requirements-docs.txt
+      - run: pip install -r requirements-docs.txt
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+      - run: npm ci && npm test && npm run build:demo
+        working-directory: frontend
+      - run: git diff --exit-code -- docs/assets/playground
+      - run: python scripts/check_docs_locales.py
+      - run: mkdocs build --strict
+      - run: npx playwright install --with-deps chromium && npm run test:demo
+        working-directory: frontend
+      - uses: actions/upload-pages-artifact@v4
+        with:
+          path: site

django_modelsheet-0.3.0/.github/workflows/docs.yml

@@ -0,0 +1,31 @@
+name: Documentation
+on:
+  push:
+    branches: [main]
+    paths: ['docs/**', 'frontend/**', 'mkdocs.yml', 'requirements-docs.txt', 'scripts/check_docs_locales.py', 'scripts/docs_assets.py', '.github/workflows/docs.yml', '.github/workflows/docs-checks.yml']
+  pull_request:
+    paths: ['docs/**', 'frontend/**', 'mkdocs.yml', 'requirements-docs.txt', 'scripts/check_docs_locales.py', 'scripts/docs_assets.py', '.github/workflows/docs.yml', '.github/workflows/docs-checks.yml']
+  workflow_dispatch:
+permissions:
+  contents: read
+concurrency:
+  group: documentation-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  build:
+    uses: ./.github/workflows/docs-checks.yml
+  deploy:
+    if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/configure-pages@v5
+      - name: Deploy documentation
+        id: deployment
+        uses: actions/deploy-pages@v4

django_modelsheet-0.3.0/.github/workflows/workflow.yml

@@ -0,0 +1,58 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      publish:
+        description: Upload version from pyproject.toml to PyPI (leave off to check the build)
+        type: boolean
+        required: true
+        default: false
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pypi-publishing
+  cancel-in-progress: false
+
+jobs:
+  metadata:
+    name: Check stable release metadata
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: {python-version: '3.13'}
+      - name: Check versions and release tag
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: python scripts/check_release.py --stable --tag "$RELEASE_TAG"
+
+  validate:
+    name: Full release validation
+    needs: metadata
+    uses: ./.github/workflows/ci.yml
+
+  publish:
+    name: Publish distributions to PyPI
+    needs: [metadata, validate]
+    if: >-
+      github.repository == 'svalench/django-modelsheet' &&
+      (github.event_name == 'release' ||
+       (inputs.publish && github.ref == 'refs/heads/main'))
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/django-modelsheet
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: pypi-distributions
+          path: dist/
+      - name: Publish using PyPI Trusted Publishing
+        uses: pypa/gh-action-pypi-publish@release/v1

django_modelsheet-0.3.0/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+## 0.3.0 — 2026-10-25
+
+- Preserve edits, undo/redo and save payloads for string primary keys such as `__proto__` and `constructor`.
+- Store an immutable preview deadline; cancel/resume cannot renew an expired plan or rebuild an empty plan.
+- Add migration `0002` to expire legacy unconfirmed plans conservatively while preserving history and operation items. Run migrations and collectstatic during upgrade.
+- Synchronize Python/npm versions and stable metadata; gate publishing on the full database/Python matrix, browser tests, strict documentation and wheel upgrade smoke checks.
+
+- Reject bulk previews containing rows hidden by object permissions before calculating aggregates.
+- Cache bulk formula parsing and query aggregates within each immutable plan, preserving formula budgets and lazy branches.
+- Return existing bulk previews on idempotent retries even after their view snapshot expires or is removed.
+- Lock editing and navigation while saving/loading so pending changes cannot be silently discarded.
+- Invalidate bulk previews for structural edits and ignore stale preview/poll responses.
+- Add permission, retry, formula-cache and browser regression tests plus an isolated bulk benchmark.
+- Enable sheets through `ModelSheetAdmin` registration without a required settings list.
+- Discover role models from enabled Admin registrations, including custom Admin sites.
+- Keep `MODELSHEET["models"]` as an optional restriction for existing projects.
+
+## 0.3.0a2 — 2026-10-24
+
+- Keep unchanged numeric cells out of the local change buffer.
+- Constrain cell editors to their cells and reset inherited form styles.
+- Synchronize the formula bar with Tabulator keyboard navigation and selection.
+- Preserve live-demo cell identities after editing so arrow and Tab navigation remain reliable.
+- Add browser regression coverage for editor layout, no-op edits and keyboard workflows.
+- Include the live documentation playground in English, Simplified Chinese and Belarusian.
+
+## 0.3.0a1 — 2026-10-24
+
+- Initial Django package, explicit Admin registration, precompiled static assets.
+- Spreadsheet range editing, local undo/redo, safe atomic saves and row fingerprints.
+- Permission-aware search, grouped filters, sorting, snapshots and Admin switching.
+- Bounded Python/TypeScript formula engines with shared golden fixtures.
+- Immutable bulk previews, confirmation, audit, idempotency and background adapter contract.
+- Demo project, migrations, role/cleanup commands, CI and packaging checks.
+
+Version 0.3.0a1 combined the planned v0.1–v0.3 increments and introduced the first
+published schema. Later releases preserve its forward migration path.

django_modelsheet-0.3.0/CONTRIBUTING.md

@@ -0,0 +1,18 @@
+# Contributing
+
+Use Python 3.11+ (3.12+ with Django 6.x) and Node 22. Install `.[test]`, then run
+`npm ci` inside frontend. Build assets with `npm run build` and include both source
+and generated assets in changes. Never require npm in consuming Django projects.
+
+Run pytest, ruff, Vitest and Playwright as described in README. Formula semantics
+changes must add fixtures to tests/formula_cases.json and pass both runtimes.
+Use actual transactional tests with separate connections for concurrency changes.
+Database-specific behavior must be exercised by the PostgreSQL/MySQL CI jobs.
+
+Run makemigrations for schema changes. Do not rewrite released migrations. Preserve
+permission checks on every API/worker entry point and safe saves by default.
+Do not silently broaden a preview's members or automatically replay failed items.
+
+Update docs and CHANGELOG for public interfaces. Add dependency license notices when
+bundling new assets. Avoid committing local credentials, demo databases and generated
+test reports. The demo's explicit test credentials must not be used in production.

django_modelsheet-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 django-modelsheet contributors
+
+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_modelsheet-0.3.0/MANIFEST.in

@@ -0,0 +1,14 @@
+include LICENSE README.md CHANGELOG.md CONTRIBUTING.md SECURITY.md
+recursive-include modelsheet/static *
+recursive-include modelsheet/templates *.html
+recursive-include modelsheet/locale *.po *.mo
+recursive-include docs *.md *.json
+recursive-include frontend *.ts *.json *.html *.css
+prune frontend/node_modules
+prune frontend/test-results
+prune frontend/playwright-report
+recursive-include tests *.py *.json
+recursive-include demo *.py
+recursive-include scripts *.py
+recursive-include .github/workflows *.yml
+include manage.py

django_modelsheet-0.3.0/PKG-INFO

@@ -0,0 +1,210 @@
+Metadata-Version: 2.4
+Name: django-modelsheet
+Version: 0.3.0
+Summary: Spreadsheet editing, formulas and previewed bulk operations for Django Admin
+License-Expression: MIT
+Project-URL: Repository, https://github.com/svalench/django-modelsheet
+Project-URL: Documentation, https://svalench.github.io/django-modelsheet/
+Project-URL: Issues, https://github.com/svalench/django-modelsheet/issues
+Project-URL: Changelog, https://github.com/svalench/django-modelsheet/blob/main/CHANGELOG.md
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 5.2
+Classifier: Framework :: Django :: 6.0
+Classifier: Framework :: Django :: 6.1
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Django<6.2,>=5.2
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: pytest-django>=4.9; extra == "test"
+Requires-Dist: pytest-timeout>=2; extra == "test"
+Requires-Dist: build; extra == "test"
+Requires-Dist: ruff; extra == "test"
+Requires-Dist: playwright; extra == "test"
+Requires-Dist: PyYAML>=6; extra == "test"
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]>=3.2; extra == "postgres"
+Provides-Extra: mysql
+Requires-Dist: mysqlclient>=2.2; extra == "mysql"
+Dynamic: license-file
+
+# django-modelsheet
+
+Spreadsheet editing for explicitly registered Django Admin models: cell/range editing,
+local undo/redo, Decimal formulas, server-side filters, and previewed bulk changes.
+
+**0.3.0 is the first stable release.** [Release notes](https://github.com/svalench/django-modelsheet/releases/tag/v0.3.0) · [PyPI](https://pypi.org/project/django-modelsheet/0.3.0/)
+The repository includes a working demo, compiled assets, tests, and a compatibility CI matrix.
+
+**[Documentation website →](https://svalench.github.io/django-modelsheet/)** —
+installation, examples, formulas, bulk operations and extension APIs in English, Simplified Chinese and Belarusian.
+
+## Quickstart
+
+Install the stable release:
+
+```sh
+pip install django-modelsheet==0.3.0
+```
+
+```python
+# settings.py
+INSTALLED_APPS += ["modelsheet"]
+
+# SQLite only: required for safe writes; PostgreSQL/MySQL use row locks.
+DATABASES["default"].setdefault("OPTIONS", {})["transaction_mode"] = "IMMEDIATE"
+```
+
+```python
+# admin.py
+from django.contrib import admin
+from modelsheet.admin import ModelSheetAdmin
+from .models import Product
+
+@admin.register(Product)
+class ProductAdmin(ModelSheetAdmin):
+    list_display = ("name", "price", "stock")
+    search_fields = ("name",)
+    sheet_fields = ("name", "price", "stock")
+    sheet_editable = ("price", "stock")
+    sheet_computed_fields = {"inventory_value": "=[price]*[stock]"}
+```
+
+```sh
+python manage.py migrate
+python manage.py collectstatic --noinput
+python manage.py modelsheet_roles  # optional: creates groups, assigns no users
+```
+
+Registering `ModelSheetAdmin` enables the sheet; no model list in settings is needed.
+
+Assign a group through Django Admin and mark the account as staff. Superusers can
+use configured sheets immediately. Open **Spreadsheet** from the model list, or
+visit `/admin/shop/product/sheet/`. No frontend build, CDN or extra URL include is
+required in the consuming project. Admin's existing sessions and CSRF protection apply.
+
+## Upgrading to 0.3.0
+
+Back up the database and pause writes/background workers. Install the new package,
+run `python manage.py migrate` and `python manage.py collectstatic --noinput`, then
+restart the application/workers and reload browser tabs. Migration `0002` preserves
+history and operation items, but expires legacy unconfirmed previews: build a new
+preview before confirming. Already confirmed runs retain their resume behavior.
+New preview deadlines start when preparation completes and cannot be extended by
+cancel/resume or settings changes. Pin `django-modelsheet==0.3.0`.
+
+## Using the sheet
+
+- Double-click to edit; use the formula bar for a value or expression.
+- Changes stay local until **Save**. Ctrl/Cmd+Z, Ctrl/Cmd+Y and Ctrl/Cmd+S operate on this buffer.
+- Select a range, copy/paste TSV from Excel, or press Ctrl/Cmd+D to fill down.
+- Readonly cells are skipped during paste with a notification. A save is atomic across all changed rows.
+- Use **Sort** for ordered sort fields, or Alt+click a column header (Alt+Shift+click adds a field).
+  Ordinary header clicks select columns. Search and filters run on the server.
+- **Bulk change** selects either highlighted page rows or every matching row, including other pages.
+  Build a preview, inspect its exact count/values, then confirm it. Editing inputs requires a new preview.
+- **Ordinary Admin** is available only when its list can represent the same filter, ordering and page.
+
+Numbers use a decimal point and dates use ISO 8601. Empty pasted cells become
+NULL for nullable fields, otherwise empty text for text fields or a validation error.
+Prefix text beginning with `=` with an apostrophe, for example `'=SUM(A1:A2)`.
+
+## Configuration
+
+```python
+MODELSHEET = {
+    "page_size": 200,
+    "max_page_size": 500,
+    "max_save_rows": 500,
+    "count_mode": "exact",  # exact | none (no approximate COUNT promise)
+    "bulk_background_threshold": 5000,
+    "max_bulk_rows": 100000,
+    "chunk_size": 200,
+    "snapshot_ttl_seconds": 1800,
+    "preview_ttl_seconds": 1800,
+    "history_retention_days": 365,
+    "max_operations_per_minute": 30,
+    "max_request_bytes": 1000000,
+    "formula": {"max_length": 500, "max_depth": 10, "max_steps": 10000, "timeout_ms": 250},
+    "background_adapter": None,
+}
+```
+
+Run `python manage.py modelsheet_cleanup` periodically through your scheduler.
+It removes expired snapshots and terminal/unused-preview operations beyond retention.
+Do not reuse old idempotency keys after their operation has been purged.
+
+## Permissions
+
+Access requires `is_active`, `is_staff`, `modelsheet.open`, the model's standard
+`view` permission, and `ModelAdmin.has_view_permission()`. Editing additionally
+requires the standard `change` permission and `has_change_permission()`.
+
+Package permission codenames include app/model identifiers:
+
+```text
+modelsheet.view_field_shop_product_price
+modelsheet.edit_field_shop_product_price
+modelsheet.bulk_shop_product
+modelsheet.history_shop_product
+```
+
+`get_queryset(request)` bounds every read/write. Object-level Admin hooks and the
+configured policy apply in addition. Hidden fields cannot be used in filters,
+sorting, formulas or history. Field permissions never grant model-level editing.
+
+Group templates are opt-in and additive: Viewer, Editor, Operator, Auditor and Admin.
+They grant access to the configured sheet fields; review these grants before
+assigning users, especially sensitive columns. They do not grant superuser status.
+
+## Development and demo
+
+```sh
+python -m pip install -e '.[test]'
+cd frontend
+npm ci
+npm run build
+npm test
+cd ..
+python manage.py migrate
+python manage.py seed_demo --create-user
+python manage.py runserver
+```
+
+The explicit `--create-user` option creates a local-only `admin` / `admin` account.
+The demo settings are not production settings. Open
+`http://127.0.0.1:8000/admin/shop/product/sheet/`.
+
+```sh
+python -m pytest
+python -m ruff check .
+python -m build --no-isolation
+cd frontend
+npx playwright install chromium
+npm run test:e2e
+```
+
+Target matrix: Django 5.2 / Python 3.11–3.14; Django 6.0 and 6.1 / Python
+3.12–3.14; PostgreSQL, MySQL/InnoDB, SQLite. CI exercises valid combinations and
+the same transactional contract across databases. Consult CI results before
+treating a combination as verified; local results are recorded in `docs/validation.md`.
+
+## Boundaries
+
+Safe mode calls `full_clean()` and the instance's `save()` by default, including
+normal model signals. Custom `ModelAdmin.save_model()`, custom Admin forms,
+`save_related()` and external effects need an explicit adapter. Snapshot fingerprints
+cover concrete model fields, not all intermediate history or related-table contents.
+
+Sheets use the `default` database. User models require no extra fields or inheritance.
+Existing scalar fields are editable; FK fields can be displayed/filtered but FK/M2M
+editors, server undo, file import/export, fast-save, cursor pagination and persistent
+formulas are deferred. Large operations require your own background adapter.
+
+See [formulas](docs/formulas.md), [extension API](docs/extensions.md),
+[background processing](docs/background.md), [HTTP API](docs/api.md), and
+[release procedure](docs/releasing.md). Bundled dependency notices are in
+`modelsheet/static/modelsheet/THIRD_PARTY_LICENSES.txt`.