# Wagtailmeili
[](https://pypi.python.org/pypi/wagtailmeili/)
[](https://codecov.io/gh/softquantum/wagtailmeili)
[](https://github.com/astral-sh/ruff)
[](https://opensource.org/licenses/BSD-3-Clause)
A search backend for Wagtail using [MeiliSearch](https://github.com/meilisearch/MeiliSearch).
> [!CAUTION]
> This package is still in development and until version 1.0.0, I will not maintain a DeprecationWarning pattern.
> I built the integration with meilisearch about 2 years ago for a project and decided to make it a public package to improve it and integrate more features.
> [!TIP]
> If you need support or require help with a Wagtail project, you can hire me 😊
## Requirements
Wagtailmeili requires the following:
- Python >= 3.11
- Wagtail >= 5.2
## Installation
### In your Wagtail project
#### Configure your MeiliSearch instance in your `settings.py` file.
Install Meilisearch python client e.g., using pip
```shell
pip install meilisearch
```
Add `wagtailmeili` to your `INSTALLED_APPS`
```python
INSTALLED_APPS = [
# ...
"wagtailmeili",
# ...
]
```
add the search backend to your `WAGTAILSEARCH_BACKENDS`
```python
import os
WAGTAILSEARCH_BACKENDS = {
"default": {
"BACKEND": "wagtailmeili.backend",
"HOST": os.environ.get("MEILISEARCH_HOST", "http://127.0.0.1"),
"PORT": os.environ.get("MEILISEARCH_PORT", "7700"),
"MASTER_KEY": os.environ.get("MEILISEARCH_MASTER_KEY", "your-master-key"),
# "STOP_WORDS": ...
# "RANKING_RULES: ...
# "SKIP_MODELS": ...
# "SKIP_MODELS_BY_FIELD_VALUE": ...
},
}
```
## Features
### Default search configs
* STOP_WORDS: see defaults in [settings.py](src/wagtailmeili/settings.py)
* RANKING_RULES: see defaults in [settings.py](src/wagtailmeili/settings.py)
* SKIP_MODELS: "skip_models" is a list of models that you want to skip from indexing no matter the model setup.
```python
WAGTAILSEARCH_BACKENDS = {
"default": {
"SKIP_MODELS": ["app_label.Model1", "app_label.Model2",],
# ...
}
}
```
* SKIP_MODELS_BY_FIELD_VALUE: A convenient way to skip instances based on attributes
```python
WAGTAILSEARCH_BACKENDS = {
"default": {
# add this to not index pages that are not published for example
"SKIP_MODELS_BY_FIELD_VALUE": {
"wagtailmeili_testapp.MoviePage": {
"field": "live",
"value": False,
},
},
# ...
}
}
```
### Model fields
To declare **_sortable attributes_** or add **_ranking rules_** for the model, just add, for example:
```python
from wagtail.models import Page
class MySuperPage(Page):
"""A Super Page to do incredible things."""
sortable_attributes = [
"published_last_timestamp",
# ...
]
ranking_rules = [
"published_last_timestamp:desc",
# ...
]
```
### Template Tag filter
```html
{% load meilisearch %}
{% get_matches_position result %}
```
## Roadmap before 1.0.0 (unsorted)
- -[x] ~~Adding tests~~
- -[ ] Refactoring index.py to be with easier testing
- -[ ] Exploring Meilisearch and bringing more of its features for Wagtail
- -[ ] Getting a leaner implementation (looking at Autocomplete and rebuilder)
- -[ ] Giving more love to the Sample project with a frontend
- -[ ] official documentation
## Sample Project: WMDB
The Wagtail Movie Database (WMDB) is a sample project for testing purposes. To run the project, follow these steps:
1. start the local meilisearch instance
```shell
meilisearch --master-key=<your masterKey>
```
2. copy the directory wagtail_moviedb wherever you want
3. create a virtualenv and activate it (instructions on linux/macOS)
```shell
python -m venv .venv
source .venv/bin/activate
```
4. install the dependencies
```shell
pip install -r requirements.txt
```
5. add an .env file
```dotenv
MEILISEARCH_MASTER_KEY="your masterKey"
```
6. apply migrations
```shell
python manage.py migrate
```
7. Create a superuser (optional)
```shell
python manage.py createsuperuser
```
8. load movies & start local web server
```shell
python manage.py load_movies
python manage.py runserver
```
9. visit your meilisearch local instance: https://127.0.0.1:7700, give it your master-key. You should see some movies loaded.
10. update index (optional):
```shell
python manage.py update_index
```
## Contributions
Welcome to all contributions!
### Prerequisites
- Install Meilisearch locally following their [documentation](https://www.meilisearch.com/docs/learn/self_hosted/install_meilisearch_locally)
- Start Meilisearch instance in your favorite terminal
```shell
meilisearch --master-key correctmasterkey
```
### Install
To make changes to this project, first clone this repository:
```sh
git clone git@github.com:softquantum/wagtailmeili.git
cd wagtailmeili
```
With your preferred virtualenv activated, install testing dependencies:
#### Using pip
```sh
pip install "pip>=21.3"
pip install -e '.[dev]' -U
```
### How to run tests
You can run tests as shown below:
```shell
pytest
```
or with tox
```
tox
```
## License
This project is released under the [3-Clause BSD License](LICENSE).
Raw data
{
"_id": null,
"home_page": null,
"name": "wagtailmeili",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": "Maxime Decooman <maxime@softquantum.com>",
"keywords": "wagtail, django, search, meilisearch, backend",
"author": null,
"author_email": "Maxime Decooman <maxime@softquantum.com>",
"download_url": "https://files.pythonhosted.org/packages/50/fc/fb2636e5043ac98a919193c713c33ac8f25d6d3c1959af112bc6b87ecd21/wagtailmeili-0.3.1.tar.gz",
"platform": null,
"description": "# Wagtailmeili\n[](https://pypi.python.org/pypi/wagtailmeili/)\n[](https://codecov.io/gh/softquantum/wagtailmeili)\n[](https://github.com/astral-sh/ruff)\n[](https://opensource.org/licenses/BSD-3-Clause)\n\nA search backend for Wagtail using [MeiliSearch](https://github.com/meilisearch/MeiliSearch).\n\n> [!CAUTION]\n> This package is still in development and until version 1.0.0, I will not maintain a DeprecationWarning pattern.\n> I built the integration with meilisearch about 2 years ago for a project and decided to make it a public package to improve it and integrate more features.\n\n> [!TIP] \n> If you need support or require help with a Wagtail project, you can hire me \ud83d\ude0a\n\n## Requirements\nWagtailmeili requires the following:\n- Python >= 3.11\n- Wagtail >= 5.2\n\n## Installation\n\n### In your Wagtail project\n#### Configure your MeiliSearch instance in your `settings.py` file.\nInstall Meilisearch python client e.g., using pip\n```shell\n pip install meilisearch\n```\nAdd `wagtailmeili` to your `INSTALLED_APPS`\n```python\nINSTALLED_APPS = [\n # ...\n \"wagtailmeili\",\n # ...\n]\n```\nadd the search backend to your `WAGTAILSEARCH_BACKENDS`\n```python\nimport os\n\nWAGTAILSEARCH_BACKENDS = {\n \"default\": {\n \"BACKEND\": \"wagtailmeili.backend\",\n \"HOST\": os.environ.get(\"MEILISEARCH_HOST\", \"http://127.0.0.1\"),\n \"PORT\": os.environ.get(\"MEILISEARCH_PORT\", \"7700\"),\n \"MASTER_KEY\": os.environ.get(\"MEILISEARCH_MASTER_KEY\", \"your-master-key\"),\n # \"STOP_WORDS\": ...\n # \"RANKING_RULES: ...\n # \"SKIP_MODELS\": ...\n # \"SKIP_MODELS_BY_FIELD_VALUE\": ...\n },\n}\n```\n## Features\n### Default search configs\n* STOP_WORDS: see defaults in [settings.py](src/wagtailmeili/settings.py)\n* RANKING_RULES: see defaults in [settings.py](src/wagtailmeili/settings.py)\n* SKIP_MODELS: \"skip_models\" is a list of models that you want to skip from indexing no matter the model setup.\n```python\nWAGTAILSEARCH_BACKENDS = {\n \"default\": {\n \"SKIP_MODELS\": [\"app_label.Model1\", \"app_label.Model2\",],\n # ...\n }\n}\n```\n* SKIP_MODELS_BY_FIELD_VALUE: A convenient way to skip instances based on attributes\n```python\nWAGTAILSEARCH_BACKENDS = {\n \"default\": {\n # add this to not index pages that are not published for example\n \"SKIP_MODELS_BY_FIELD_VALUE\": {\n \"wagtailmeili_testapp.MoviePage\": {\n \"field\": \"live\",\n \"value\": False,\n },\n },\n # ...\n }\n}\n```\n\n### Model fields\n\nTo declare **_sortable attributes_** or add **_ranking rules_** for the model, just add, for example:\n```python\nfrom wagtail.models import Page\n\n\nclass MySuperPage(Page):\n \"\"\"A Super Page to do incredible things.\"\"\"\n \n sortable_attributes = [\n \"published_last_timestamp\", \n # ...\n ]\n ranking_rules = [\n \"published_last_timestamp:desc\",\n # ...\n ]\n```\n\n### Template Tag filter\n```html\n{% load meilisearch %}\n\n{% get_matches_position result %}\n```\n\n## Roadmap before 1.0.0 (unsorted)\n- -[x] ~~Adding tests~~\n- -[ ] Refactoring index.py to be with easier testing\n- -[ ] Exploring Meilisearch and bringing more of its features for Wagtail\n- -[ ] Getting a leaner implementation (looking at Autocomplete and rebuilder)\n- -[ ] Giving more love to the Sample project with a frontend\n- -[ ] official documentation\n\n## Sample Project: WMDB\nThe Wagtail Movie Database (WMDB) is a sample project for testing purposes. To run the project, follow these steps:\n1. start the local meilisearch instance\n```shell\nmeilisearch --master-key=<your masterKey>\n```\n2. copy the directory wagtail_moviedb wherever you want\n3. create a virtualenv and activate it (instructions on linux/macOS)\n```shell\npython -m venv .venv\nsource .venv/bin/activate\n```\n4. install the dependencies\n```shell\npip install -r requirements.txt\n```\n5. add an .env file\n```dotenv\nMEILISEARCH_MASTER_KEY=\"your masterKey\"\n```\n6. apply migrations\n```shell\npython manage.py migrate\n```\n7. Create a superuser (optional)\n```shell\npython manage.py createsuperuser\n```\n8. load movies & start local web server\n```shell\npython manage.py load_movies\npython manage.py runserver\n```\n9. visit your meilisearch local instance: https://127.0.0.1:7700, give it your master-key. You should see some movies loaded.\n10. update index (optional):\n```shell\npython manage.py update_index\n```\n\n## Contributions\nWelcome to all contributions!\n\n### Prerequisites\n- Install Meilisearch locally following their [documentation](https://www.meilisearch.com/docs/learn/self_hosted/install_meilisearch_locally)\n- Start Meilisearch instance in your favorite terminal\n\n```shell\nmeilisearch --master-key correctmasterkey\n```\n\n### Install\nTo make changes to this project, first clone this repository:\n\n```sh\ngit clone git@github.com:softquantum/wagtailmeili.git\ncd wagtailmeili\n```\n\nWith your preferred virtualenv activated, install testing dependencies:\n#### Using pip\n\n```sh\npip install \"pip>=21.3\"\npip install -e '.[dev]' -U\n```\n### How to run tests\n\nYou can run tests as shown below:\n```shell\npytest \n```\nor with tox\n```\ntox\n```\n\n## License\nThis project is released under the [3-Clause BSD License](LICENSE).\n",
"bugtrack_url": null,
"license": null,
"summary": "A Meilisearch backend for Wagtail CMS",
"version": "0.3.1",
"project_urls": {
"Home": "https://github.com/softquantum/wagtailmeili",
"Issues": "https://github.com/softquantum/wagtailmeili/issues"
},
"split_keywords": [
"wagtail",
" django",
" search",
" meilisearch",
" backend"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ae50ca1cdf89d4b94925407e95eb4e7c5d9e2170b95f15a4a906a5ece8faf986",
"md5": "2ee9f7779ab95815295f13187c728608",
"sha256": "d08f0075274d94914daf0448c020687721a8e0e9474b07b504593352d990cc72"
},
"downloads": -1,
"filename": "wagtailmeili-0.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2ee9f7779ab95815295f13187c728608",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 24070,
"upload_time": "2025-02-14T01:59:57",
"upload_time_iso_8601": "2025-02-14T01:59:57.331381Z",
"url": "https://files.pythonhosted.org/packages/ae/50/ca1cdf89d4b94925407e95eb4e7c5d9e2170b95f15a4a906a5ece8faf986/wagtailmeili-0.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "50fcfb2636e5043ac98a919193c713c33ac8f25d6d3c1959af112bc6b87ecd21",
"md5": "29e675c237e0d6f90bff55d7f5933290",
"sha256": "c369dee7f8626bfa3d966eefaea7b96521d36c61cde8ac234802280d93887383"
},
"downloads": -1,
"filename": "wagtailmeili-0.3.1.tar.gz",
"has_sig": false,
"md5_digest": "29e675c237e0d6f90bff55d7f5933290",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 6172423,
"upload_time": "2025-02-14T01:59:59",
"upload_time_iso_8601": "2025-02-14T01:59:59.116701Z",
"url": "https://files.pythonhosted.org/packages/50/fc/fb2636e5043ac98a919193c713c33ac8f25d6d3c1959af112bc6b87ecd21/wagtailmeili-0.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-14 01:59:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "softquantum",
"github_project": "wagtailmeili",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "wagtailmeili"
}
JSON
