djangorestframework-tabulator 0.1.0__py3-none-any.whl

djangorestframework_tabulator-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,8 @@
+rest_framework_tabulator/__init__.py,sha256=CaNVrNVPDykAIqI83caW4C69Fzblx13DEKcHYQ9_HJw,379
+rest_framework_tabulator/filters.py,sha256=xVsJai1nG--VXsugzuToSHZQNCAfle8gm5hpn21s3Go,9816
+rest_framework_tabulator/pagination.py,sha256=hpIXhNKM-snwvr0MBMonepqOEVqyHrs4ObY-ASNgVCQ,2078
+rest_framework_tabulator/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+djangorestframework_tabulator-0.1.0.dist-info/METADATA,sha256=6Zddb1Sp9sWvvyE0OxBFQVfk2nwy1i64OSEacvxStiU,7504
+djangorestframework_tabulator-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+djangorestframework_tabulator-0.1.0.dist-info/licenses/LICENSE,sha256=A5tLhf0hAM09ItVNP4fXQ88Ti8BC7mpzC_oP-tL5xtw,1117
+djangorestframework_tabulator-0.1.0.dist-info/RECORD,,

djangorestframework_tabulator-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

djangorestframework_tabulator-0.1.0.dist-info/licenses/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.

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',
+]

rest_framework_tabulator/filters.py

@@ -0,0 +1,273 @@
+# Copyright (C) 2026 Esteban De La Fuente Rubio / Derafu <https://www.derafu.dev>
+# SPDX-License-Identifier: MIT
+
+"""Tabulator's remote filtering and sorting."""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING, Any
+
+from django.core.exceptions import ValidationError as DjangoValidationError
+from django.db.models import Q
+from rest_framework.exceptions import ValidationError
+from rest_framework.filters import BaseFilterBackend
+
+if TYPE_CHECKING:
+    from django.db.models import QuerySet
+    from rest_framework.request import Request
+    from rest_framework.views import APIView
+
+# `filter[0][field]=date&filter[0][type]=>=&filter[0][value]=2026-01-01`,
+# `filter[0][value][0]=a&filter[0][value][1]=b` for an array value (the
+# `in` type), and `sort[0][field]=date&sort[0][dir]=desc` — Django does
+# not nest bracketed keys on its own (`request.GET` keeps each one as a
+# literal key, e.g. `'filter[0][field]'`), so they have to be parsed by
+# hand.
+_FILTER_FIELD = re.compile(r'^filter\[(\d+)\]\[field\]$')
+_FILTER_TYPE = re.compile(r'^filter\[(\d+)\]\[type\]$')
+_FILTER_VALUE = re.compile(r'^filter\[(\d+)\]\[value\]$')
+_FILTER_VALUE_ITEM = re.compile(r'^filter\[(\d+)\]\[value\]\[(\d+)\]$')
+_SORT_KEY = re.compile(r'^sort\[(\d+)\]\[(field|dir)\]$')
+
+# Tabulator type -> Django ORM lookup, for the types that map to a plain
+# `field__lookup=value` query. `=`/`!=` are handled separately (equality
+# needs no suffix, negation needs `~Q(...)`); `smart`/`smarter` build a
+# `Q` of their own (see `_smart_filter`/`_smarter_filter`) since they
+# don't reduce to a single lookup.
+_LOOKUP_BY_TYPE = {
+    'like': 'icontains',
+    # Tabulator's own `keywords` type additionally supports a custom
+    # word separator and an "all words must match" toggle
+    # (`headerFilterFuncParams`) — neither is sent to the server in
+    # remote mode (confirmed against `Filter.js`: the ajax payload only
+    # ever carries `{field, type, value}`), so this is approximated as
+    # a plain substring match, same as `like`.
+    'keywords': 'icontains',
+    'starts': 'istartswith',
+    'ends': 'iendswith',
+    'regex': 'regex',
+    'in': 'in',
+    '<': 'lt',
+    '<=': 'lte',
+    '>': 'gt',
+    '>=': 'gte',
+}
+
+_IMPOSSIBLE = Q(pk__in=[])
+
+
+def _parse_filters(query_params: Any) -> dict[str, dict[str, Any]]:
+    """Group `filter[i][...]` keys into `{i: {field, type, value}}`."""
+    entries: dict[str, dict[str, Any]] = {}
+    value_items: dict[str, dict[int, str]] = {}
+
+    for key, value in query_params.items():
+        if match := _FILTER_FIELD.match(key):
+            entries.setdefault(match.group(1), {})['field'] = value
+        elif match := _FILTER_TYPE.match(key):
+            entries.setdefault(match.group(1), {})['type'] = value
+        elif match := _FILTER_VALUE.match(key):
+            entries.setdefault(match.group(1), {})['value'] = value
+        elif match := _FILTER_VALUE_ITEM.match(key):
+            index, position = match.groups()
+            value_items.setdefault(index, {})[int(position)] = value
+
+    for index, items in value_items.items():
+        entries.setdefault(index, {})['value'] = [
+            items[position] for position in sorted(items)
+        ]
+
+    return entries
+
+
+def _parse_sorters(query_params: Any) -> dict[str, dict[str, str]]:
+    """Group `sort[i][...]` keys into `{i: {field, dir}}`."""
+    grouped: dict[str, dict[str, str]] = {}
+    for key, value in query_params.items():
+        match = _SORT_KEY.match(key)
+        if not match:
+            continue
+        index, subkey = match.groups()
+        grouped.setdefault(index, {})[subkey] = value
+    return grouped
+
+
+def _numeric_comparison(field: str, lookup: str, raw_number: str) -> Q:
+    """
+    `field__lookup=value`, or a clause that matches nothing.
+
+    Same behaviour as Tabulator's own comparison filters: comparing
+    against a value that isn't a number never matches, rather than
+    raising an error.
+    """
+    try:
+        value = float(raw_number.strip())
+    except ValueError:
+        return _IMPOSSIBLE
+    return Q(**{f'{field}__{lookup}': value})
+
+
+def _smart_filter(field: str, raw: str) -> Q:
+    """
+    Port of Tabulator's own `smart` filter function to a Django `Q`.
+
+    Faithfully mirrors `Filter/defaults/filters.js` (``smart``): ``.``
+    matches any non-empty value, ``!`` matches empty/null, a leading
+    comparison operator (``<``, ``<=``, ``>``, ``>=``) does a numeric
+    comparison, a leading ``=`` does an exact match on the rest of the
+    string, several whitespace-separated words become an ``AND`` of a
+    substring match per word (delegated to `_smarter_filter`), and
+    anything else falls back to a plain substring match.
+    """
+    search = raw.strip()
+
+    if search == '.':
+        return ~Q(**{f'{field}__isnull': True}) & ~Q(**{field: ''})
+    if search == '!':
+        return Q(**{f'{field}__isnull': True}) | Q(**{field: ''})
+
+    comparisons = (('<=', 'lte'), ('>=', 'gte'), ('<', 'lt'), ('>', 'gt'))
+    for operator, lookup in comparisons:
+        if search.startswith(operator):
+            return _numeric_comparison(field, lookup, search[len(operator) :])
+
+    if search.startswith('='):
+        return Q(**{field: search[1:].strip()})
+
+    if ' ' in search:
+        terms = [term for term in search.split() if term]
+        if len(terms) > 1:
+            return _smarter_filter(field, ' AND '.join(terms))
+
+    return Q(**{f'{field}__icontains': search})
+
+
+def _smarter_filter(field: str, raw: str) -> Q:
+    """
+    Port of Tabulator's own `smarter` filter function to a Django `Q`.
+
+    Splits on ``AND``/``OR`` (case-insensitive) and combines each part's
+    `_smart_filter` clause left to right, in the order they appear — no
+    operator precedence, same as the original.
+    """
+    search = raw.strip()
+    if not search:
+        return Q()
+
+    parts = re.split(r'\s+(AND|OR)\s+', search, flags=re.IGNORECASE)
+    if len(parts) == 1:
+        return _smart_filter(field, search)
+
+    result: Q | None = None
+    operator = 'AND'
+    for raw_part in parts:
+        part = raw_part.strip()
+        if part.upper() in ('AND', 'OR'):
+            operator = part.upper()
+            continue
+        clause = _smart_filter(field, part)
+        if result is None:
+            result = clause
+        elif operator == 'OR':
+            result |= clause
+        else:
+            result &= clause
+
+    return result if result is not None else Q()
+
+
+_Q_BUILDERS = {
+    'smart': _smart_filter,
+    'smarter': _smarter_filter,
+}
+
+
+def _error_message(error: Exception) -> str:
+    """Plain text out of a `ValueError`/`ValidationError`."""
+    messages = getattr(error, 'messages', None)
+    return ' '.join(messages) if messages else str(error)
+
+
+class TabulatorFilterBackend(BaseFilterBackend):
+    """
+    Translates the `filter`/`sort` Tabulator sends in remote mode.
+
+    Allowed fields are declared on the view, not here:
+    `filterset_fields`/`ordering_fields` (same attribute names already
+    used by `django-filter`/`rest_framework.filters.OrderingFilter`, so
+    they look familiar) — any field not declared there is silently
+    ignored. A field is never exposed just because the client asked for
+    it.
+    """
+
+    def filter_queryset(
+        self,
+        request: Request,
+        queryset: QuerySet[Any],
+        view: APIView,
+    ) -> QuerySet[Any]:
+        """Apply filtering, then sorting, to `queryset`."""
+        queryset = self._filter(request, queryset, view)
+        return self._sort(request, queryset, view)
+
+    def _filter(
+        self,
+        request: Request,
+        queryset: QuerySet[Any],
+        view: APIView,
+    ) -> QuerySet[Any]:
+        allowed = set(getattr(view, 'filterset_fields', None) or [])
+        entries = _parse_filters(request.query_params)
+
+        for entry in entries.values():
+            field = entry.get('field')
+            value = entry.get('value')
+            if not field or not value or field not in allowed:
+                continue
+
+            operator = entry.get('type', '=')
+            builder = _Q_BUILDERS.get(operator)
+            if builder:
+                clause = builder(field, value)
+            elif operator == '!=':
+                clause = ~Q(**{field: value})
+            else:
+                lookup = _LOOKUP_BY_TYPE.get(operator)
+                key = f'{field}__{lookup}' if lookup else field
+                clause = Q(**{key: value})
+
+            # Applied one entry at a time (equivalent to combining every
+            # clause with `&` and filtering once) so that a value that
+            # doesn't fit the field's type — Django validates this
+            # eagerly, right here at `.filter()`, not lazily when the
+            # queryset is evaluated — can be blamed on the field that
+            # caused it, and turned into a clean `400` instead of
+            # bubbling up as an unhandled `500`.
+            try:
+                queryset = queryset.filter(clause)
+            except (TypeError, ValueError, DjangoValidationError) as error:
+                raise ValidationError(
+                    {field: _error_message(error)},
+                ) from error
+
+        return queryset
+
+    def _sort(
+        self,
+        request: Request,
+        queryset: QuerySet[Any],
+        view: APIView,
+    ) -> QuerySet[Any]:
+        allowed = set(getattr(view, 'ordering_fields', None) or [])
+        entries = _parse_sorters(request.query_params)
+
+        ordering = []
+        for entry in entries.values():
+            field = entry.get('field')
+            if not field or field not in allowed:
+                continue
+            descending = entry.get('dir') == 'desc'
+            ordering.append(f'-{field}' if descending else field)
+
+        return queryset.order_by(*ordering) if ordering else queryset

rest_framework_tabulator/pagination.py

@@ -0,0 +1,60 @@
+# Copyright (C) 2026 Esteban De La Fuente Rubio / Derafu <https://www.derafu.dev>
+# SPDX-License-Identifier: MIT
+
+"""Tabulator's remote pagination."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from rest_framework.pagination import PageNumberPagination
+from rest_framework.response import Response
+
+
+class TabulatorPagination(PageNumberPagination):
+    """
+    Shapes the paginated response the way Tabulator expects in remote mode.
+
+    Tabulator sends `page`/`size` as query params (confirmed against
+    Tabulator's own `Page.js`, not its documentation) — both names
+    already match what `PageNumberPagination` uses, so nothing needs
+    translating; `size` just needs to be turned into a client-
+    controllable option. The response Tabulator expects is
+    `{"data": [...], "last_page": N}`, not DRF's own `{count, next,
+    previous, results}` — that's the one method overridden here.
+    """
+
+    page_query_param = 'page'
+    page_size_query_param = 'size'
+    page_size = 20
+    max_page_size = 200
+
+    def get_paginated_response(self, data: list[Any]) -> Response:
+        """`{"data": [...], "last_page": N}` — the shape Tabulator expects."""
+        # `self.page` is only ever `None` before `paginate_queryset()` has
+        # run — DRF always calls that first, and only reaches this method
+        # if it returned something, so it's never `None` here.
+        assert self.page is not None
+        return Response(
+            {
+                'last_page': self.page.paginator.num_pages,
+                'data': data,
+            },
+        )
+
+    def get_paginated_response_schema(
+        self,
+        schema: dict[str, Any],
+    ) -> dict[str, Any]:
+        """OpenAPI schema for the shape above, for anyone generating docs."""
+        return {
+            'type': 'object',
+            'required': ['data', 'last_page'],
+            'properties': {
+                'last_page': {
+                    'type': 'integer',
+                    'example': 4,
+                },
+                'data': schema,
+            },
+        }