grid-view-spec 2.0.0__tar.gz

grid_view_spec-2.0.0/LICENSE

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

grid_view_spec-2.0.0/PKG-INFO

@@ -0,0 +1,195 @@
+Metadata-Version: 2.4
+Name: grid-view-spec
+Version: 2.0.0
+Summary: Declarative GridViewSpec pages: tables, filters, KPI, charts, PDF/XLSX export; optional Django backend
+Author-email: Oleksii Pylypchuk <alpi@keemail.me>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/alpiua/grid-view-spec
+Project-URL: Repository, https://github.com/alpiua/grid-view-spec
+Project-URL: Documentation, https://alpiua.github.io/grid-view-spec/
+Project-URL: Issues, https://github.com/alpiua/grid-view-spec/issues
+Project-URL: Changelog, https://github.com/alpiua/grid-view-spec/blob/main/CHANGELOG.md
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 5
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: jinja2>=3.1
+Provides-Extra: django
+Requires-Dist: django<6.0,>=4.2; extra == "django"
+Provides-Extra: mcp
+Requires-Dist: fastmcp>=2.0.0; extra == "mcp"
+Provides-Extra: starlette
+Requires-Dist: starlette>=0.40; extra == "starlette"
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.115; extra == "fastapi"
+Requires-Dist: starlette>=0.40; extra == "fastapi"
+Provides-Extra: static-charts
+Requires-Dist: matplotlib>=3.8; extra == "static-charts"
+Provides-Extra: pdf
+Requires-Dist: weasyprint>=62; extra == "pdf"
+Requires-Dist: jinja2>=3.1; extra == "pdf"
+Provides-Extra: xlsx
+Requires-Dist: xlsxwriter>=3.2.0; extra == "xlsx"
+Provides-Extra: xlsx-all
+Requires-Dist: xlsxwriter>=3.2.0; extra == "xlsx-all"
+Requires-Dist: openpyxl>=3.1; extra == "xlsx-all"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.6; extra == "docs"
+Requires-Dist: mkdocs-material>=9.5; extra == "docs"
+Provides-Extra: dev
+Requires-Dist: basedpyright>=1.28.0; extra == "dev"
+Requires-Dist: build>=1.2.0; extra == "dev"
+Requires-Dist: django<6.0,>=4.2; extra == "dev"
+Requires-Dist: django-stubs>=5.1.0; extra == "dev"
+Requires-Dist: jinja2>=3.1; extra == "dev"
+Requires-Dist: matplotlib>=3.8; extra == "dev"
+Requires-Dist: matplotlib-stubs>=0.3.11; extra == "dev"
+Requires-Dist: mkdocs>=1.6; extra == "dev"
+Requires-Dist: mkdocs-material>=9.5; extra == "dev"
+Requires-Dist: openpyxl>=3.1; extra == "dev"
+Requires-Dist: pre-commit>=4.0.0; extra == "dev"
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-django>=4.8.0; extra == "dev"
+Requires-Dist: jsonschema>=4.23.0; extra == "dev"
+Requires-Dist: ruff>=0.8.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+Requires-Dist: typing_extensions>=4.12.0; extra == "dev"
+Requires-Dist: weasyprint>=62; extra == "dev"
+Requires-Dist: xlsxwriter>=3.2.0; extra == "dev"
+Dynamic: license-file
+
+# Grid View Spec
+
+[![PyPI](https://img.shields.io/pypi/v/grid-view-spec.svg?label=PyPI)](https://pypi.org/project/grid-view-spec/)
+[![Python](https://img.shields.io/pypi/pyversions/grid-view-spec.svg)](https://pypi.org/project/grid-view-spec/)
+[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-2563eb)](https://alpiua.github.io/grid-view-spec/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+**Declarative dashboard pages for Django and other hosts** — tables, filters, KPI strips, charts, and export from one typed **`GridViewSpec`** contract. You own SQL/ORM rows; the package owns layout, templates, browser runtime, and PDF/XLSX pipelines.
+
+**[Documentation](https://alpiua.github.io/grid-view-spec/)** · **[MCP server](docs/tools/mcp-server.md)** · **[PyPI](https://pypi.org/project/grid-view-spec/)**
+
+---
+
+## Core idea
+
+| Layer | Owner |
+|-------|--------|
+| **Data** | Host — querysets, aggregates, authorization |
+| **Spec** | `GridViewSpec` — blocks (`GridViewTable`, `GridViewFilters`, …) + layout |
+| **Render** | Package — Jinja/Django HTML, `gridviewspec.min.js`, export |
+
+```python
+from grid_view_spec import GridViewSpec, validate_spec
+from grid_view_spec.types.layout import GridViewArea, GridViewLayout
+from grid_view_spec.types.table_v2 import GridViewColumn, GridViewTable
+
+spec = GridViewSpec(
+    id="orders",
+    blocks=(
+        GridViewTable(
+            id="orders_table",
+            backend="simple",
+            columns=(
+                GridViewColumn(id="name", label="Customer", field="name"),
+                GridViewColumn(id="amount", label="Amount", field="amount", type="currency"),
+            ),
+        ),
+    ),
+    layout=GridViewLayout(root=GridViewArea(id="root", blocks=("orders_table",))),
+)
+validate_spec(spec)
+```
+
+```django
+{% load grid_view_spec %}
+{% grid_view_spec_assets part='css' %}
+{% render_grid_view_spec spec rows %}
+{% grid_view_spec_assets part='js' force_core=True %}
+```
+
+---
+
+## Install
+
+```bash
+pip install "grid-view-spec[django]"
+# optional:
+pip install "grid-view-spec[django,pdf,xlsx,mcp]"
+```
+
+**Django**
+
+```python
+INSTALLED_APPS = ["grid_view_spec.backends.django"]
+```
+
+```bash
+python manage.py migrate grid_view_spec_django
+```
+
+```python
+urlpatterns = [
+    path("", include("grid_view_spec.backends.django.urls")),
+]
+```
+
+See [Getting started](docs/getting-started.md) and [Django integration](docs/integration/django.md).
+
+---
+
+## Export
+
+Register builders that return **`GridViewExportJob(spec, rows, table_id=…)`**:
+
+```python
+from grid_view_spec.export.registry import register_pdf_export, register_xlsx_export
+from grid_view_spec.export.registry import GridViewExportJob
+
+def register_exports():
+    def builder(host, ctx):
+        page = load_orders_page(ctx)  # same loader as HTML view
+        return GridViewExportJob(spec=page.spec, rows=page.rows, table_id="orders_table")
+
+    register_pdf_export("orders", builder)
+    register_xlsx_export("orders", builder)
+```
+
+Browser links use `?builder=orders` plus current filter query params. Details: [Export page pattern](docs/export/page-pattern.md).
+
+---
+
+## AG-Grid, charts, MCP
+
+- **AG-Grid** — `GridViewTable(backend="ag_grid")` + host JSON API; helpers in `grid_view_spec.backends.django.ag_grid`
+- **Charts / KPI** — spec blocks + ECharts; values always from host `rows`
+- **MCP** — `gridviewspec-mcp` for validation, catalog, migration hints ([tools/mcp-server.md](docs/tools/mcp-server.md))
+
+---
+
+## Development
+
+```bash
+uv sync
+uv run pytest -q
+uv run basedpyright --warnings src/grid_view_spec tests
+cd frontend && npm run build && npm run typecheck
+```
+
+Pre-commit hooks: ruff, basedpyright, frontend typecheck/eslint, pytest.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

grid_view_spec-2.0.0/README.md

@@ -0,0 +1,125 @@
+# Grid View Spec
+
+[![PyPI](https://img.shields.io/pypi/v/grid-view-spec.svg?label=PyPI)](https://pypi.org/project/grid-view-spec/)
+[![Python](https://img.shields.io/pypi/pyversions/grid-view-spec.svg)](https://pypi.org/project/grid-view-spec/)
+[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-2563eb)](https://alpiua.github.io/grid-view-spec/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+**Declarative dashboard pages for Django and other hosts** — tables, filters, KPI strips, charts, and export from one typed **`GridViewSpec`** contract. You own SQL/ORM rows; the package owns layout, templates, browser runtime, and PDF/XLSX pipelines.
+
+**[Documentation](https://alpiua.github.io/grid-view-spec/)** · **[MCP server](docs/tools/mcp-server.md)** · **[PyPI](https://pypi.org/project/grid-view-spec/)**
+
+---
+
+## Core idea
+
+| Layer | Owner |
+|-------|--------|
+| **Data** | Host — querysets, aggregates, authorization |
+| **Spec** | `GridViewSpec` — blocks (`GridViewTable`, `GridViewFilters`, …) + layout |
+| **Render** | Package — Jinja/Django HTML, `gridviewspec.min.js`, export |
+
+```python
+from grid_view_spec import GridViewSpec, validate_spec
+from grid_view_spec.types.layout import GridViewArea, GridViewLayout
+from grid_view_spec.types.table_v2 import GridViewColumn, GridViewTable
+
+spec = GridViewSpec(
+    id="orders",
+    blocks=(
+        GridViewTable(
+            id="orders_table",
+            backend="simple",
+            columns=(
+                GridViewColumn(id="name", label="Customer", field="name"),
+                GridViewColumn(id="amount", label="Amount", field="amount", type="currency"),
+            ),
+        ),
+    ),
+    layout=GridViewLayout(root=GridViewArea(id="root", blocks=("orders_table",))),
+)
+validate_spec(spec)
+```
+
+```django
+{% load grid_view_spec %}
+{% grid_view_spec_assets part='css' %}
+{% render_grid_view_spec spec rows %}
+{% grid_view_spec_assets part='js' force_core=True %}
+```
+
+---
+
+## Install
+
+```bash
+pip install "grid-view-spec[django]"
+# optional:
+pip install "grid-view-spec[django,pdf,xlsx,mcp]"
+```
+
+**Django**
+
+```python
+INSTALLED_APPS = ["grid_view_spec.backends.django"]
+```
+
+```bash
+python manage.py migrate grid_view_spec_django
+```
+
+```python
+urlpatterns = [
+    path("", include("grid_view_spec.backends.django.urls")),
+]
+```
+
+See [Getting started](docs/getting-started.md) and [Django integration](docs/integration/django.md).
+
+---
+
+## Export
+
+Register builders that return **`GridViewExportJob(spec, rows, table_id=…)`**:
+
+```python
+from grid_view_spec.export.registry import register_pdf_export, register_xlsx_export
+from grid_view_spec.export.registry import GridViewExportJob
+
+def register_exports():
+    def builder(host, ctx):
+        page = load_orders_page(ctx)  # same loader as HTML view
+        return GridViewExportJob(spec=page.spec, rows=page.rows, table_id="orders_table")
+
+    register_pdf_export("orders", builder)
+    register_xlsx_export("orders", builder)
+```
+
+Browser links use `?builder=orders` plus current filter query params. Details: [Export page pattern](docs/export/page-pattern.md).
+
+---
+
+## AG-Grid, charts, MCP
+
+- **AG-Grid** — `GridViewTable(backend="ag_grid")` + host JSON API; helpers in `grid_view_spec.backends.django.ag_grid`
+- **Charts / KPI** — spec blocks + ECharts; values always from host `rows`
+- **MCP** — `gridviewspec-mcp` for validation, catalog, migration hints ([tools/mcp-server.md](docs/tools/mcp-server.md))
+
+---
+
+## Development
+
+```bash
+uv sync
+uv run pytest -q
+uv run basedpyright --warnings src/grid_view_spec tests
+cd frontend && npm run build && npm run typecheck
+```
+
+Pre-commit hooks: ruff, basedpyright, frontend typecheck/eslint, pytest.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

grid_view_spec-2.0.0/pyproject.toml

@@ -0,0 +1,142 @@
+[project]
+name = "grid-view-spec"
+version = "2.0.0"
+description = "Declarative GridViewSpec pages: tables, filters, KPI, charts, PDF/XLSX export; optional Django backend"
+readme = "README.md"
+authors = [
+    { name = "Oleksii Pylypchuk", email = "alpi@keemail.me" }
+]
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Web Environment",
+    "Framework :: Django",
+    "Framework :: Django :: 5",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "jinja2>=3.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/alpiua/grid-view-spec"
+Repository = "https://github.com/alpiua/grid-view-spec"
+Documentation = "https://alpiua.github.io/grid-view-spec/"
+Issues = "https://github.com/alpiua/grid-view-spec/issues"
+Changelog = "https://github.com/alpiua/grid-view-spec/blob/main/CHANGELOG.md"
+
+[project.scripts]
+gridviewspec-mcp = "grid_view_spec.mcp.server:main"
+
+[project.optional-dependencies]
+django = ["django>=4.2,<6.0"]
+mcp = ["fastmcp>=2.0.0"]
+starlette = ["starlette>=0.40"]
+fastapi = ["fastapi>=0.115", "starlette>=0.40"]
+static-charts = ["matplotlib>=3.8"]
+pdf = ["weasyprint>=62", "jinja2>=3.1"]
+xlsx = ["xlsxwriter>=3.2.0"]
+xlsx-all = ["xlsxwriter>=3.2.0", "openpyxl>=3.1"]
+docs = [
+    "mkdocs>=1.6",
+    "mkdocs-material>=9.5",
+]
+# Mirror of [dependency-groups] dev — for pip install grid-view-spec[dev,mcp]
+dev = [
+    "basedpyright>=1.28.0",
+    "build>=1.2.0",
+    "django>=4.2,<6.0",
+    "django-stubs>=5.1.0",
+    "jinja2>=3.1",
+    "matplotlib>=3.8",
+    "matplotlib-stubs>=0.3.11",
+    "mkdocs>=1.6",
+    "mkdocs-material>=9.5",
+    "openpyxl>=3.1",
+    "pre-commit>=4.0.0",
+    "pytest>=8.0.0",
+    "pytest-django>=4.8.0",
+    "jsonschema>=4.23.0",
+    "ruff>=0.8.0",
+    "twine>=5.0.0",
+    "typing_extensions>=4.12.0",
+    "weasyprint>=62",
+    "xlsxwriter>=3.2.0",
+]
+
+[dependency-groups]
+dev = [
+    "basedpyright>=1.28.0",
+    "build>=1.2.0",
+    "django>=4.2,<6.0",
+    "django-stubs>=5.1.0",
+    "jinja2>=3.1",
+    "matplotlib>=3.8",
+    "matplotlib-stubs>=0.3.11",
+    "mkdocs>=1.6",
+    "mkdocs-material>=9.5",
+    "openpyxl>=3.1",
+    "pre-commit>=4.0.0",
+    "pytest>=8.0.0",
+    "pytest-django>=4.8.0",
+    "jsonschema>=4.23.0",
+    "fastmcp>=2.0.0",
+    "ruff>=0.8.0",
+    "twine>=5.0.0",
+    "typing_extensions>=4.12.0",
+    "weasyprint>=62",
+    "xlsxwriter>=3.2.0",
+]
+
+[tool.uv]
+default-groups = ["dev"]
+
+[build-system]
+requires = ["setuptools>=77.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+grid_view_spec = [
+    "py.typed",
+    "templates/**/*.html",
+    "schema/*.json",
+    "static/**/*",
+    "locale/**/*.po",
+    "locale/**/*.mo",
+]
+
+[tool.pytest.ini_options]
+addopts = "--ds=tests.settings"
+pythonpath = ["src", ".", "tests"]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+exclude = ["*/migrations/*"]
+
+[tool.django-stubs]
+django_settings_module = "tests.settings"
+
+[tool.basedpyright]
+include = ["src/grid_view_spec", "tests"]
+exclude = ["**/migrations/**", "**/__pycache__/**", "hooks/**"]
+typeCheckingMode = "strict"
+pythonVersion = "3.11"
+reportMissingTypeStubs = false
+stubPath = "typings"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]

grid_view_spec-2.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

grid_view_spec-2.0.0/src/grid_view_spec/__init__.py

@@ -0,0 +1,23 @@
+"""Framework-agnostic GridViewSpec vNext contract (grid-view-spec 2.x)."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from grid_view_spec.types import GridViewBlock, GridViewSpec, GridViewTable, GridViewToolbar
+from grid_view_spec.validate import normalize_spec, spec_from_wire, spec_to_wire, validate_spec
+
+try:
+    __version__ = version("grid-view-spec")
+except PackageNotFoundError:
+    __version__ = "2.0.0"
+
+__all__ = [
+    "GridViewBlock",
+    "GridViewSpec",
+    "GridViewTable",
+    "GridViewToolbar",
+    "__version__",
+    "normalize_spec",
+    "spec_from_wire",
+    "spec_to_wire",
+    "validate_spec",
+]

grid_view_spec-2.0.0/src/grid_view_spec/backends/django/__init__.py

@@ -0,0 +1,43 @@
+"""Django host backend adapters."""
+
+from typing import TYPE_CHECKING
+
+from grid_view_spec.backends.django.host import DjangoGridViewHost
+from grid_view_spec.backends.django.prefs import DjangoOrmPrefs
+
+if TYPE_CHECKING:
+    from grid_view_spec.backends.django.views import (
+        django_host,
+        export_pdf,
+        export_xlsx,
+        load_lazy_block,
+        render_lazy_block_response,
+        save_grid_prefs,
+    )
+
+__all__ = [
+    "DjangoGridViewHost",
+    "DjangoOrmPrefs",
+    "django_host",
+    "export_pdf",
+    "export_xlsx",
+    "load_lazy_block",
+    "render_lazy_block_response",
+    "save_grid_prefs",
+]
+
+
+def __getattr__(name: str) -> object:
+    if name in {
+        "django_host",
+        "export_pdf",
+        "export_xlsx",
+        "load_lazy_block",
+        "render_lazy_block_response",
+        "save_grid_prefs",
+    }:
+        from grid_view_spec.backends.django import views
+
+        return getattr(views, name)
+    msg = f"module {__name__!r} has no attribute {name!r}"
+    raise AttributeError(msg)

grid_view_spec-2.0.0/src/grid_view_spec/backends/django/ag_grid/__init__.py

@@ -0,0 +1,26 @@
+"""AG-Grid infinite row model — server-side query helpers."""
+
+from grid_view_spec.backends.django.ag_grid.export import (
+    EXPORT_COLS_PARAM,
+    parse_active_col_ids,
+    resolve_export_columns,
+)
+from grid_view_spec.backends.django.ag_grid.server import (
+    InfiniteGridParams,
+    apply_grid_filters,
+    apply_grid_sort,
+    parse_infinite_params,
+)
+from grid_view_spec.types.ag_grid import AgGridColumnSpec, AgGridPageSpec
+
+__all__ = [
+    "AgGridColumnSpec",
+    "AgGridPageSpec",
+    "EXPORT_COLS_PARAM",
+    "InfiniteGridParams",
+    "apply_grid_filters",
+    "apply_grid_sort",
+    "parse_active_col_ids",
+    "parse_infinite_params",
+    "resolve_export_columns",
+]

grid_view_spec-2.0.0/src/grid_view_spec/backends/django/ag_grid/export.py

@@ -0,0 +1,26 @@
+"""Resolve AG-Grid export columns from page spec + optional live grid snapshot."""
+
+from __future__ import annotations
+
+from django.http import HttpRequest
+from grid_view_spec.types.ag_grid import AgGridPageSpec
+
+EXPORT_COLS_PARAM = "export_cols"
+
+
+def parse_active_col_ids(
+    request: HttpRequest,
+    *,
+    param: str = EXPORT_COLS_PARAM,
+) -> tuple[str, ...]:
+    """Read comma-separated active column ids synced from the browser grid."""
+    raw = request.GET.get(param, "")
+    return tuple(col_id.strip() for col_id in raw.split(",") if col_id.strip())
+
+
+def resolve_export_columns(
+    spec: AgGridPageSpec,
+    request: HttpRequest,
+) -> list[str]:
+    """Resolve export column order from *spec* and optional ``export_cols`` query param."""
+    return spec.resolve_export_columns(parse_active_col_ids(request))