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).
