django-modelsheet 0.3.0__py3-none-any.whl

django_modelsheet-0.3.0.dist-info/METADATA

@@ -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`.

django_modelsheet-0.3.0.dist-info/RECORD

@@ -0,0 +1,42 @@
+django_modelsheet-0.3.0.dist-info/licenses/LICENSE,sha256=MmQND-_DSLg3oiVoo63Z3JCB2OXKqZRSXroN0t1Ai7I,1087
+modelsheet/__init__.py,sha256=VrXpHDu3erkzwl_WXrqINBm9xWkcyUy53IQOj042dOs,22
+modelsheet/adapters.py,sha256=k--zM4F04BMAlEUdmnrRh-JGB8bDtxZsTXQ-4YnCNZQ,4457
+modelsheet/admin.py,sha256=WLuzbvFxSDca7i4BMbESKEqgX4CvXmG9_JTWa0vdTXo,13138
+modelsheet/apps.py,sha256=ddPeL-HoSEOP2VVyrrbao4h97dAgKlqM6hluy-ozJH0,455
+modelsheet/background.py,sha256=VBLNlkcnrNiel6LBwTLkMjOAlPwsPxBG7F3YRKLs28c,1919
+modelsheet/bulk.py,sha256=1ZmbIGwpTogu6FVF-Rkp7nvWrwPIP-0rEtU4X31YLuY,18149
+modelsheet/checks.py,sha256=xVXGnuY6rJMTvlh22mlWdcG1Kc1IBwsnP8SbEVF4iAY,3989
+modelsheet/conf.py,sha256=pjoPc5kI-Rc9lM9b6T6k1NI6XUYABDuOFLH3Ew_tFRQ,1378
+modelsheet/errors.py,sha256=fs0ucDObHYetMqV6olQ3miff0VqOU0Vx0KgzV7Epqmc,614
+modelsheet/metadata.py,sha256=ApFru-G0EfxQoZ6HcK4g2rAb7fcfuvpdyAzW6O0TY40,1405
+modelsheet/models.py,sha256=CoHciVpShLTDhfgMXpKLVlYTrDJoWJFZDQjf2iilNsw,2604
+modelsheet/permissions.py,sha256=9zniYFREwDVg85MN3mOMhVjL2x2DjA68PbzWV2XgcTg,2841
+modelsheet/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+modelsheet/query.py,sha256=dYHKrNmlPhqZEy_liR1bU4pCYozc_PpZ-HPwkBbxN-A,5246
+modelsheet/registry.py,sha256=uACRZGuDCDHLCk-IByfqG5rS7jTZL-aQH6CPHoujYcY,605
+modelsheet/services.py,sha256=_5w_ELlPqAwwhZnb6JKozxtOawnxpgHr7X6qao8xZ_8,18683
+modelsheet/views.py,sha256=mPgpWX_4x77tMetOuWGL9W1Plirxp7yV5ihmHBfSm_A,3680
+modelsheet/formula/__init__.py,sha256=QyDX-f5Dvqmnovz9zUC-On05OWlIp5I_xDK3qnkG1WY,125
+modelsheet/formula/engine.py,sha256=ec_v5156CrpQPOzmv5fgQozR__LjXw88GXams80BaiU,14084
+modelsheet/locale/ru/LC_MESSAGES/django.mo,sha256=CAVfcPAzm7SzCfRXErTD-5xbHlO7lfHh3OOLpbH0CZA,259
+modelsheet/locale/ru/LC_MESSAGES/django.po,sha256=_jEJe0eYK6iuF6MzjtJXFnGMaUY1hUaq3Jw4Bfz7Hhg,246
+modelsheet/locale/ru/LC_MESSAGES/djangojs.mo,sha256=EzdptKmDcsPL68r_NMFECeZqOZ-5uEyBfdR3aNw4r4Q,3431
+modelsheet/locale/ru/LC_MESSAGES/djangojs.po,sha256=SoxFKh-_JOYM2elhdxMqpG7J6C4t_bWtUpeQQ25pWWQ,3536
+modelsheet/management/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+modelsheet/management/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+modelsheet/management/commands/modelsheet_cleanup.py,sha256=pwJ-PFU4NBEEp7srW4h8bZPQ9R6WiPDk3S_TWi85ttY,905
+modelsheet/management/commands/modelsheet_roles.py,sha256=MsGz87KORtKOt5ihnXcBRc77roWJneyWhN5qjP0wuo8,2624
+modelsheet/migrations/0001_initial.py,sha256=uP5UZTy3U80YhE5kfft1kOnObt8qlVk94-WFDP8q5zY,4589
+modelsheet/migrations/0002_operation_preview_expires_at.py,sha256=zqZ0dW3Z4XCMFUNM7c-bCMSqRieIoU9NtA4Wh1QgYP0,1117
+modelsheet/migrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+modelsheet/static/modelsheet/THIRD_PARTY_LICENSES.txt,sha256=0opprOP9KVjqzCKxO-Uz5x_wleW0c4CkJS5sBi7HP2Y,2188
+modelsheet/static/modelsheet/sheet.css,sha256=-oCXbWclpUbFXEIevimlCzWZcvMsUb1N7bgQaBy9gU4,33181
+modelsheet/static/modelsheet/sheet.js,sha256=zKuQay5gjSaBCmaCgIGL_r-qRRh-aCylUW406D2sPNQ,673053
+modelsheet/templates/modelsheet/audit.html,sha256=BbTLwkuAccbglySQWlcwVmsFOSPrWm-AEfH7zXLql5M,753
+modelsheet/templates/modelsheet/change_list.html,sha256=LZh_Jzqi2N0FO9jLoMdu-OlEJAIcHjsvt-seRjnHY8A,231
+modelsheet/templates/modelsheet/sheet.html,sha256=jkpWDt_YdYfIBKI4qYC75v6X6TrVzCj_WTOQnLRCzkQ,531
+modelsheet/templates/modelsheet/unavailable.html,sha256=1Nihf4i4RAobf6qK-zg1AG0fauf7Gp3Xbfr0i5WUXyc,129
+django_modelsheet-0.3.0.dist-info/METADATA,sha256=gyFPXNSzAUJ27wcoFYIkgRNMB9_2m6qBj6t0szlK-Ak,8638
+django_modelsheet-0.3.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+django_modelsheet-0.3.0.dist-info/top_level.txt,sha256=bUovMtlnvML9O2UB-RuPHhcidwi_vXCkTlv9V727lak,11
+django_modelsheet-0.3.0.dist-info/RECORD,,

django_modelsheet-0.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

django_modelsheet-0.3.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+modelsheet

modelsheet/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.3.0"

modelsheet/adapters.py

@@ -0,0 +1,121 @@
+import datetime as dt
+from decimal import Decimal, ROUND_HALF_EVEN, localcontext
+
+from django.core.exceptions import ValidationError
+from django.conf import settings
+from django.db import models
+from django.utils import timezone
+
+
+def serialize(value):
+    if isinstance(value, Decimal):
+        return str(value)
+    if isinstance(value, (dt.datetime, dt.date, dt.time)):
+        return value.isoformat()
+    if isinstance(value, (str, int, float, bool)) or value is None:
+        return value
+    return str(value)
+
+
+class FieldAdapter:
+    def supported(self, field):
+        return (
+            isinstance(
+                field,
+                (
+                    models.CharField,
+                    models.TextField,
+                    models.IntegerField,
+                    models.DecimalField,
+                    models.FloatField,
+                    models.BooleanField,
+                    models.DateField,
+                    models.TimeField,
+                    models.UUIDField,
+                    models.ForeignKey,
+                ),
+            )
+            and not field.primary_key
+        )
+
+    def editable(self, field):
+        return self.supported(field) and field.editable and not isinstance(field, models.ForeignKey)
+
+    def serialize(self, field, instance):
+        return serialize(field.value_from_object(instance))
+
+    def parse(self, field, value):
+        if isinstance(value, (dict, list)):
+            raise ValidationError("A scalar value is required.")
+        if value is None or value == "":
+            if field.null:
+                return None
+            if isinstance(field, (models.CharField, models.TextField)):
+                return ""
+            raise ValidationError("This field cannot be empty.")
+        if isinstance(field, models.BooleanField) and isinstance(value, str):
+            if value.lower() in ("true", "1"):
+                value = True
+            elif value.lower() in ("false", "0"):
+                value = False
+        if isinstance(field, models.DecimalField):
+            value = Decimal(str(value))
+            if not value.is_finite():
+                raise ValidationError("A finite decimal is required.")
+            with localcontext() as context:
+                context.prec = max(28, field.max_digits + 2)
+                value = value.quantize(
+                    Decimal(1).scaleb(-field.decimal_places), rounding=ROUND_HALF_EVEN
+                )
+        if isinstance(field, models.IntegerField) and not isinstance(field, models.BooleanField):
+            integer = Decimal(str(value))
+            if (
+                isinstance(value, bool)
+                or not integer.is_finite()
+                or integer.adjusted() > 19
+                or integer != integer.to_integral_value()
+            ):
+                raise ValidationError("An integer is required.")
+        if isinstance(field, models.FloatField):
+            import math
+
+            if not math.isfinite(float(value)):
+                raise ValidationError("A finite number is required.")
+        value = field.to_python(value)
+        if isinstance(value, dt.datetime) and timezone.is_naive(value) and settings.USE_TZ:
+            value = timezone.make_aware(value, dt.timezone.utc)
+        elif isinstance(value, dt.datetime) and timezone.is_aware(value) and not settings.USE_TZ:
+            value = value.astimezone(dt.timezone.utc).replace(tzinfo=None)
+        return value
+
+    def metadata(self, field):
+        return {
+            "name": field.name,
+            "label": str(field.verbose_name),
+            "type": field.get_internal_type(),
+            "nullable": field.null,
+            "choices": [[serialize(k), str(v)] for k, v in field.flatchoices],
+        }
+
+
+class SaveAdapter:
+    """Override for project validation/business logic. External effects must be idempotent."""
+
+    def validate(self, instance, request):
+        instance.full_clean()
+
+    def save(self, instance, fields, request):
+        instance.save()
+
+
+class BackgroundAdapter:
+    """Implement enqueue and capture/restore_context; see docs/background.md."""
+
+    def capture_context(self, request):
+        return {}
+
+    def restore_context(self, user, context):
+        raise NotImplementedError("Restore a request including tenant and project context")
+
+    def enqueue(self, operation_id, phase):
+        raise NotImplementedError("Durably enqueue modelsheet.background.process(id, phase)")