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

{drf_react_by_schema-0.28.2 → 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.2
+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
@@ -136,6 +136,15 @@ with the package's::
 ``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

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

@@ -104,6 +104,15 @@ with the package's::
 ``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

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.2 → 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.2
+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
@@ -136,6 +136,15 @@ with the package's::
 ``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

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

@@ -1,6 +1,6 @@
 [metadata]
 name = drf_react_by_schema
-version = 0.28.2
+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.2/drf_react_by_schema/filters.py

@@ -1,112 +0,0 @@
-from django.apps import apps
-from django.db import connections
-from django.db.models import CharField, TextField
-from rest_framework.filters import OrderingFilter, SearchFilter
-
-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 matches on text fields.
-
-    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).
-    """
-
-    # 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])
-        return super().filter_queryset(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 _is_text_field(model, field_path):
-        """Whether the terminal field in ``field_path`` is a text field."""
-        # 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 isinstance(model._meta.get_field(parts[-1]), TEXT_FIELD_CLASSES)
-        except Exception:
-            # Unknown paths and non-relational lookups keep the standard lookup.
-            return False
-
-
-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)