django-pitchfork 0.1.0__tar.gz

django_pitchfork-0.1.0/LICENSE

@@ -0,0 +1,30 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, the django-pitchfork authors.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.

django_pitchfork-0.1.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: django-pitchfork
+Version: 0.1.0
+Summary: Rust-powered search for Django: the haystack-compatible search layer on pitchfork-engine (native Tantivy, Whoosh, Solr, Elasticsearch, Xapian).
+License: BSD-3-Clause
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Framework :: Django :: 5.1
+Classifier: Framework :: Django :: 6.0
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: django>=4.2
+Requires-Dist: pitchfork-engine>=0.1.0
+Provides-Extra: whoosh
+Requires-Dist: whoosh<3,>=2.7; extra == "whoosh"
+Provides-Extra: solr
+Requires-Dist: pysolr<5,>=3.9; extra == "solr"
+Provides-Extra: elasticsearch
+Requires-Dist: elasticsearch<8,>=7.17; extra == "elasticsearch"
+Dynamic: license-file
+
+# django-pitchfork
+
+**Full-text search for Django, powered by Rust.** `django-pitchfork` is a
+drop-in replacement for [django-haystack](https://github.com/django-haystack/django-haystack):
+the same public API your templates, views and management commands already
+speak — `SearchQuerySet`, `SearchIndex`, fields, inputs, views, forms,
+templatetags, management commands — backed by a fast Rust/Tantivy engine
+instead of Python-only indexes.
+
+It is the Django-facing search layer on top of
+[pitchfork-engine](https://gitlab.com/co-plus-plus/pitchfork-engine) (the
+search engine itself: a standalone Tantivy-backed HTTP server, a PyO3
+in-process extension, and the haystack backend machinery).
+
+## Why
+
+- **Same API, faster core.** Your code keeps using the haystack API; queries
+  and indexing run against Rust's Tantivy (GIL released, native query AST).
+- **Escape hatch from unmaintained backends.** Upstream haystack's
+  Elasticsearch support tracks ES 7 only; here every backend is tested
+  against a live fixture in CI, and gaps are documented, not silent.
+- **One-way dependency.** `django_pitchfork` imports `pitchfork` (the
+  engine); the engine never imports the replacement.
+
+## Backends
+
+| Backend | Transport | Notes |
+|---|---|---|
+| **pitchfork** (native) | HTTP server or in-process PyO3 | The perf baseline; Rust/Tantivy |
+| Whoosh | file-based index | No service needed |
+| Solr | HTTP (pysolr) | Solr 6 fixture semantics; managed-schema generation |
+| Elasticsearch | HTTP (elasticsearch-py) | 7.x tested; 8.x is a documented gap |
+| Xapian | in-process bindings | Bindings not on PyPI — install from your distro |
+
+Each backend ships with a **capability contract** (`caps` module) and a
+generated support matrix ([`docs/backend_support.md`](docs/backend_support.md))
+so documented features are never hand-written claims. Every backend is
+covered by the shared conformance suite (`conformance/run.py`) against live
+fixtures.
+
+## Quick start
+
+```python
+# settings.py
+PITCHFORK_CONNECTIONS = {
+    "default": {
+        "ENGINE": "django_pitchfork.backends.pitchfork.PitchforkEngine",
+        "URL": "http://127.0.0.1:8117/",   # the pitchfork-server fixture
+    },
+}
+```
+
+```python
+# myapp/search_indexes.py
+from django_pitchfork import indexes
+
+class NoteIndex(indexes.SearchIndex, indexes.Indexable):
+    text = indexes.CharField(document=True)
+    title = indexes.CharField(model_attr="title")
+
+    def get_model(self):
+        return Note
+```
+
+```bash
+python manage.py rebuild_index
+python manage.py haystack_info
+```
+
+```python
+from django_pitchfork.query import SearchQuerySet
+
+results = SearchQuerySet().filter(content="haystack").order_by("-pub_date")
+```
+
+Install:
+
+```bash
+python -m pip install "django-pitchfork"                 # core (engine included)
+python -m pip install "django-pitchfork[whoosh]"         # Whoosh
+python -m pip install "django-pitchfork[solr]"           # pysolr
+python -m pip install "django-pitchfork[elasticsearch]"  # ES 7.x client
+```
+
+Xapian: no extra — the python-xapian bindings are not on PyPI. Install them
+from your distro (`libxapian-dev` + `python3-xapian`) and the backend picks
+them up (or use the xapian-capable image in `docker/xa/`).
+
+The engine repo has the full quick start for the server and embedded
+transports: <https://gitlab.com/co-plus-plus/pitchfork-engine/>
+
+## Migrating from django-haystack
+
+Mechanical import-sed (`haystack.` → `django_pitchfork.`) is the primary
+path — every public haystack module has a same-named counterpart, and the
+legacy `HAYSTACK_*` setting names keep working. See
+[`MIGRATION.md`](MIGRATION.md).
+
+For in-progress migrations an explicit-use compat shim mirrors haystack's
+import surface (parity-tested against a frozen list of haystack's public
+names, with live parity enforced when haystack is installed as a dev dep):
+
+```python
+import django_pitchfork.compat.haystack as haystack
+```
+
+The shim is never installed as `haystack` — that name collides with the
+real distribution.
+
+## Docs & benchmarks
+
+- Sphinx docs: `docs/` (`sphinx-build -W -b html docs/ docs/_build/`).
+- Conformance-suite baselines per backend: [`BENCHMARK.md`](BENCHMARK.md).
+
+## License
+
+BSD-3-Clause. The haystack API surface it replaces is also BSD-3-Clause
+(django-haystack).

django_pitchfork-0.1.0/README.md

@@ -0,0 +1,118 @@
+# django-pitchfork
+
+**Full-text search for Django, powered by Rust.** `django-pitchfork` is a
+drop-in replacement for [django-haystack](https://github.com/django-haystack/django-haystack):
+the same public API your templates, views and management commands already
+speak — `SearchQuerySet`, `SearchIndex`, fields, inputs, views, forms,
+templatetags, management commands — backed by a fast Rust/Tantivy engine
+instead of Python-only indexes.
+
+It is the Django-facing search layer on top of
+[pitchfork-engine](https://gitlab.com/co-plus-plus/pitchfork-engine) (the
+search engine itself: a standalone Tantivy-backed HTTP server, a PyO3
+in-process extension, and the haystack backend machinery).
+
+## Why
+
+- **Same API, faster core.** Your code keeps using the haystack API; queries
+  and indexing run against Rust's Tantivy (GIL released, native query AST).
+- **Escape hatch from unmaintained backends.** Upstream haystack's
+  Elasticsearch support tracks ES 7 only; here every backend is tested
+  against a live fixture in CI, and gaps are documented, not silent.
+- **One-way dependency.** `django_pitchfork` imports `pitchfork` (the
+  engine); the engine never imports the replacement.
+
+## Backends
+
+| Backend | Transport | Notes |
+|---|---|---|
+| **pitchfork** (native) | HTTP server or in-process PyO3 | The perf baseline; Rust/Tantivy |
+| Whoosh | file-based index | No service needed |
+| Solr | HTTP (pysolr) | Solr 6 fixture semantics; managed-schema generation |
+| Elasticsearch | HTTP (elasticsearch-py) | 7.x tested; 8.x is a documented gap |
+| Xapian | in-process bindings | Bindings not on PyPI — install from your distro |
+
+Each backend ships with a **capability contract** (`caps` module) and a
+generated support matrix ([`docs/backend_support.md`](docs/backend_support.md))
+so documented features are never hand-written claims. Every backend is
+covered by the shared conformance suite (`conformance/run.py`) against live
+fixtures.
+
+## Quick start
+
+```python
+# settings.py
+PITCHFORK_CONNECTIONS = {
+    "default": {
+        "ENGINE": "django_pitchfork.backends.pitchfork.PitchforkEngine",
+        "URL": "http://127.0.0.1:8117/",   # the pitchfork-server fixture
+    },
+}
+```
+
+```python
+# myapp/search_indexes.py
+from django_pitchfork import indexes
+
+class NoteIndex(indexes.SearchIndex, indexes.Indexable):
+    text = indexes.CharField(document=True)
+    title = indexes.CharField(model_attr="title")
+
+    def get_model(self):
+        return Note
+```
+
+```bash
+python manage.py rebuild_index
+python manage.py haystack_info
+```
+
+```python
+from django_pitchfork.query import SearchQuerySet
+
+results = SearchQuerySet().filter(content="haystack").order_by("-pub_date")
+```
+
+Install:
+
+```bash
+python -m pip install "django-pitchfork"                 # core (engine included)
+python -m pip install "django-pitchfork[whoosh]"         # Whoosh
+python -m pip install "django-pitchfork[solr]"           # pysolr
+python -m pip install "django-pitchfork[elasticsearch]"  # ES 7.x client
+```
+
+Xapian: no extra — the python-xapian bindings are not on PyPI. Install them
+from your distro (`libxapian-dev` + `python3-xapian`) and the backend picks
+them up (or use the xapian-capable image in `docker/xa/`).
+
+The engine repo has the full quick start for the server and embedded
+transports: <https://gitlab.com/co-plus-plus/pitchfork-engine/>
+
+## Migrating from django-haystack
+
+Mechanical import-sed (`haystack.` → `django_pitchfork.`) is the primary
+path — every public haystack module has a same-named counterpart, and the
+legacy `HAYSTACK_*` setting names keep working. See
+[`MIGRATION.md`](MIGRATION.md).
+
+For in-progress migrations an explicit-use compat shim mirrors haystack's
+import surface (parity-tested against a frozen list of haystack's public
+names, with live parity enforced when haystack is installed as a dev dep):
+
+```python
+import django_pitchfork.compat.haystack as haystack
+```
+
+The shim is never installed as `haystack` — that name collides with the
+real distribution.
+
+## Docs & benchmarks
+
+- Sphinx docs: `docs/` (`sphinx-build -W -b html docs/ docs/_build/`).
+- Conformance-suite baselines per backend: [`BENCHMARK.md`](BENCHMARK.md).
+
+## License
+
+BSD-3-Clause. The haystack API surface it replaces is also BSD-3-Clause
+(django-haystack).

django_pitchfork-0.1.0/django_pitchfork/__init__.py

@@ -0,0 +1,47 @@
+"""django_pitchfork — the public haystack replacement layer on pitchfork-engine.
+
+One-way import rule: this package imports
+``pitchfork`` (the engine); the engine never imports this package.
+
+The user-facing ``connections`` facade reads ``PITCHFORK_CONNECTIONS`` first
+and falls back to the legacy ``HAYSTACK_CONNECTIONS``, resolving lazily so
+``import django_pitchfork`` never touches Django settings at import time.
+"""
+
+from django.conf import settings
+from django.core.exceptions import ImproperlyConfigured
+
+from .routers import DefaultRouter  # noqa: F401 (public surface)
+from .utils.loading import ConnectionFacade, ConnectionRouter
+
+__version__ = "0.0.1"
+
+DEFAULT_ALIAS = "default"
+
+connections = ConnectionFacade()
+connection_router = ConnectionRouter()
+
+
+# Legacy-setting guards (haystack parity: fail loudly, don't silently ignore).
+if settings.configured:
+    if hasattr(settings, "HAYSTACK_SITECONF"):
+        raise ImproperlyConfigured(
+            "The HAYSTACK_SITECONF setting is no longer used & can be removed."
+        )
+    if hasattr(settings, "HAYSTACK_SEARCH_ENGINE"):
+        raise ImproperlyConfigured(
+            "The HAYSTACK_SEARCH_ENGINE setting has been replaced with "
+            "HAYSTACK_CONNECTIONS (or PITCHFORK_CONNECTIONS)."
+        )
+
+
+def reset_search_queries(**kwargs):
+    for conn in connections.all():
+        if conn:
+            conn.reset_queries()
+
+
+if settings.configured and settings.DEBUG:
+    from django.core import signals as django_signals
+
+    django_signals.request_started.connect(reset_search_queries)

django_pitchfork-0.1.0/django_pitchfork/admin.py

@@ -0,0 +1,167 @@
+from django import VERSION as django_version
+from django.contrib.admin.options import ModelAdmin, csrf_protect_m
+from django.contrib.admin.views.main import SEARCH_VAR, ChangeList
+from django.core.exceptions import PermissionDenied
+from django.core.paginator import InvalidPage, Paginator
+from django.shortcuts import render
+from django.utils.encoding import force_str
+from django.utils.translation import ngettext
+
+from django_pitchfork import connections
+from django_pitchfork.constants import DEFAULT_ALIAS
+from django_pitchfork.query import SearchQuerySet
+from django_pitchfork.utils import get_model_ct_tuple
+
+
+class SearchChangeList(ChangeList):
+    def __init__(self, **kwargs):
+        self.haystack_connection = kwargs.pop("haystack_connection", DEFAULT_ALIAS)
+        super_kwargs = kwargs
+        if django_version[0] >= 4:
+            super_kwargs["search_help_text"] = "Search..."
+        super().__init__(**super_kwargs)
+
+    def get_results(self, request):
+        if SEARCH_VAR not in request.GET:
+            return super().get_results(request)
+
+        # Note that pagination is 0-based, not 1-based.
+        sqs = (
+            SearchQuerySet(self.haystack_connection)
+            .models(self.model)
+            .auto_query(request.GET[SEARCH_VAR])
+            .load_all()
+        )
+
+        paginator = Paginator(sqs, self.list_per_page)
+        # Get the number of objects, with admin filters applied.
+        result_count = paginator.count
+        full_result_count = (
+            SearchQuerySet(self.haystack_connection).models(self.model).all().count()
+        )
+
+        can_show_all = result_count <= self.list_max_show_all
+        multi_page = result_count > self.list_per_page
+
+        # Get the list of objects to display on this page.
+        try:
+            result_list = paginator.page(self.page_num).object_list
+            # Grab just the Django models, since that's what everything else is
+            # expecting.
+            result_list = [result.object for result in result_list]
+        except InvalidPage:
+            result_list = ()
+
+        self.result_count = result_count
+        self.full_result_count = full_result_count
+        self.result_list = result_list
+        self.can_show_all = can_show_all
+        self.multi_page = multi_page
+        self.paginator = paginator
+
+
+class SearchModelAdminMixin:
+    # haystack connection to use for searching
+    haystack_connection = DEFAULT_ALIAS
+
+    @csrf_protect_m
+    def changelist_view(self, request, extra_context=None):
+        if not self.has_change_permission(request, None):
+            raise PermissionDenied
+
+        if SEARCH_VAR not in request.GET:
+            # Do the usual song and dance.
+            return super().changelist_view(request, extra_context)
+
+        # Do a search of just this model and populate a Changelist with the
+        # returned bits.
+        indexed_models = (
+            connections[self.haystack_connection]
+            .get_unified_index()
+            .get_indexed_models()
+        )
+
+        if self.model not in indexed_models:
+            # Oops. That model isn't being indexed. Return the usual
+            # behavior instead.
+            return super().changelist_view(request, extra_context)
+
+        # So. Much. Boilerplate.
+        # Why copy-paste a few lines when you can copy-paste TONS of lines?
+        list_display = list(self.list_display)
+
+        kwargs = {
+            "haystack_connection": self.haystack_connection,
+            "request": request,
+            "model": self.model,
+            "list_display": list_display,
+            "list_display_links": self.list_display_links,
+            "list_filter": self.list_filter,
+            "date_hierarchy": self.date_hierarchy,
+            "search_fields": self.search_fields,
+            "list_select_related": self.list_select_related,
+            "list_per_page": self.list_per_page,
+            "list_editable": self.list_editable,
+            "list_max_show_all": self.list_max_show_all,
+            "model_admin": self,
+        }
+        if hasattr(self, "get_sortable_by"):  # Django 2.1+
+            kwargs["sortable_by"] = self.get_sortable_by(request)
+        changelist = SearchChangeList(**kwargs)
+        changelist.formset = None
+        media = self.media
+
+        # Build the action form and populate it with available actions.
+        # Check actions to see if any are available on this changelist
+        actions = self.get_actions(request)
+        if actions:
+            action_form = self.action_form(auto_id=None)
+            action_form.fields["action"].choices = self.get_action_choices(request)
+        else:
+            action_form = None
+
+        selection_note = ngettext(
+            "0 of %(count)d selected",
+            "of %(count)d selected",
+            len(changelist.result_list),
+        )
+        selection_note_all = ngettext(
+            "%(total_count)s selected",
+            "All %(total_count)s selected",
+            changelist.result_count,
+        )
+
+        context = {
+            "module_name": force_str(self.model._meta.verbose_name_plural),
+            "selection_note": selection_note % {"count": len(changelist.result_list)},
+            "selection_note_all": selection_note_all
+            % {"total_count": changelist.result_count},
+            "title": changelist.title,
+            "is_popup": changelist.is_popup,
+            "cl": changelist,
+            "media": media,
+            "has_add_permission": self.has_add_permission(request),
+            "opts": changelist.opts,
+            "app_label": self.model._meta.app_label,
+            "action_form": action_form,
+            "actions_on_top": self.actions_on_top,
+            "actions_on_bottom": self.actions_on_bottom,
+            "actions_selection_counter": getattr(self, "actions_selection_counter", 0),
+        }
+        context.update(extra_context or {})
+        request.current_app = self.admin_site.name
+        app_name, model_name = get_model_ct_tuple(self.model)
+        return render(
+            request,
+            self.change_list_template
+            or [
+                "admin/%s/%s/change_list.html" % (app_name, model_name),
+                "admin/%s/change_list.html" % app_name,
+                "admin/change_list.html",
+            ],
+            context,
+        )
+
+
+class SearchModelAdmin(SearchModelAdminMixin, ModelAdmin):
+    pass

django_pitchfork-0.1.0/django_pitchfork/apps.py

@@ -0,0 +1,38 @@
+"""App config for django_pitchfork."""
+
+import logging
+
+from django.apps import AppConfig
+from django.conf import settings
+
+from . import connection_router, connections
+
+SIGNAL_PROCESSOR_PATH_DEFAULT = "pitchfork.signals.BaseSignalProcessor"
+
+
+class PitchforkConfig(AppConfig):
+    name = "django_pitchfork"
+    verbose_name = "django_pitchfork"
+    signal_processor = None
+    stream = None
+
+    def ready(self):
+        # Setup default logging (engine-owned facade).
+        log = logging.getLogger("pitchfork")
+        self.stream = logging.StreamHandler()
+        self.stream.setLevel(logging.INFO)
+        log.addHandler(self.stream)
+
+        # Setup the signal processor.
+        if not self.signal_processor:
+            signal_processor_path = getattr(
+                settings,
+                "PITCHFORK_SIGNAL_PROCESSOR",
+                getattr(settings, "HAYSTACK_SIGNAL_PROCESSOR", SIGNAL_PROCESSOR_PATH_DEFAULT),
+            )
+            from django_pitchfork.utils.loading import import_class
+
+            signal_processor_class = import_class(signal_processor_path)
+            self.signal_processor = signal_processor_class(
+                connections, connection_router
+            )

django_pitchfork-0.1.0/django_pitchfork/backends/__init__.py

@@ -0,0 +1,17 @@
+"""Backends for django_pitchfork. Public ``ENGINE`` paths live under
+``backends.{pitchfork,simple}.``; the base-class seam is ``backends.base``
+(re-exports of the engine's machinery).
+"""
+
+from .base import (  # noqa: F401
+    VALID_GAPS,
+    BaseEngine,
+    BaseSearchBackend,
+    BaseSearchQuery,
+    EmptyResults,
+    SPELLING_SUGGESTION_HAS_NOT_RUN,
+    SearchBackend,
+    SearchNode,
+    SQ,
+    log_query,
+)

django_pitchfork-0.1.0/django_pitchfork/backends/base.py

@@ -0,0 +1,15 @@
+"""Base-class seam — re-exports the engine's machinery under the replacement
+namespace (the public extension point for third-party backends)."""
+
+from pitchfork.backends.machinery import (  # noqa: F401
+    VALID_GAPS,
+    BaseEngine,
+    BaseSearchBackend,
+    BaseSearchQuery,
+    EmptyResults,
+    SPELLING_SUGGESTION_HAS_NOT_RUN,
+    SearchBackend,
+    SearchNode,
+    SQ,
+    log_query,
+)