drf-react-by-schema 0.28.1__tar.gz → 0.28.3__tar.gz

{drf_react_by_schema-0.28.1 → drf_react_by_schema-0.28.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: drf_react_by_schema
-Version: 0.28.1
+Version: 0.28.3
 Summary: A Django app to easily integrate with React from models.
 Home-page: https://gitlab.com/eita/drf-react-by-schema/drf-react-by-schema-django
 Author: Cooperativa EITA
@@ -115,6 +115,52 @@ single release line. The supported combinations are exercised in CI (see
        drf-react-by-schema
        drf-excel<2.6
 
+Django 3.2 is kept as **legacy support**: the 3.2-only pin above and its CI job
+will be dropped when the supported floor moves to 4.2. New code should target
+4.2-5.2; Django-3.2-only branches must stay isolated so the migration is a single
+clean-up pass.
+
+Accent-insensitive search
+-------------------------
+On PostgreSQL with the ``unaccent`` extension enabled (and
+``django.contrib.postgres`` in ``INSTALLED_APPS``), replace DRF's search filter
+with the package's::
+
+    REST_FRAMEWORK = {
+        "DEFAULT_FILTER_BACKENDS": [
+            "drf_react_by_schema.filters.DRFReactBySchemaSearchFilter",
+            "drf_react_by_schema.filters.DRFReactBySchemaOrderingFilter",
+        ],
+    }
+
+``unaccent`` is applied only to text fields; dates, numbers and booleans keep
+DRF's default lookup, because ``unaccent`` raises on them.
+
+The filter also orders the hits by relevance. It concatenates the short text
+(``CharField``) paths of ``search_fields``, in order, and scores the whole query
+against that label: exact match (100), prefix (80), substring (60). The first
+path is scored on its own as well, so ``nome`` keeps its exact/prefix bonus even
+when the label also contains phone/e-mail fields. Records that only match all
+the terms across fields keep score 0 and are ordered by ``pk`` as a stable
+tiebreaker. An explicit ``?ordering=`` always wins over relevance. ``TextField``
+paths (long free text such as notes) stay out of the label.
+
+The filter is **opt-in**: apps that keep DRF's ``SearchFilter`` are unaffected
+and do not need the extension. It probes the backend, ``INSTALLED_APPS`` and the
+database extension once per connection alias. If the extension is missing — or
+the database is not PostgreSQL, or ``django.contrib.postgres`` is not installed
+— it falls back to DRF's normal lookups: search keeps working (accent-sensitive)
+instead of raising ``FieldError``. Call
+``drf_react_by_schema.filters.reset_unaccent_cache()`` if the extension is
+installed while the process is running.
+
+To create the extension, add a migration in the consuming app::
+
+    from django.contrib.postgres.operations import UnaccentExtension
+
+    class Migration(migrations.Migration):
+        operations = [UnaccentExtension()]
+
 Optional Dependencies
 ---------------------
 For enhanced caching capabilities in the automatically generated viewsets, you can install optional dependencies:

{drf_react_by_schema-0.28.1 → drf_react_by_schema-0.28.3}/README.rst

@@ -83,6 +83,52 @@ single release line. The supported combinations are exercised in CI (see
        drf-react-by-schema
        drf-excel<2.6
 
+Django 3.2 is kept as **legacy support**: the 3.2-only pin above and its CI job
+will be dropped when the supported floor moves to 4.2. New code should target
+4.2-5.2; Django-3.2-only branches must stay isolated so the migration is a single
+clean-up pass.
+
+Accent-insensitive search
+-------------------------
+On PostgreSQL with the ``unaccent`` extension enabled (and
+``django.contrib.postgres`` in ``INSTALLED_APPS``), replace DRF's search filter
+with the package's::
+
+    REST_FRAMEWORK = {
+        "DEFAULT_FILTER_BACKENDS": [
+            "drf_react_by_schema.filters.DRFReactBySchemaSearchFilter",
+            "drf_react_by_schema.filters.DRFReactBySchemaOrderingFilter",
+        ],
+    }
+
+``unaccent`` is applied only to text fields; dates, numbers and booleans keep
+DRF's default lookup, because ``unaccent`` raises on them.
+
+The filter also orders the hits by relevance. It concatenates the short text
+(``CharField``) paths of ``search_fields``, in order, and scores the whole query
+against that label: exact match (100), prefix (80), substring (60). The first
+path is scored on its own as well, so ``nome`` keeps its exact/prefix bonus even
+when the label also contains phone/e-mail fields. Records that only match all
+the terms across fields keep score 0 and are ordered by ``pk`` as a stable
+tiebreaker. An explicit ``?ordering=`` always wins over relevance. ``TextField``
+paths (long free text such as notes) stay out of the label.
+
+The filter is **opt-in**: apps that keep DRF's ``SearchFilter`` are unaffected
+and do not need the extension. It probes the backend, ``INSTALLED_APPS`` and the
+database extension once per connection alias. If the extension is missing — or
+the database is not PostgreSQL, or ``django.contrib.postgres`` is not installed
+— it falls back to DRF's normal lookups: search keeps working (accent-sensitive)
+instead of raising ``FieldError``. Call
+``drf_react_by_schema.filters.reset_unaccent_cache()`` if the extension is
+installed while the process is running.
+
+To create the extension, add a migration in the consuming app::
+
+    from django.contrib.postgres.operations import UnaccentExtension
+
+    class Migration(migrations.Migration):
+        operations = [UnaccentExtension()]
+
 Optional Dependencies
 ---------------------
 For enhanced caching capabilities in the automatically generated viewsets, you can install optional dependencies:

drf_react_by_schema-0.28.3/drf_react_by_schema/filters.py

@@ -0,0 +1,212 @@
+from django.apps import apps
+from django.db import connections
+from django.db.models import Case, CharField, F, IntegerField, TextField, Value, When
+from django.db.models.functions import Concat, Greatest, Trim
+from rest_framework.filters import OrderingFilter, SearchFilter
+from rest_framework.settings import api_settings
+
+from . import utils
+
+# Only these field types support the unaccent lookup.
+TEXT_FIELD_CLASSES = (CharField, TextField)
+
+# DRF lookups the filter converts to their unaccent-aware counterparts.
+UNACCENT_LOOKUPS = ("icontains", "istartswith", "iexact")
+
+# Per-database result of the unaccent probe (one query per alias per process).
+_UNACCENT_AVAILABLE = {}
+
+
+def reset_unaccent_cache():
+    """Forget the unaccent probe, e.g. after installing the extension."""
+    _UNACCENT_AVAILABLE.clear()
+
+
+def unaccent_available(connection):
+    """Whether ``connection`` can run the ``unaccent`` lookup.
+
+    False on non-PostgreSQL backends, without ``django.contrib.postgres`` (which
+    registers the lookup), or when the extension is missing from the database.
+    """
+    if connection.vendor != "postgresql":
+        return False
+    if not apps.is_installed("django.contrib.postgres"):
+        return False
+    alias = connection.alias
+    if alias not in _UNACCENT_AVAILABLE:
+        try:
+            with connection.cursor() as cursor:
+                cursor.execute(
+                    "SELECT 1 FROM pg_extension WHERE extname = 'unaccent'"
+                )
+                _UNACCENT_AVAILABLE[alias] = cursor.fetchone() is not None
+        except Exception:
+            _UNACCENT_AVAILABLE[alias] = False
+    return _UNACCENT_AVAILABLE[alias]
+
+
+class DRFReactBySchemaSearchFilter(SearchFilter):
+    """``SearchFilter`` with accent-insensitive matching and relevance order.
+
+    Non-text fields keep DRF's default lookup: ``unaccent`` only accepts text,
+    so applying it to a date, number or boolean raises ``FieldError``.
+
+    Accent-insensitive search needs PostgreSQL with the ``unaccent`` extension
+    enabled and ``django.contrib.postgres`` in ``INSTALLED_APPS``. When either
+    is missing (or the database is not PostgreSQL), the filter silently falls
+    back to DRF's lookups, so search still works (accent-sensitive).
+
+    Hits are ranked by how the whole query matches the concatenation of the
+    short text ``search_fields`` (the label): exact, then prefix, then
+    substring. Every match that does not reach those tiers keeps score 0.
+    The client's ``?ordering=`` always wins over relevance.
+    """
+
+    # Resolved per request by ``filter_queryset``; None on direct calls.
+    _unaccent_enabled = None
+
+    def filter_queryset(self, request, queryset, view):
+        self._unaccent_enabled = unaccent_available(connections[queryset.db])
+        queryset = super().filter_queryset(request, queryset, view)
+        return self._order_by_relevance(request, queryset, view)
+
+    def construct_search(self, field_name, queryset):
+        lookup = super().construct_search(field_name, queryset)
+        unaccent_enabled = self._unaccent_enabled
+        if unaccent_enabled is None:
+            unaccent_enabled = unaccent_available(connections[queryset.db])
+        if not unaccent_enabled:
+            return lookup
+        if not self._is_text_field(queryset.model, field_name):
+            return lookup
+        for standard_lookup in UNACCENT_LOOKUPS:
+            if lookup.endswith(f"__{standard_lookup}"):
+                return lookup[: -len(standard_lookup)] + f"unaccent__{standard_lookup}"
+        return lookup
+
+    @staticmethod
+    def _resolve_field(model, field_path):
+        """Resolve the terminal model field of a ``search_fields`` path."""
+        # Strip DRF prefix modifiers: ^, =, @, $
+        parts = str(field_path).lstrip("^=@$").split("__")
+        try:
+            for part in parts[:-1]:
+                model = model._meta.get_field(part).related_model
+            return model._meta.get_field(parts[-1])
+        except Exception:
+            # Unknown paths and non-relational lookups keep the standard lookup.
+            return None
+
+    @classmethod
+    def _is_text_field(cls, model, field_path):
+        """Whether the terminal field in ``field_path`` is a text field."""
+        return isinstance(cls._resolve_field(model, field_path), TEXT_FIELD_CLASSES)
+
+    @classmethod
+    def _is_char_field(cls, model, field_path):
+        return isinstance(cls._resolve_field(model, field_path), CharField)
+
+    @classmethod
+    def _label_paths(cls, model, search_fields):
+        """``CharField`` paths whose concatenation is the searchable label.
+
+        ``TextField`` stays out: the label is for short identifiers (name, code,
+        e-mail), not long free text such as ``dados``/``observacoes``.
+        """
+        paths = []
+        seen = set()
+        for search_field in search_fields:
+            path = str(search_field).lstrip("^=@$")
+            if path in seen or not cls._is_char_field(model, path):
+                continue
+            seen.add(path)
+            paths.append(path)
+        return paths
+
+    @staticmethod
+    def _label_expression(paths):
+        """Concatenate the label paths in ``search_fields`` order."""
+        if not paths:
+            return None
+        if len(paths) == 1:
+            return Trim(F(paths[0]))
+        parts = []
+        for index, path in enumerate(paths):
+            if index:
+                parts.append(Value(" "))
+            parts.append(F(path))
+        return Trim(Concat(*parts, output_field=CharField()))
+
+    def _order_by_relevance(self, request, queryset, view):
+        """Order hits by label match, unless the client sent ``?ordering=``."""
+        if request.query_params.get(api_settings.ORDERING_PARAM):
+            return queryset
+        search_terms = self.get_search_terms(request)
+        if not search_terms:
+            return queryset
+        paths = self._label_paths(
+            queryset.model, self.get_search_fields(view, request)
+        )
+        label = self._label_expression(paths)
+        if label is None:
+            return queryset
+
+        query = " ".join(search_terms)
+        # The probe already checks the extension; re-check the app so a
+        # mocked/partial setup (lookup not registered) falls back to the
+        # standard lookups.
+        unaccent = self._unaccent_enabled and apps.is_installed(
+            "django.contrib.postgres"
+        )
+        label_lookup = "_drbs_search_label"
+        if unaccent:
+            # Bilateral transform: unaccents both the label and the query.
+            label_lookup += "__unaccent"
+        label_rank = Case(
+            When(**{f"{label_lookup}__iexact": query}, then=Value(100)),
+            When(**{f"{label_lookup}__istartswith": query}, then=Value(80)),
+            When(**{f"{label_lookup}__icontains": query}, then=Value(60)),
+            default=Value(0),
+            output_field=IntegerField(),
+        )
+
+        # A single field may hold the whole query (e.g. ``nome``) even when the
+        # concatenated label is polluted by other text fields (phone, e-mail).
+        # Only the first label path is scored: it is the primary identifier,
+        # so a note or e-mail starting with the query cannot outrank a name.
+        primary_lookup = paths[0] + ("__unaccent" if unaccent else "")
+        primary_rank = Case(
+            When(**{f"{primary_lookup}__iexact": query}, then=Value(100)),
+            When(**{f"{primary_lookup}__istartswith": query}, then=Value(80)),
+            default=Value(0),
+            output_field=IntegerField(),
+        )
+
+        rank = Greatest(label_rank, primary_rank)
+        return (
+            queryset.annotate(_drbs_search_label=label)
+            .annotate(_drbs_search_rank=rank)
+            .order_by(F("_drbs_search_rank").desc(), queryset.model._meta.pk.name)
+        )
+
+
+class DRFReactBySchemaOrderingFilter(OrderingFilter):
+    def get_ordering(self, request, queryset, view):
+        """
+        Ordering is set by a comma delimited ?ordering=... query parameter.
+
+        The `ordering` query parameter can be overridden by setting
+        the `ordering_param` value on the OrderingFilter or by
+        specifying an `ORDERING_PARAM` value in the API settings.
+        """
+        params = request.query_params.get(self.ordering_param)
+        if params:
+            fields_raw = [param.strip() for param in params.split(",")]
+            fields = utils.serializer_to_model_fields(view, fields_raw)
+            if fields is not None:
+                ordering = self.remove_invalid_fields(queryset, fields, view, request)
+                if ordering:
+                    return ordering
+
+        # No ordering was included, or all the ordering fields were invalid
+        return self.get_default_ordering(view)

{drf_react_by_schema-0.28.1 → drf_react_by_schema-0.28.3}/drf_react_by_schema/schema_bundle.py

@@ -53,6 +53,7 @@ from .utils import (
     DATE_FILTER_OPERATORS,
     GRID_FILTER_OPERATORS,
     camel_to_snake,
+    is_searchable_model_field,
     sum_rows_capabilities,
 )
 
@@ -543,7 +544,11 @@ def _search_ordering_fields(view_instance) -> tuple[list, list]:
     except Exception:
         return [], []
     return (
-        [str(field) for field in (view_instance.search_fields or [])],
+        [
+            str(field)
+            for field in (view_instance.search_fields or [])
+            if is_searchable_model_field(view_instance, str(field))
+        ],
         [str(field) for field in (view_instance.ordering_fields or [])],
     )
 

{drf_react_by_schema-0.28.1 → drf_react_by_schema-0.28.3}/drf_react_by_schema/utils.py

@@ -332,6 +332,17 @@ def _resolve_model_field(view, path):
     return field
 
 
+def is_searchable_model_field(view, path):
+    """Whether ``path`` accepts DRF's default ``icontains`` search lookup.
+
+    A path ending on a relation (FK, reverse or m2m) has no ``icontains``
+    lookup: putting it in ``search_fields`` makes every ``?search=`` request
+    raise ``FieldError``. Unknown paths (e.g. annotations) are left untouched.
+    """
+    field = _resolve_model_field(view, path)
+    return field is None or not field.is_relation
+
+
 def _is_non_string_field(view, target_field, column_field_serializer):
     """Whether the grid filter must treat the target as non-string.
 

{drf_react_by_schema-0.28.1 → drf_react_by_schema-0.28.3}/drf_react_by_schema/viewsets.py

@@ -550,8 +550,14 @@ class DRFReactBySchemaBaseModelViewSet(
                 self, list(serializer_fields.keys())
             )
 
-            if not self.search_fields:
-                self.search_fields = target_fields
+            if not self.search_fields and target_fields:
+                # Relation-terminated paths have no ``icontains`` lookup; DRF
+                # would raise on every ``?search=``. Ordering them is valid.
+                self.search_fields = [
+                    target_field
+                    for target_field in target_fields
+                    if utils.is_searchable_model_field(self, target_field)
+                ]
             if not self.ordering_fields:
                 self.ordering_fields = target_fields
 

{drf_react_by_schema-0.28.1 → drf_react_by_schema-0.28.3}/drf_react_by_schema.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: drf-react-by-schema
-Version: 0.28.1
+Version: 0.28.3
 Summary: A Django app to easily integrate with React from models.
 Home-page: https://gitlab.com/eita/drf-react-by-schema/drf-react-by-schema-django
 Author: Cooperativa EITA
@@ -115,6 +115,52 @@ single release line. The supported combinations are exercised in CI (see
        drf-react-by-schema
        drf-excel<2.6
 
+Django 3.2 is kept as **legacy support**: the 3.2-only pin above and its CI job
+will be dropped when the supported floor moves to 4.2. New code should target
+4.2-5.2; Django-3.2-only branches must stay isolated so the migration is a single
+clean-up pass.
+
+Accent-insensitive search
+-------------------------
+On PostgreSQL with the ``unaccent`` extension enabled (and
+``django.contrib.postgres`` in ``INSTALLED_APPS``), replace DRF's search filter
+with the package's::
+
+    REST_FRAMEWORK = {
+        "DEFAULT_FILTER_BACKENDS": [
+            "drf_react_by_schema.filters.DRFReactBySchemaSearchFilter",
+            "drf_react_by_schema.filters.DRFReactBySchemaOrderingFilter",
+        ],
+    }
+
+``unaccent`` is applied only to text fields; dates, numbers and booleans keep
+DRF's default lookup, because ``unaccent`` raises on them.
+
+The filter also orders the hits by relevance. It concatenates the short text
+(``CharField``) paths of ``search_fields``, in order, and scores the whole query
+against that label: exact match (100), prefix (80), substring (60). The first
+path is scored on its own as well, so ``nome`` keeps its exact/prefix bonus even
+when the label also contains phone/e-mail fields. Records that only match all
+the terms across fields keep score 0 and are ordered by ``pk`` as a stable
+tiebreaker. An explicit ``?ordering=`` always wins over relevance. ``TextField``
+paths (long free text such as notes) stay out of the label.
+
+The filter is **opt-in**: apps that keep DRF's ``SearchFilter`` are unaffected
+and do not need the extension. It probes the backend, ``INSTALLED_APPS`` and the
+database extension once per connection alias. If the extension is missing — or
+the database is not PostgreSQL, or ``django.contrib.postgres`` is not installed
+— it falls back to DRF's normal lookups: search keeps working (accent-sensitive)
+instead of raising ``FieldError``. Call
+``drf_react_by_schema.filters.reset_unaccent_cache()`` if the extension is
+installed while the process is running.
+
+To create the extension, add a migration in the consuming app::
+
+    from django.contrib.postgres.operations import UnaccentExtension
+
+    class Migration(migrations.Migration):
+        operations = [UnaccentExtension()]
+
 Optional Dependencies
 ---------------------
 For enhanced caching capabilities in the automatically generated viewsets, you can install optional dependencies:

{drf_react_by_schema-0.28.1 → drf_react_by_schema-0.28.3}/setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = drf_react_by_schema
-version = 0.28.1
+version = 0.28.3
 description = A Django app to easily integrate with React from models.
 long_description = file: README.rst
 url = https://gitlab.com/eita/drf-react-by-schema/drf-react-by-schema-django

drf_react_by_schema-0.28.1/drf_react_by_schema/filters.py

@@ -1,24 +0,0 @@
-from rest_framework.filters import OrderingFilter, SearchFilter
-from . import utils
-
-
-class DRFReactBySchemaOrderingFilter(OrderingFilter):
-    def get_ordering(self, request, queryset, view):
-        """
-        Ordering is set by a comma delimited ?ordering=... query parameter.
-
-        The `ordering` query parameter can be overridden by setting
-        the `ordering_param` value on the OrderingFilter or by
-        specifying an `ORDERING_PARAM` value in the API settings.
-        """
-        params = request.query_params.get(self.ordering_param)
-        if params:
-            fields_raw = [param.strip() for param in params.split(",")]
-            fields = utils.serializer_to_model_fields(view, fields_raw)
-            if fields is not None:
-                ordering = self.remove_invalid_fields(queryset, fields, view, request)
-                if ordering:
-                    return ordering
-
-        # No ordering was included, or all the ordering fields were invalid
-        return self.get_default_ordering(view)