djangorestframework-tabulator 0.1.0__tar.gz

djangorestframework_tabulator-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,82 @@
+name: CI
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  tests:
+    name: Tests
+    timeout-minutes: 10
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ['3.10', '3.12', '3.14']
+        django-version: ['4.2', '5.1', '6.1']
+        exclude:
+          # Django 6.x dropped support for Python < 3.12.
+          - python-version: '3.10'
+            django-version: '6.1'
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Display Python version
+        run: python --version
+
+      - name: Install dependencies
+        # Django and the package's own dependencies (which include an
+        # unpinned djangorestframework) are resolved together, in one
+        # call — installing them separately lets pip pick the latest
+        # djangorestframework first regardless of the Django version
+        # this job is testing, which can be incompatible with it
+        # (confirmed: djangorestframework 3.18 requires django>=5.2, so
+        # forcing an older Django on top afterwards leaves a broken
+        # environment instead of the older djangorestframework pip
+        # would have picked resolving both together).
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e '.[dev]' "django==${{ matrix.django-version }}.*"
+
+      - name: Run Ruff (lint)
+        run: ruff check .
+
+      - name: Run Ruff (format)
+        run: ruff format --check .
+
+      - name: Run mypy
+        run: mypy
+
+      - name: Run pytest
+        run: |
+          mkdir -p var
+          pytest -v \
+            --junitxml=var/tests-results.xml \
+            --cov=rest_framework_tabulator \
+            --cov-report=xml:var/tests-coverage.xml
+
+      - name: Upload pytest result report
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: tests-results-python_${{ matrix.python-version }}-django_${{ matrix.django-version }}.xml
+          path: var/tests-results.xml
+
+      - name: Upload Coverage Report
+        uses: actions/upload-artifact@v4
+        with:
+          name: tests-coverage-python_${{ matrix.python-version }}-django_${{ matrix.django-version }}.xml
+          path: var/tests-coverage.xml

djangorestframework_tabulator-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+# Python.
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+dist/
+build/
+.coverage
+var/
+
+# Operating-system specific files.
+.DS_Store

djangorestframework_tabulator-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (C) 2026 Esteban De La Fuente Rubio / Derafu <https://www.derafu.dev>
+
+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.

djangorestframework_tabulator-0.1.0/Makefile

@@ -0,0 +1,40 @@
+.PHONY: install-dev lint format format-check typecheck test check build upload clean
+
+VENV = .venv
+VENV_READY = $(VENV)/.installed
+
+$(VENV_READY): pyproject.toml
+	python3 -m venv $(VENV)
+	$(VENV)/bin/pip install --upgrade pip
+	$(VENV)/bin/pip install -e '.[dev]'
+	touch $(VENV_READY)
+
+install-dev: $(VENV_READY)
+
+lint: $(VENV_READY)
+	$(VENV)/bin/ruff check .
+
+format: $(VENV_READY)
+	$(VENV)/bin/ruff format .
+
+format-check: $(VENV_READY)
+	$(VENV)/bin/ruff format --check .
+
+typecheck: $(VENV_READY)
+	$(VENV)/bin/mypy
+
+test: $(VENV_READY)
+	$(VENV)/bin/pytest -v
+
+check: lint format-check typecheck test
+
+build: $(VENV_READY)
+	$(VENV)/bin/python -m build
+
+upload: build
+	$(VENV)/bin/twine check dist/*
+	$(VENV)/bin/twine upload dist/*
+
+clean:
+	rm -rf dist build *.egg-info .pytest_cache .ruff_cache .mypy_cache
+	find . -type d -name __pycache__ -exec rm -rf {} +

djangorestframework_tabulator-0.1.0/PKG-INFO

@@ -0,0 +1,186 @@
+Metadata-Version: 2.5
+Name: djangorestframework-tabulator
+Version: 0.1.0
+Summary: Remote pagination and filtering for Tabulator (tabulator.info) on Django REST Framework.
+Author: Esteban De La Fuente Rubio / Derafu
+License: MIT License
+        
+        Copyright (C) 2026 Esteban De La Fuente Rubio / Derafu <https://www.derafu.dev>
+        
+        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.
+License-File: LICENSE
+Keywords: django,djangorestframework,filtering,pagination,tabulator
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4
+Classifier: Framework :: Django :: 5
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: django>=4.2
+Requires-Dist: djangorestframework>=3.15
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: django-stubs; extra == 'dev'
+Requires-Dist: djangorestframework-stubs; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest-django; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/x-rst
+
+djangorestframework-tabulator
+==============================
+
+|build-status-image| |pypi-version| |py-versions|
+
+Remote pagination and filtering for `Tabulator <https://tabulator.info>`_
+on top of `Django REST Framework <https://www.django-rest-framework.org>`_.
+
+Why this exists
+----------------
+
+Tabulator, in remote mode (``pagination: "remote"``, ``filterMode:
+"remote"``, ``sortMode: "remote"``), sends pagination/filtering/sorting
+using its own query string convention, and expects the response back in
+its own shape — neither matches what DRF ships out of the box
+(``PageNumberPagination`` responds with ``{count, next, previous,
+results}``; its ``filter_backends`` don't understand nested bracketed
+keys). This package translates both sides. `jQuery DataTables
+<https://datatables.net>`_ already has a mature DRF adapter
+(`djangorestframework-datatables
+<https://pypi.org/project/djangorestframework-datatables/>`_); no
+equivalent exists for Tabulator.
+
+Usage
+-----
+
+.. code-block:: python
+
+    from rest_framework.generics import ListAPIView
+    from rest_framework_tabulator import TabulatorFilterBackend, TabulatorPagination
+
+    class DocumentListView(ListAPIView):
+        queryset = Document.objects.all()
+        serializer_class = DocumentSerializer
+        pagination_class = TabulatorPagination
+        filter_backends = [TabulatorFilterBackend]
+        filterset_fields = ['number', 'status', 'issued_at']
+        ordering_fields = ['issued_at', 'number', 'total']
+
+Tabulator's contract (confirmed against the source code of
+``tabulator-tables/tabulator`` itself, not third-party documentation):
+
+- Request: ``page``/``size`` (pagination), ``sort[i][field]``/
+  ``sort[i][dir]`` (sorting), ``filter[i][field]``/``filter[i][type]``/
+  ``filter[i][value]`` (filtering) — an array value (the ``in`` type) is
+  sent as ``filter[i][value][0]``, ``filter[i][value][1]``, etc.
+- Expected response: ``{"data": [...], "last_page": N}``.
+
+``filterset_fields``/``ordering_fields`` on the view are allowlists of
+fields (same attribute names ``django-filter``/``rest_framework.filters
+.OrderingFilter`` already use, so they look familiar) — any field not
+declared there is silently ignored, on both the filter and the sort
+side. Leaving either one undeclared denies filtering/sorting entirely
+rather than allowing every field by default.
+
+Supported filter types
+-----------------------
+
+Every filter type Tabulator ships is supported (confirmed against
+``Filter/defaults/filters.js`` in the Tabulator source for the exact
+set of built-in types):
+
+.. list-table::
+   :header-rows: 1
+
+   * - Tabulator ``type``
+     - Django lookup
+   * - ``=``
+     - exact
+   * - ``!=``
+     - negated exact
+   * - ``<``, ``<=``, ``>``, ``>=``
+     - ``lt``, ``lte``, ``gt``, ``gte``
+   * - ``like``
+     - ``icontains``
+   * - ``keywords``
+     - ``icontains`` (see note below)
+   * - ``starts``
+     - ``istartswith``
+   * - ``ends``
+     - ``iendswith``
+   * - ``regex``
+     - ``regex``
+   * - ``in``
+     - ``in`` (array value)
+   * - ``smart``
+     - ported from Tabulator's own ``smart`` filter
+   * - ``smarter``
+     - ported from Tabulator's own ``smarter`` filter
+
+``keywords`` note: Tabulator's client-side ``keywords`` filter also
+supports a custom word separator and an "all words must match" toggle
+(``headerFilterFuncParams``), but neither is sent to the server in
+remote mode — the ajax payload only ever carries ``{field, type,
+value}``. It is approximated here as a plain substring match, same as
+``like``.
+
+``smart``/``smarter`` are a faithful port of Tabulator's own filter
+functions, not a Django-specific addition: ``.`` matches any non-empty
+value, ``!`` matches empty/null, a leading comparison operator does a
+numeric comparison, a leading ``=`` does an exact match, multiple
+whitespace-separated words become an ``AND`` of a substring match per
+word, ``AND``/``OR`` combine sub-expressions left to right (no operator
+precedence, same as the original), and anything else falls back to a
+substring match.
+
+A value that doesn't fit the field's type (e.g. a non-numeric string
+against an integer field, or an invalid date) raises a DRF
+``ValidationError`` — a clean ``400`` naming the offending field —
+instead of an unhandled ``500``. Django validates most field types
+eagerly, right when the filter is applied, so this is caught there
+rather than only when the queryset is evaluated.
+
+License
+-------
+
+MIT — see ``LICENSE``.
+
+Development
+-----------
+
+.. code-block:: bash
+
+    pip install -e '.[dev]'
+    pytest
+
+.. |build-status-image| image:: https://github.com/derafu/djangorestframework-tabulator/actions/workflows/ci.yml/badge.svg
+   :target: https://github.com/derafu/djangorestframework-tabulator/actions/workflows/ci.yml
+   :alt: CI
+
+.. |pypi-version| image:: https://img.shields.io/pypi/v/djangorestframework-tabulator.svg
+   :target: https://pypi.org/project/djangorestframework-tabulator/
+   :alt: Pypi version
+
+.. |py-versions| image:: https://img.shields.io/pypi/pyversions/djangorestframework-tabulator.svg
+   :target: https://pypi.org/project/djangorestframework-tabulator/
+   :alt: Python versions

djangorestframework_tabulator-0.1.0/README.rst

@@ -0,0 +1,137 @@
+djangorestframework-tabulator
+==============================
+
+|build-status-image| |pypi-version| |py-versions|
+
+Remote pagination and filtering for `Tabulator <https://tabulator.info>`_
+on top of `Django REST Framework <https://www.django-rest-framework.org>`_.
+
+Why this exists
+----------------
+
+Tabulator, in remote mode (``pagination: "remote"``, ``filterMode:
+"remote"``, ``sortMode: "remote"``), sends pagination/filtering/sorting
+using its own query string convention, and expects the response back in
+its own shape — neither matches what DRF ships out of the box
+(``PageNumberPagination`` responds with ``{count, next, previous,
+results}``; its ``filter_backends`` don't understand nested bracketed
+keys). This package translates both sides. `jQuery DataTables
+<https://datatables.net>`_ already has a mature DRF adapter
+(`djangorestframework-datatables
+<https://pypi.org/project/djangorestframework-datatables/>`_); no
+equivalent exists for Tabulator.
+
+Usage
+-----
+
+.. code-block:: python
+
+    from rest_framework.generics import ListAPIView
+    from rest_framework_tabulator import TabulatorFilterBackend, TabulatorPagination
+
+    class DocumentListView(ListAPIView):
+        queryset = Document.objects.all()
+        serializer_class = DocumentSerializer
+        pagination_class = TabulatorPagination
+        filter_backends = [TabulatorFilterBackend]
+        filterset_fields = ['number', 'status', 'issued_at']
+        ordering_fields = ['issued_at', 'number', 'total']
+
+Tabulator's contract (confirmed against the source code of
+``tabulator-tables/tabulator`` itself, not third-party documentation):
+
+- Request: ``page``/``size`` (pagination), ``sort[i][field]``/
+  ``sort[i][dir]`` (sorting), ``filter[i][field]``/``filter[i][type]``/
+  ``filter[i][value]`` (filtering) — an array value (the ``in`` type) is
+  sent as ``filter[i][value][0]``, ``filter[i][value][1]``, etc.
+- Expected response: ``{"data": [...], "last_page": N}``.
+
+``filterset_fields``/``ordering_fields`` on the view are allowlists of
+fields (same attribute names ``django-filter``/``rest_framework.filters
+.OrderingFilter`` already use, so they look familiar) — any field not
+declared there is silently ignored, on both the filter and the sort
+side. Leaving either one undeclared denies filtering/sorting entirely
+rather than allowing every field by default.
+
+Supported filter types
+-----------------------
+
+Every filter type Tabulator ships is supported (confirmed against
+``Filter/defaults/filters.js`` in the Tabulator source for the exact
+set of built-in types):
+
+.. list-table::
+   :header-rows: 1
+
+   * - Tabulator ``type``
+     - Django lookup
+   * - ``=``
+     - exact
+   * - ``!=``
+     - negated exact
+   * - ``<``, ``<=``, ``>``, ``>=``
+     - ``lt``, ``lte``, ``gt``, ``gte``
+   * - ``like``
+     - ``icontains``
+   * - ``keywords``
+     - ``icontains`` (see note below)
+   * - ``starts``
+     - ``istartswith``
+   * - ``ends``
+     - ``iendswith``
+   * - ``regex``
+     - ``regex``
+   * - ``in``
+     - ``in`` (array value)
+   * - ``smart``
+     - ported from Tabulator's own ``smart`` filter
+   * - ``smarter``
+     - ported from Tabulator's own ``smarter`` filter
+
+``keywords`` note: Tabulator's client-side ``keywords`` filter also
+supports a custom word separator and an "all words must match" toggle
+(``headerFilterFuncParams``), but neither is sent to the server in
+remote mode — the ajax payload only ever carries ``{field, type,
+value}``. It is approximated here as a plain substring match, same as
+``like``.
+
+``smart``/``smarter`` are a faithful port of Tabulator's own filter
+functions, not a Django-specific addition: ``.`` matches any non-empty
+value, ``!`` matches empty/null, a leading comparison operator does a
+numeric comparison, a leading ``=`` does an exact match, multiple
+whitespace-separated words become an ``AND`` of a substring match per
+word, ``AND``/``OR`` combine sub-expressions left to right (no operator
+precedence, same as the original), and anything else falls back to a
+substring match.
+
+A value that doesn't fit the field's type (e.g. a non-numeric string
+against an integer field, or an invalid date) raises a DRF
+``ValidationError`` — a clean ``400`` naming the offending field —
+instead of an unhandled ``500``. Django validates most field types
+eagerly, right when the filter is applied, so this is caught there
+rather than only when the queryset is evaluated.
+
+License
+-------
+
+MIT — see ``LICENSE``.
+
+Development
+-----------
+
+.. code-block:: bash
+
+    pip install -e '.[dev]'
+    pytest
+
+.. |build-status-image| image:: https://github.com/derafu/djangorestframework-tabulator/actions/workflows/ci.yml/badge.svg
+   :target: https://github.com/derafu/djangorestframework-tabulator/actions/workflows/ci.yml
+   :alt: CI
+
+.. |pypi-version| image:: https://img.shields.io/pypi/v/djangorestframework-tabulator.svg
+   :target: https://pypi.org/project/djangorestframework-tabulator/
+   :alt: Pypi version
+
+.. |py-versions| image:: https://img.shields.io/pypi/pyversions/djangorestframework-tabulator.svg
+   :target: https://pypi.org/project/djangorestframework-tabulator/
+   :alt: Python versions

djangorestframework_tabulator-0.1.0/pyproject.toml

@@ -0,0 +1,120 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "djangorestframework-tabulator"
+version = "0.1.0"
+description = "Remote pagination and filtering for Tabulator (tabulator.info) on Django REST Framework."
+readme = "README.rst"
+license = { file = "LICENSE" }
+authors = [
+  { name = "Esteban De La Fuente Rubio / Derafu" },
+]
+requires-python = ">=3.10"
+keywords = ["django", "djangorestframework", "tabulator", "pagination", "filtering"]
+classifiers = [
+  "Framework :: Django",
+  "Framework :: Django :: 4",
+  "Framework :: Django :: 5",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Intended Audience :: Developers",
+]
+dependencies = [
+  "django>=4.2",
+  "djangorestframework>=3.15",
+]
+
+[project.optional-dependencies]
+dev = [
+  "ruff",
+  "mypy",
+  "django-stubs",
+  "djangorestframework-stubs",
+  "pytest",
+  "pytest-django",
+  "pytest-cov",
+  "build",
+  "twine",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["rest_framework_tabulator"]
+
+[tool.pytest.ini_options]
+DJANGO_SETTINGS_MODULE = "tests.settings"
+python_files = ["test_*.py"]
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+files = ["rest_framework_tabulator"]
+
+[tool.ruff]
+
+include = ["**/*.py", "**/*.pyi"]
+
+exclude = [
+  ".git",
+  "__pycache__",
+  ".venv",
+  "venv",
+]
+
+line-length = 79
+target-version = "py310"
+respect-gitignore = true
+fix = true
+
+[tool.ruff.lint]
+
+select = [
+  "D",
+  "F",
+  "E",
+  "W",
+  "I",
+  "UP",
+  "N",
+  "B",
+  "A",
+  "C90",
+  "ARG",
+  "DTZ",
+  "TRY",
+  "SLF",
+  "ERA",
+  "PL",
+  "RUF",
+  "DJ",
+]
+
+ignore = [
+  "D100",
+  "D101",
+  "D102",
+  "D104",
+  "D105",
+  "D106",
+  "D203",
+  "D212",
+  "D401",
+  "TRY400",
+  "N818",
+  "TRY003",
+  "ARG001",
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["rest_framework_tabulator"]
+
+[tool.ruff.lint.mccabe]
+max-complexity = 25
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["D", "SLF", "PLR2004"]
+
+[tool.ruff.format]
+quote-style = "single"

djangorestframework_tabulator-0.1.0/rest_framework_tabulator/__init__.py

@@ -0,0 +1,14 @@
+# Copyright (C) 2026 Esteban De La Fuente Rubio / Derafu <https://www.derafu.dev>
+# SPDX-License-Identifier: MIT
+
+"""Tabulator (tabulator.info) adapter for Django REST Framework."""
+
+from __future__ import annotations
+
+from .filters import TabulatorFilterBackend
+from .pagination import TabulatorPagination
+
+__all__ = [
+    'TabulatorFilterBackend',
+    'TabulatorPagination',
+]