django-tsearchable 0.2.0__py3-none-any.whl

django_tsearchable-0.2.0.dist-info/METADATA

@@ -0,0 +1,147 @@
+Metadata-Version: 2.5
+Name: django-tsearchable
+Version: 0.2.0
+Summary: Drop-in PostgreSQL full-text search for Django: auto-maintained search_vector, GIN/GiST index, boolean query syntax, admin/DRF/forms integration.
+Project-URL: Homepage, https://github.com/yourname/django-tsearchable
+Project-URL: Issues, https://github.com/yourname/django-tsearchable/issues
+Project-URL: Changelog, https://github.com/yourname/django-tsearchable/blob/main/CHANGELOG.md
+Author-email: Your Name <you@example.com>
+License: MIT
+License-File: LICENSE
+Keywords: django,drf,full-text-search,postgresql,search,tsvector
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Framework :: Django :: 5.1
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Database
+Requires-Python: >=3.9
+Requires-Dist: django>=4.2
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: django-filter; extra == 'dev'
+Requires-Dist: djangorestframework; extra == 'dev'
+Requires-Dist: psycopg[binary]; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-django; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Provides-Extra: drf
+Requires-Dist: djangorestframework>=3.14; extra == 'drf'
+Provides-Extra: filter
+Requires-Dist: django-filter>=23.5; extra == 'filter'
+Description-Content-Type: text/markdown
+
+# django-tsearchable
+
+**PostgreSQL full-text search for Django in one abstract model.** Subclass `SearchableModel`, list the fields,
+and get an auto-maintained `search_vector`, a GIN/GiST index, and a search syntax your users already understand:
+`python and (django or "rest framework") not php`.
+
+```python
+from django.db import models
+from tsearchable import SearchableModel
+
+class Candidate(SearchableModel):
+    first_name = models.CharField(max_length=255)
+    last_name = models.CharField(max_length=255)
+    email = models.EmailField()
+    skills = ArrayField(models.CharField(max_length=50), default=list)
+    tags = models.ManyToManyField("Tag")
+
+    search_fields = {"first_name": "A", "last_name": "A", "email": "B", "skills": "C", "tags__title": "C"}
+    search_index = "gin"                 # "gin" | "gist" | None
+
+Candidate.objects.search('python and not java', rank=True)
+```
+
+## Features
+
+| Area | What you get |
+|---|---|
+| **Model** | Abstract `SearchableModel` adds `search_vector`, builds the index (`gin`/`gist`) in your migrations, weights `A`–`D`, ORM-style paths (`company__name`, `tags__title`), list/array fields |
+| **Query syntax** | implicit AND, `and` / `or` / `not` / `!`, parentheses, `"exact phrase"`, prefix matching, accent- and Turkish-aware (`cagri` finds `Çağrı`). Hostile input can never raise a tsquery syntax error. Or switch to Postgres `websearch` syntax |
+| **Always up to date** | refreshed on `save()` and automatically on M2M changes; or choose `"trigger"` (DB trigger, covers `bulk_create`/`update()`), `"deferred"` (signal → your Celery/RQ task), or `False` |
+| **Search quality** | `rank=True` relevance ordering, `highlight=[...]` (`<mark>` snippets), `fuzzy=True` typo tolerance (pg_trgm), `.suggest()` autocomplete, per-field languages, `search_all()` across models |
+| **Integrations** | Django admin mixin, DRF filter backend, django-filter `SearchFilter`, `SearchForm` + `SearchableListViewMixin` |
+| **Tooling** | `manage.py rebuild_search_vectors`, `manage.py tsearch_trigger_sql`, system checks, `tsearchable.testing` assertions |
+
+## Install
+
+```bash
+pip install django-tsearchable            # + [drf] and/or [filter] extras
+```
+```python
+INSTALLED_APPS = ["django.contrib.postgres", "tsearchable", ...]
+```
+Requires PostgreSQL, Django ≥ 4.2. No `unaccent` extension needed. Then `makemigrations && migrate`
+and backfill existing rows once: `python manage.py rebuild_search_vectors`.
+
+## Usage
+
+### Configuration (class attributes)
+
+| Attribute | Default | Meaning |
+|---|---|---|
+| `search_fields` | `[]` | list of paths, or `{path: "A"}` / `{path: ("A", "turkish")}` (weight, language) |
+| `search_config` | `"simple"` | Postgres text search config |
+| `search_mode` | `"tsquery"` | `"tsquery"` (rich syntax) or `"websearch"` |
+| `search_index` | `"gin"` | `"gin"`, `"gist"` or `None`; `search_index_options` is passed to the index |
+| `search_auto_update` | `True` | `True`, `False`, `"trigger"`, `"deferred"` |
+| `search_fallback_fields` | `[]` | extra `icontains` OR-ed into `.search()` (`search_fallback_unaccent` for `unaccent`) |
+| `search_fuzzy_fields` | `[]` | fields for trigram typo tolerance |
+| `search_normalize` | `True` | lowercase + accent stripping for the `simple` config |
+
+### Searching
+```python
+Candidate.objects.search("pyhton", fuzzy=True)                    # typo tolerant (CREATE EXTENSION pg_trgm)
+Candidate.objects.search("backend", rank=True, highlight=["bio"]) # obj.bio_highlight -> "…<mark>backend</mark>…"
+Candidate.objects.suggest("pyt", field="first_name")              # autocomplete
+search_all([Candidate, JobPost], "python")                        # one relevance-sorted list
+```
+
+### Admin / DRF / forms
+```python
+class CandidateAdmin(SearchableAdminMixin, admin.ModelAdmin): ...          # tsearchable.admin
+
+class CandidateViewSet(ModelViewSet):                                      # tsearchable.drf  (?search=...)
+    filter_backends = [SearchableFilterBackend]
+
+class CandidateList(SearchableListViewMixin, ListView): model = Candidate  # tsearchable.views (?q=...)
+#   template context: search_form, search_query
+
+class CandidateFilter(FilterSet): q = SearchFilter()                       # tsearchable.filters
+```
+
+### Keeping vectors fresh
+* Default: updated on `save()` and on M2M add/remove/clear for paths like `tags__title`.
+* `"trigger"`: local columns only; run `manage.py tsearch_trigger_sql app.Model` and paste the printed
+  `SearchTrigger(...)` into a migration. Covers `bulk_create`, `update()` and raw SQL.
+* `"deferred"`: connect `tsearchable.signals.search_vector_refresh_requested` to enqueue
+  `instance.refresh_search_vector()` in your task queue.
+* After `bulk_*` with the default mode: `Model.objects.rebuild_search_vectors()`.
+
+### Query syntax
+`python django` (AND) · `python or java` · `python not java` · `!java` · `(a or b) and c` · `"senior backend"` (phrase) · `pyth*` / `pyth` (prefix)
+
+### System checks
+`manage.py check` validates `search_fields` paths, index type, update mode, trigger limitations, and that the DB is PostgreSQL.
+
+### Testing your own code
+```python
+from tsearchable.testing import assert_search_finds, assert_search_misses
+assert_search_finds(Candidate, "python not java", alice)
+```
+
+## Limitations
+* Highlighting uses the original text, so accent-insensitive matches (`cagri` → `Çağrı`) match but may not be highlighted.
+* Reverse-FK paths (e.g. `experiences__title`) are indexed on `save()` but not refreshed when the related row changes.
+* `"trigger"` mode only normalises Turkish letters (optionally `unaccent=True` for others) and supports local fields.
+
+## Development
+```bash
+pip install -e ".[dev]" && pytest     # needs a local PostgreSQL (PGUSER/PGPASSWORD/PGHOST env vars)
+```
+MIT licensed.

django_tsearchable-0.2.0.dist-info/RECORD

@@ -0,0 +1,22 @@
+tsearchable/__init__.py,sha256=ZHJsYEKvgTxRM9cxWVkGb0creCmvYStCIRxNoOrPOW8,636
+tsearchable/admin.py,sha256=wdemPdSWFUoJiwClMuLeh3xvTdGNAOeRLLXrIvQ7XZ4,527
+tsearchable/apps.py,sha256=VLDtw_sqTSgrZVNQI2GL3oKWjLgrCBhcIdHB3A4jdnI,304
+tsearchable/checks.py,sha256=tGgytQ49bxNAB07Ry7R-5HJWUiRF_yKknvf09zVGZTk,2805
+tsearchable/drf.py,sha256=R2GUT4BTR6LEcF4fF4uQLObx4Yp0AHzRos_aUpIRKsA,955
+tsearchable/filters.py,sha256=kOafeT_6P_uEyjTlCgQegTDli-PiEmXIGfFf7Qqf-uQ,369
+tsearchable/forms.py,sha256=2O14UhzYNqUzDuXq72E0rZA5DdWAD2CQAvE0Axy1kxY,707
+tsearchable/models.py,sha256=wvtxP_Z7PDjfdbT97cqMXa_QBoSOQ5EYmpK7JAIjq38,6452
+tsearchable/operations.py,sha256=ktnqPD3vkD_MRJtNLUil8CjUwmhiY7gDeUbruH1eZ9I,1524
+tsearchable/query.py,sha256=upk2C6wQ9fDLjCPiYBk1YCpRa7eEYq4JwJ7tkclRH_0,4320
+tsearchable/querysets.py,sha256=0X9CDZpYmnfUB_CoV87jc41v_NKoMVwwHIYo_NRb0nY,3936
+tsearchable/signals.py,sha256=Tb-IBwLiY8fqS4p07lOu77p-F1NTR2fPB-M-QDqPHzc,1700
+tsearchable/testing.py,sha256=xhbiM4xlNu8j2aROtRiS3gSM7cIsygSSOy42ByzTTIU,765
+tsearchable/views.py,sha256=dRNOXS7OOesQv8rh5Cd9sNRIu8FGAwq7AggZ71s4jZE,848
+tsearchable/management/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tsearchable/management/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tsearchable/management/commands/rebuild_search_vectors.py,sha256=yXeHRmivR8_pkqdQXG4QdTvGPOpKMOMzkhCn8-RkSKA,1301
+tsearchable/management/commands/tsearch_trigger_sql.py,sha256=J9iS_VZZGZZwjO5nVU31xQeXMRY3bGyEGgxvpinJTwA,902
+django_tsearchable-0.2.0.dist-info/METADATA,sha256=pLN-hmHXH2GQwWOhmMce0aMDp0l8AB8TzWkWWDKg2JM,7315
+django_tsearchable-0.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+django_tsearchable-0.2.0.dist-info/licenses/LICENSE,sha256=4iQbqGktDW0Z96miDtfz1OLDwapPbcTaKsJ7W6CCLq4,1066
+django_tsearchable-0.2.0.dist-info/RECORD,,

django_tsearchable-0.2.0.dist-info/WHEEL

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

django_tsearchable-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,16 @@
+MIT License
+
+Copyright (c) 2026 Your Name
+
+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.

tsearchable/__init__.py

@@ -0,0 +1,18 @@
+"""django-tsearchable. Django-dependent names load lazily, so `tsearchable.query` works without Django set up."""
+from .query import TSQueryConverter, normalize_text
+
+__version__ = "0.2.0"
+__all__ = [
+    "SearchableModel", "SearchableQuerySet", "SearchableManager", "search_all",
+    "TSQueryConverter", "normalize_text",
+]
+
+
+def __getattr__(name):
+    if name == "SearchableModel":
+        from .models import SearchableModel
+        return SearchableModel
+    if name in ("SearchableQuerySet", "SearchableManager", "search_all"):
+        from . import querysets
+        return getattr(querysets, name)
+    raise AttributeError(name)

tsearchable/admin.py

@@ -0,0 +1,12 @@
+class SearchableAdminMixin:
+    """Admin search box understands `python and not java`, "exact phrase", prefix matching.
+
+        class CandidateAdmin(SearchableAdminMixin, admin.ModelAdmin): ...
+    """
+
+    search_rank = False
+
+    def get_search_results(self, request, queryset, search_term):
+        if search_term and search_term.strip() and hasattr(queryset, "search"):
+            return queryset.search(search_term, rank=self.search_rank), False
+        return super().get_search_results(request, queryset, search_term)

tsearchable/apps.py

@@ -0,0 +1,12 @@
+from django.apps import AppConfig
+
+
+class TSearchableConfig(AppConfig):
+    name = "tsearchable"
+    verbose_name = "TSearchable"
+
+    def ready(self):
+        from . import checks  # noqa: F401  (registers system checks)
+        from .signals import connect_m2m_handlers
+
+        connect_m2m_handlers()

tsearchable/checks.py

@@ -0,0 +1,62 @@
+from django.apps import apps
+from django.core.checks import Error, Tags, Warning, register
+from django.core.exceptions import FieldDoesNotExist
+from django.db import connections
+
+from .models import AUTO_UPDATE_MODES, INDEX_TYPES, SearchableModel
+
+
+def _path_ok(model, path):
+    parts = path.split("__")
+    current = model
+    for i, part in enumerate(parts):
+        last = i == len(parts) - 1
+        try:
+            field = current._meta.get_field(part)
+        except FieldDoesNotExist:
+            return last and hasattr(current, part)  # property / method on the model
+        if not last:
+            if not field.is_relation or field.related_model is None:
+                return False
+            current = field.related_model
+    return True
+
+
+def check_model(model):
+    errors = []
+    label = model._meta.label
+    specs = model._search_field_specs()
+    if not specs:
+        errors.append(Warning(f"{label} has no `search_fields`; search_vector will always be empty.", obj=model, id="tsearchable.W001"))
+    for path in specs:
+        if not _path_ok(model, path):
+            errors.append(Error(f"`search_fields` entry {path!r} does not resolve on {label}.", obj=model, id="tsearchable.E001"))
+    if model.search_index and str(model.search_index).lower() not in INDEX_TYPES:
+        errors.append(Error(f"`search_index` must be one of {sorted(INDEX_TYPES)} or None, got {model.search_index!r}.", obj=model, id="tsearchable.E002"))
+    if model.search_auto_update not in AUTO_UPDATE_MODES:
+        errors.append(Error(f"`search_auto_update` must be one of {AUTO_UPDATE_MODES}, got {model.search_auto_update!r}.", obj=model, id="tsearchable.E003"))
+    if model.search_auto_update == "trigger" and any("__" in p for p in specs):
+        errors.append(Error("`search_auto_update = 'trigger'` only supports local fields (no `__` paths).", obj=model, id="tsearchable.E004"))
+    if model.search_mode not in ("tsquery", "websearch"):
+        errors.append(Error(f"`search_mode` must be 'tsquery' or 'websearch', got {model.search_mode!r}.", obj=model, id="tsearchable.E005"))
+    return errors
+
+
+@register(Tags.models)
+def check_searchable_models(app_configs, **kwargs):
+    errors = []
+    for model in apps.get_models():
+        if issubclass(model, SearchableModel):
+            errors += check_model(model)
+    return errors
+
+
+@register(Tags.database, deploy=False)
+def check_database_vendor(app_configs, databases=None, **kwargs):
+    if not any(issubclass(m, SearchableModel) for m in apps.get_models()):
+        return []
+    errors = []
+    for alias in databases or []:
+        if connections[alias].vendor != "postgresql":
+            errors.append(Error(f"Database {alias!r} is not PostgreSQL; django-tsearchable requires PostgreSQL.", id="tsearchable.E006"))
+    return errors

tsearchable/drf.py

@@ -0,0 +1,23 @@
+from rest_framework.filters import BaseFilterBackend
+
+
+class SearchableFilterBackend(BaseFilterBackend):
+    """DRF filter backend: `?search=python and not java`. Override the param with `search_param` on the view."""
+
+    search_param = "search"
+
+    def filter_queryset(self, request, queryset, view):
+        param = getattr(view, "search_param", None) or self.search_param
+        term = request.query_params.get(param, "").strip()
+        if not term or not hasattr(queryset, "search"):
+            return queryset
+        return queryset.search(term, rank=getattr(view, "search_rank", False))
+
+    def get_schema_operation_parameters(self, view):
+        return [{
+            "name": getattr(view, "search_param", None) or self.search_param,
+            "required": False,
+            "in": "query",
+            "description": "Full-text search (supports and / or / not, quotes, parentheses).",
+            "schema": {"type": "string"},
+        }]

tsearchable/filters.py

@@ -0,0 +1,12 @@
+import django_filters
+
+
+class SearchFilter(django_filters.CharFilter):
+    """django-filter integration:  q = SearchFilter()  inside a FilterSet."""
+
+    def __init__(self, *args, rank=False, **kwargs):
+        self.rank = rank
+        super().__init__(*args, **kwargs)
+
+    def filter(self, qs, value):
+        return qs.search(value, rank=self.rank) if value else qs

tsearchable/forms.py

@@ -0,0 +1,21 @@
+from django import forms
+
+
+class SearchForm(forms.Form):
+    """GET search form with a single (optionally renamed) query field."""
+
+    q = forms.CharField(required=False, strip=True, max_length=200, label="Search")
+
+    def __init__(self, *args, field_name="q", **kwargs):
+        super().__init__(*args, **kwargs)
+        self.field_name = field_name
+        if field_name != "q":
+            self.fields = {field_name: self.fields["q"]}
+
+    @property
+    def query(self):
+        return (self.cleaned_data.get(self.field_name) or "") if self.is_valid() else ""
+
+    def apply(self, queryset, **search_kwargs):
+        q = self.query
+        return queryset.search(q, **search_kwargs) if q else queryset

tsearchable/management/commands/rebuild_search_vectors.py

@@ -0,0 +1,28 @@
+from django.apps import apps
+from django.core.management.base import BaseCommand, CommandError
+
+from tsearchable.models import SearchableModel
+
+
+class Command(BaseCommand):
+    help = "Recompute search_vector for SearchableModel tables (all of them, or the given app_label.Model)."
+
+    def add_arguments(self, parser):
+        parser.add_argument("models", nargs="*", help="app_label.ModelName (default: every SearchableModel)")
+        parser.add_argument("--batch-size", type=int, default=500)
+
+    def handle(self, *args, models, batch_size, **options):
+        if models:
+            targets = []
+            for label in models:
+                try:
+                    targets.append(apps.get_model(label))
+                except (LookupError, ValueError):
+                    raise CommandError(f"Unknown model {label!r}; use app_label.ModelName")
+        else:
+            targets = [m for m in apps.get_models() if issubclass(m, SearchableModel)]
+        for model in targets:
+            if not issubclass(model, SearchableModel):
+                raise CommandError(f"{model._meta.label} is not a SearchableModel")
+            n = model._default_manager.all().rebuild_search_vectors(chunk_size=batch_size)
+            self.stdout.write(self.style.SUCCESS(f"{model._meta.label}: {n} rows"))

tsearchable/management/commands/tsearch_trigger_sql.py

@@ -0,0 +1,23 @@
+from django.apps import apps
+from django.core.management.base import BaseCommand, CommandError
+
+
+class Command(BaseCommand):
+    help = "Print a migration snippet that installs the DB trigger for a model using search_auto_update='trigger'."
+
+    def add_arguments(self, parser):
+        parser.add_argument("model", help="app_label.ModelName")
+
+    def handle(self, *args, model, **options):
+        try:
+            m = apps.get_model(model)
+        except (LookupError, ValueError):
+            raise CommandError(f"Unknown model {model!r}")
+        specs = m._search_field_specs()
+        fields = {p: w for p, (w, _c) in specs.items()}
+        self.stdout.write(
+            "from tsearchable.operations import SearchTrigger\n\n"
+            "operations = [\n"
+            f"    SearchTrigger(table={m._meta.db_table!r}, fields={fields!r}, config={m.search_config!r}),\n"
+            "]"
+        )

tsearchable/models.py

@@ -0,0 +1,156 @@
+import operator
+from functools import reduce
+
+from django.contrib.postgres.indexes import GinIndex, GistIndex
+from django.contrib.postgres.search import SearchVector, SearchVectorField
+from django.core.exceptions import FieldDoesNotExist, ObjectDoesNotExist
+from django.db import models, transaction
+from django.db.models import Value
+from django.db.models.base import ModelBase
+
+from .query import normalize_text
+from .querysets import SearchableManager
+from .signals import search_vector_refresh_requested
+
+INDEX_TYPES = {"gin": GinIndex, "gist": GistIndex}
+AUTO_UPDATE_MODES = (True, False, "trigger", "deferred")
+
+
+def _get_attr(obj, name):
+    try:
+        if hasattr(obj, name):
+            return getattr(obj, name)
+        meta = getattr(obj, "_meta", None)
+        if meta is not None:  # reverse relation addressed by its query name (ORM style)
+            field = meta.get_field(name)
+            if field.auto_created and not field.concrete:
+                return getattr(obj, field.get_accessor_name(), None)
+    except (FieldDoesNotExist, ObjectDoesNotExist, AttributeError):
+        pass
+    return None
+
+
+def _values(obj, parts):
+    """Collect text for an ORM-style path (`a__b__c`): FKs, reverse FK / M2M managers, lists, callables."""
+    if obj is None:
+        return []
+    if not parts:
+        if isinstance(obj, (list, tuple, set)):
+            return [str(x) for x in obj if x not in (None, "")]
+        return [str(obj)] if obj != "" else []
+    head, *rest = parts
+    value = _get_attr(obj, head)
+    if callable(value) and not hasattr(value, "all"):
+        value = value()
+    if hasattr(value, "all"):
+        out = []
+        for item in value.all():
+            out += _values(item, rest)
+        return out
+    return _values(value, rest)
+
+
+class SearchableModelBase(ModelBase):
+    def __new__(mcs, name, bases, attrs, **kwargs):
+        cls = super().__new__(mcs, name, bases, attrs, **kwargs)
+        if cls._meta.abstract or not cls.search_index:
+            return cls
+        index_cls = INDEX_TYPES.get(str(cls.search_index).lower())
+        if index_cls is None:  # reported by the system check tsearchable.E002
+            return cls
+        if any("search_vector" in idx.fields for idx in cls._meta.indexes):
+            return cls
+        index = index_cls(fields=["search_vector"], **cls.search_index_options)
+        index.set_name_with_model(cls)
+        cls._meta.indexes = [*cls._meta.indexes, index]
+        # ModelState.from_model only reads options listed in original_attrs -> needed for makemigrations
+        cls._meta.original_attrs["indexes"] = cls._meta.indexes
+        return cls
+
+
+class SearchableModel(models.Model, metaclass=SearchableModelBase):
+    """
+    class Candidate(SearchableModel):
+        search_fields = {"first_name": "A", "tags__title": "C", "title": ("A", "turkish")}
+        search_index = "gin"            # "gin" | "gist" | None
+    """
+
+    # list of ORM-style paths, or {path: weight} / {path: (weight, config)}; weight is "A".."D"
+    search_fields = []
+    search_config = "simple"
+    search_mode = "tsquery"            # "tsquery" (and/or/not/quotes/prefix) | "websearch" (Postgres websearch syntax)
+    search_index = "gin"               # "gin" | "gist" | None
+    search_index_options = {}
+    search_auto_update = True          # True | False | "trigger" | "deferred"
+    search_fallback_fields = []        # extra icontains OR-ed in by .search()
+    search_fallback_unaccent = False   # True needs the `unaccent` Postgres extension
+    search_fuzzy_fields = []           # trigram-similarity fallback for .search(fuzzy=True); needs `pg_trgm`
+    search_normalize = True            # lowercase + accent strip (Turkish aware) for fields using the "simple" config
+
+    search_vector = SearchVectorField(null=True, blank=True, editable=False)
+
+    objects = SearchableManager()
+
+    class Meta:
+        abstract = True
+
+    # ---- configuration helpers -----------------------------------------
+    @classmethod
+    def _search_field_specs(cls):
+        """{path: (weight, config)}"""
+        items = cls.search_fields.items() if isinstance(cls.search_fields, dict) else ((f, None) for f in cls.search_fields)
+        out = {}
+        for path, spec in items:
+            weight, config = None, cls.search_config
+            if isinstance(spec, (tuple, list)):
+                weight = spec[0] if spec else None
+                if len(spec) > 1 and spec[1]:
+                    config = spec[1]
+            elif spec:
+                weight = spec
+            out[path] = (weight, config)
+        return out
+
+    @classmethod
+    def search_configs(cls):
+        configs = [cls.search_config]
+        for _, config in cls._search_field_specs().values():
+            if config not in configs:
+                configs.append(config)
+        return configs
+
+    # ---- vector maintenance --------------------------------------------
+    def build_search_vector_expression(self):
+        parts = []
+        for path, (weight, config) in self._search_field_specs().items():
+            text = " ".join(_values(self, path.split("__")))
+            if self.search_normalize and config == "simple":
+                text = normalize_text(text)
+            if text.strip():
+                parts.append(SearchVector(Value(text), weight=weight, config=config))
+        if not parts:
+            return Value(None, output_field=SearchVectorField())
+        return reduce(operator.add, parts)
+
+    def refresh_search_vector(self):
+        if self.pk is None:
+            return
+        type(self)._base_manager.filter(pk=self.pk).update(search_vector=self.build_search_vector_expression())
+
+    def schedule_search_refresh(self):
+        mode = self.search_auto_update
+        if mode is True:
+            self.refresh_search_vector()
+        elif mode == "deferred":
+            cls = type(self)
+            transaction.on_commit(lambda: search_vector_refresh_requested.send(sender=cls, instance=self))
+
+    def save(self, *args, **kwargs):
+        with transaction.atomic():
+            super().save(*args, **kwargs)
+            mode = self.search_auto_update
+            if mode is True or mode == "deferred":
+                update_fields = kwargs.get("update_fields")
+                roots = {p.split("__")[0] for p in self._search_field_specs()}
+                if update_fields is None or roots & set(update_fields):
+                    self.schedule_search_refresh()

tsearchable/operations.py

@@ -0,0 +1,37 @@
+"""Migration helper for `search_auto_update = "trigger"` (DB-side vector maintenance, catches bulk operations)."""
+from django.db import migrations
+
+_FROM = "İIıÇçĞğÖöŞşÜü"
+_TO = "iiiccggoossuu"
+
+
+def _expr(column, unaccent):
+    e = f"lower(translate(coalesce(NEW.\"{column}\"::text, ''), '{_FROM}', '{_TO}'))"
+    return f"unaccent({e})" if unaccent else e
+
+
+def SearchTrigger(table, fields, config="simple", column="search_vector", unaccent=False):
+    """
+    fields: {"first_name": "A", "email": "B", "bio": None}   (local columns only)
+    unaccent=True additionally strips non-Turkish accents (needs `CREATE EXTENSION unaccent`,
+    e.g. migrations.RunSQL / django.contrib.postgres.operations.UnaccentExtension()).
+    """
+    base = f"tsearch_{table}"[:50]
+    fn, trg = f"{base}_fn", f"{base}_trg"
+    parts = []
+    for col, weight in fields.items():
+        vec = f"to_tsvector('{config}', {_expr(col, unaccent)})"
+        parts.append(f"setweight({vec}, '{weight}')" if weight else vec)
+    body = " || ".join(parts) if parts else "NULL"
+    sql = f"""
+CREATE OR REPLACE FUNCTION {fn}() RETURNS trigger AS $$
+BEGIN
+  NEW."{column}" := {body};
+  RETURN NEW;
+END $$ LANGUAGE plpgsql;
+DROP TRIGGER IF EXISTS {trg} ON "{table}";
+CREATE TRIGGER {trg} BEFORE INSERT OR UPDATE ON "{table}" FOR EACH ROW EXECUTE FUNCTION {fn}();
+UPDATE "{table}" SET "{column}" = NULL;
+"""
+    reverse = f'DROP TRIGGER IF EXISTS {trg} ON "{table}"; DROP FUNCTION IF EXISTS {fn}();'
+    return migrations.RunSQL(sql, reverse)

tsearchable/query.py

@@ -0,0 +1,117 @@
+"""User-facing search syntax -> PostgreSQL raw tsquery string. Pure Python, no Django needed."""
+from __future__ import annotations
+
+import re
+import unicodedata
+from typing import List
+
+
+def normalize_text(text: str) -> str:
+    """Lowercase + strip accents (Turkish aware). Used for BOTH indexing and querying,
+    so the two sides always agree and no `unaccent` DB extension is required."""
+    text = text.replace("ı", "i").replace("İ", "I")
+    text = unicodedata.normalize("NFKD", text)
+    text = "".join(c for c in text if not unicodedata.combining(c))
+    return text.lower()
+
+
+class TSQueryConverter:
+    OPERATORS = {"and": ("&", 2), "&": ("&", 2), "or": ("|", 1), "|": ("|", 1), "not": ("!", 3), "!": ("!", 3)}
+    _TOKEN = re.compile(r'"[^"]*"|\(|\)|&|\||!|[^\s()&|!"]+')
+    _WORD = re.compile(r"\w+", re.UNICODE)
+
+    def __init__(self, normalize: bool = True):
+        self.normalize = normalize
+
+    # ---- helpers -------------------------------------------------------
+    def _is_op(self, t: str) -> bool:
+        return t.lower() in self.OPERATORS
+
+    def _is_unary(self, t: str) -> bool:
+        return t.lower() in ("not", "!")
+
+    def _prec(self, t: str) -> int:
+        return self.OPERATORS[t.lower()][1]
+
+    def _words(self, text: str) -> List[str]:
+        if self.normalize:
+            text = normalize_text(text)
+        else:
+            text = text.lower()
+        # \w+ strips every tsquery metacharacter (: ' & | ! ( ) < >) -> no syntax errors / injection
+        return self._WORD.findall(text)
+
+    # ---- pipeline ------------------------------------------------------
+    def tokenize(self, query: str) -> List[str]:
+        return self._TOKEN.findall(query)
+
+    def add_implicit_and(self, tokens: List[str]) -> List[str]:
+        out: List[str] = []
+        for i, t in enumerate(tokens):
+            out.append(t)
+            if i + 1 == len(tokens):
+                break
+            n = tokens[i + 1]
+            ends_operand = t == ")" or (not self._is_op(t) and t != "(")
+            starts_operand = n == "(" or self._is_unary(n) or (not self._is_op(n) and n != ")")
+            if ends_operand and starts_operand:
+                out.append("and")
+        return out
+
+    def infix_to_postfix(self, tokens: List[str]) -> List[str]:
+        out: List[str] = []
+        stack: List[str] = []
+        for t in tokens:
+            if t == "(":
+                stack.append(t)
+            elif t == ")":
+                while stack and stack[-1] != "(":
+                    out.append(stack.pop())
+                if stack:
+                    stack.pop()
+            elif self._is_op(t):
+                if not self._is_unary(t):
+                    while stack and stack[-1] != "(" and self._prec(stack[-1]) >= self._prec(t):
+                        out.append(stack.pop())
+                stack.append(t)
+            else:
+                out.append(t)
+        while stack:
+            op = stack.pop()
+            if op != "(":
+                out.append(op)
+        return out
+
+    def format_term(self, token: str) -> str:
+        if token.startswith('"'):
+            words = self._words(token)
+            if not words:
+                return ""
+            return words[0] if len(words) == 1 else "(" + " <-> ".join(words) + ")"
+        words = self._words(token)
+        if not words:
+            return ""
+        terms = [f"{w}:*" for w in words]
+        return terms[0] if len(terms) == 1 else "(" + " & ".join(terms) + ")"
+
+    def evaluate_postfix(self, postfix: List[str]) -> str:
+        stack: List[str] = []
+        for t in postfix:
+            if self._is_unary(t):
+                if stack:
+                    stack.append(f"!{stack.pop()}")
+            elif self._is_op(t):
+                if len(stack) >= 2:
+                    right, left = stack.pop(), stack.pop()
+                    stack.append(f"({left} {self.OPERATORS[t.lower()][0]} {right})")
+            else:
+                f = self.format_term(t)
+                if f:
+                    stack.append(f)
+        return " & ".join(stack)
+
+    def convert(self, query: str) -> str:
+        if not query or not query.strip():
+            return ""
+        tokens = self.add_implicit_and(self.tokenize(query.strip()))
+        return self.evaluate_postfix(self.infix_to_postfix(tokens))

tsearchable/querysets.py

@@ -0,0 +1,95 @@
+from django.contrib.postgres.search import SearchHeadline, SearchQuery, SearchRank
+from django.db import models
+from django.db.models import F, Q
+
+from .query import TSQueryConverter, normalize_text
+
+
+def _build_queries(model, query, mode):
+    """One SearchQuery per distinct text-search config used by the model."""
+    queries = []
+    for config in model.search_configs():
+        normalize = model.search_normalize and config == "simple"
+        if mode == "websearch":
+            text = normalize_text(query) if normalize else query
+            queries.append(SearchQuery(text, search_type="websearch", config=config))
+        else:
+            tsquery = TSQueryConverter(normalize=normalize).convert(query)
+            if tsquery:
+                queries.append(SearchQuery(tsquery, search_type="raw", config=config))
+    return queries
+
+
+class SearchableQuerySet(models.QuerySet):
+    def search(self, query, *, rank=False, fallback=True, fuzzy=False, highlight=None, mode=None):
+        """
+        Full-text search.
+
+        rank       order by relevance (adds `search_rank`)
+        fallback   OR in icontains on `search_fallback_fields`
+        fuzzy      OR in trigram similarity on `search_fuzzy_fields` (typo tolerance, needs pg_trgm)
+        highlight  list of text fields -> adds `<field>_highlight` with <mark>..</mark> around matches
+        mode       override `search_mode` ("tsquery" | "websearch")
+        """
+        if not query or not query.strip():
+            return self
+        model = self.model
+        query = query.strip()
+        sqs = _build_queries(model, query, mode or model.search_mode)
+        cond = Q()
+        for sq in sqs:
+            cond |= Q(search_vector=sq)
+        distinct = False
+        if fallback:
+            suffix = "__unaccent__icontains" if model.search_fallback_unaccent else "__icontains"
+            for field in model.search_fallback_fields:
+                cond |= Q(**{field + suffix: query})
+                distinct = distinct or "__" in field
+        if fuzzy:
+            for field in model.search_fuzzy_fields:
+                cond |= Q(**{field + "__trigram_similar": query})
+                distinct = distinct or "__" in field
+        if not cond:
+            return self.none()
+        qs = self.filter(cond)
+        if distinct:
+            qs = qs.distinct()
+        if sqs:
+            if rank:
+                qs = qs.annotate(search_rank=SearchRank(F("search_vector"), sqs[0])).order_by("-search_rank")
+            for field in highlight or []:
+                qs = qs.annotate(
+                    **{f"{field}_highlight": SearchHeadline(F(field), sqs[0], start_sel="<mark>", stop_sel="</mark>")}
+                )
+        return qs
+
+    def suggest(self, prefix, field, limit=10):
+        """Autocomplete: distinct values of `field` starting with `prefix`."""
+        prefix = (prefix or "").strip()
+        if not prefix:
+            return []
+        qs = self.filter(**{f"{field}__istartswith": prefix}).order_by(field)
+        return list(qs.values_list(field, flat=True).distinct()[:limit])
+
+    def rebuild_search_vectors(self, chunk_size=500):
+        """Recompute search_vector for every row (backfill, or after bulk_create/bulk_update/update())."""
+        n = 0
+        for obj in self.iterator(chunk_size=chunk_size):
+            obj.refresh_search_vector()
+            n += 1
+        return n
+
+
+SearchableManager = models.Manager.from_queryset(SearchableQuerySet)
+
+
+def search_all(models_, query, limit=20, **kwargs):
+    """Search several SearchableModels at once; returns objects merged and sorted by relevance."""
+    hits = []
+    for model in models_:
+        for obj in model._default_manager.search(query, rank=True, **kwargs)[:limit]:
+            if not hasattr(obj, "search_rank"):
+                obj.search_rank = 0.0
+            hits.append(obj)
+    hits.sort(key=lambda o: o.search_rank, reverse=True)
+    return hits[:limit]

tsearchable/signals.py

@@ -0,0 +1,42 @@
+from django.apps import apps
+from django.db import transaction
+from django.db.models.signals import m2m_changed
+from django.dispatch import Signal
+
+#: Sent (on commit) when `search_auto_update = "deferred"`. Connect a receiver that enqueues
+#: a Celery/RQ/... task calling ``instance.refresh_search_vector()``.
+search_vector_refresh_requested = Signal()  # kwargs: sender=model class, instance=obj
+
+
+def _make_m2m_handler(model):
+    def handler(sender, instance, action, reverse, pk_set=None, **kwargs):
+        if action not in ("post_add", "post_remove", "post_clear"):
+            return
+        if not reverse:
+            instance.schedule_search_refresh()
+        elif pk_set:
+            for obj in model._base_manager.filter(pk__in=pk_set):
+                obj.schedule_search_refresh()
+
+    return handler
+
+
+def connect_m2m_handlers():
+    """Refresh vectors automatically when an M2M used in `search_fields` (e.g. `tags__title`) changes."""
+    from .models import SearchableModel
+
+    for model in apps.get_models():
+        if not issubclass(model, SearchableModel) or model.search_auto_update not in (True, "deferred"):
+            continue
+        for path in model._search_field_specs():
+            try:
+                field = model._meta.get_field(path.split("__")[0])
+            except Exception:
+                continue
+            if getattr(field, "many_to_many", False) and not field.auto_created:
+                m2m_changed.connect(
+                    _make_m2m_handler(model),
+                    sender=field.remote_field.through,
+                    weak=False,
+                    dispatch_uid=f"tsearchable.{model._meta.label_lower}.{field.name}",
+                )

tsearchable/testing.py

@@ -0,0 +1,17 @@
+"""Small assertions for your own test-suite:  assert_search_finds(Candidate, "python", alice)"""
+
+
+def _qs(target):
+    return target._default_manager.all() if hasattr(target, "_default_manager") else target
+
+
+def assert_search_finds(target, query, *objs, **search_kwargs):
+    found = set(_qs(target).search(query, **search_kwargs).values_list("pk", flat=True))
+    missing = [o for o in objs if o.pk not in found]
+    assert not missing, f"search({query!r}) did not find: {missing}"
+
+
+def assert_search_misses(target, query, *objs, **search_kwargs):
+    found = set(_qs(target).search(query, **search_kwargs).values_list("pk", flat=True))
+    present = [o for o in objs if o.pk in found]
+    assert not present, f"search({query!r}) unexpectedly found: {present}"

tsearchable/views.py

@@ -0,0 +1,24 @@
+from .forms import SearchForm
+
+
+class SearchableListViewMixin:
+    """Put before ListView:  class CandidateList(SearchableListViewMixin, ListView): model = Candidate"""
+
+    search_param = "q"
+    search_rank = False
+    search_form_class = SearchForm
+
+    def get_search_form(self):
+        return self.search_form_class(self.request.GET or None, field_name=self.search_param)
+
+    def get_queryset(self):
+        queryset = super().get_queryset()
+        self.search_form = self.get_search_form()
+        return self.search_form.apply(queryset, rank=self.search_rank)
+
+    def get_context_data(self, **kwargs):
+        context = super().get_context_data(**kwargs)
+        form = getattr(self, "search_form", None) or self.get_search_form()
+        context["search_form"] = form
+        context["search_query"] = form.query
+        return context