============================
django-elasticsearch-dsl-drf
============================
Integrate `Elasticsearch DSL
<https://pypi.python.org/pypi/elasticsearch-dsl>`_ with
`Django REST framework <https://pypi.python.org/pypi/djangorestframework>`_ in
the shortest way possible, with least efforts possible.
Package provides views, serializers, filter backends, pagination and other
handy add-ons.
You are expected to use `django-elasticsearch-dsl
<https://pypi.python.org/pypi/django-elasticsearch-dsl>`_ for defining your
Elasticsearch documents.
.. image:: https://img.shields.io/pypi/v/django-elasticsearch-dsl-drf.svg
:target: https://pypi.python.org/pypi/django-elasticsearch-dsl-drf
:alt: PyPI Version
.. image:: https://img.shields.io/pypi/pyversions/django-elasticsearch-dsl-drf.svg
:target: https://pypi.python.org/pypi/django-elasticsearch-dsl-drf/
:alt: Supported Python versions
.. image:: https://github.com/barseghyanartur/django-elasticsearch-dsl-drf/workflows/test/badge.svg
:target: https://github.com/barseghyanartur/django-elasticsearch-dsl-drf/actions
:alt: Build Status
.. image:: https://readthedocs.org/projects/django-elasticsearch-dsl-drf/badge/?version=latest
:target: http://django-elasticsearch-dsl-drf.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status
.. image:: https://img.shields.io/badge/license-GPL--2.0--only%20OR%20LGPL--2.1--or--later-blue.svg
:target: https://github.com/barseghyanartur/django-elasticsearch-dsl-drf/#License
:alt: GPL-2.0-only OR LGPL-2.1-or-later
.. image:: https://coveralls.io/repos/github/barseghyanartur/django-elasticsearch-dsl-drf/badge.svg?branch=master
:target: https://coveralls.io/github/barseghyanartur/django-elasticsearch-dsl-drf?branch=master
:alt: Coverage
Documentation
=============
Documentation is available on `Read the Docs
<http://django-elasticsearch-dsl-drf.readthedocs.io/>`_.
Make sure to read `FAQ <https://github.com/barseghyanartur/django-elasticsearch-dsl-drf/blob/master/docs/faq.rst>`_.
Prerequisites
=============
- Django 2.2, 3.1 and 3.2.
- Python 3.6, 3.7, 3.8 and 3.9.
- Elasticsearch 6.x, 7.x. For older versions use
``django-elasticsearch-dsl-drf`` version 0.18.
Main features and highlights
============================
- `Dynamic serializer for Documents <http://django-elasticsearch-dsl-drf.readthedocs.io/en/0.22.5/basic_usage_examples.html#sample-serializer>`_.
- `Search filter backend <http://django-elasticsearch-dsl-drf.readthedocs.io/en/0.22.5/advanced_usage_examples.html#search>`_.
- `Ordering filter backend <http://django-elasticsearch-dsl-drf.readthedocs.io/en/0.22.5/advanced_usage_examples.html#ordering>`_.
- `Filtering filter backend <http://django-elasticsearch-dsl-drf.readthedocs.io/en/0.22.5/advanced_usage_examples.html#filtering>`_ (big variety of
native- and functional- query lookups, such as ``gt``, ``gte``, ``lt``,
``lte``, ``endswith``, ``contains``, ``wildcard``, ``exists``, ``exclude``,
``isnull``, ``range``, ``in``, ``prefix`` (same as ``startswith``), ``term``
and ``terms`` is implemented.
- `Geo-spatial filtering filter backend <http://django-elasticsearch-dsl-drf.readthedocs.io/en/0.22.5/advanced_usage_examples.html#geo-spatial-features>`_ (the
following filters implemented: ``geo_distance``, ``geo_polygon`` and
``geo_bounding_box``).
- `Geo-spatial ordering filter backend <http://django-elasticsearch-dsl-drf.readthedocs.io/en/0.22.5/advanced_usage_examples.html#geo-spatial-features>`_ (the
following filters implemented: ``geo_distance``).
- `Faceted search filter backend <http://django-elasticsearch-dsl-drf.readthedocs.io/en/0.22.5/advanced_usage_examples.html#faceted-search>`_.
- `Post-filter filter backend <http://django-elasticsearch-dsl-drf.readthedocs.io/en/0.22.5/advanced_usage_examples.html#post-filter>`_.
- `Nested filtering filter backend <http://django-elasticsearch-dsl-drf.readthedocs.io/en/0.22.5/nested_fields_usage_examples.html#nested-filtering>`_.
- `Highlight backend <http://django-elasticsearch-dsl-drf.readthedocs.io/en/0.22.5/advanced_usage_examples.html#highlighting>`_.
- `Suggester filter backend <http://django-elasticsearch-dsl-drf.readthedocs.io/en/0.22.5/advanced_usage_examples.html#suggestions>`_.
- `Functional suggester filter backend <http://django-elasticsearch-dsl-drf.readthedocs.io/en/0.22.5/advanced_usage_examples.html#functional-suggestions>`_.
- `Pagination (Page number and limit/offset pagination) <http://django-elasticsearch-dsl-drf.readthedocs.io/en/0.22.5/advanced_usage_examples.html#pagination>`_.
- `Ids filter backend <http://django-elasticsearch-dsl-drf.readthedocs.io/en/0.22.5/advanced_usage_examples.html#ids-filter>`_.
- `Multi match search filter backend <http://django-elasticsearch-dsl-drf.readthedocs.io/en/0.22.5/search_backends.html#multi-match-search-filter-backend>`_.
- `Simple search query filter backend <http://django-elasticsearch-dsl-drf.readthedocs.io/en/0.22.5/search_backends.html#simple-query-string-filter-backend>`_.
- `More-like-this support (detail action) <http://django-elasticsearch-dsl-drf.readthedocs.io/en/0.22.5/more_like_this.html>`_.
- `Global aggregations support <http://django-elasticsearch-dsl-drf.readthedocs.io/en/0.22.5/global_aggregations.html>`_.
- `Source filter backend <http://django-elasticsearch-dsl-drf.readthedocs.io/en/0.22.5/source_backend.html>`_.
Do you need a similar tool for GraphQL? Check `graphene-elastic
<https://github.com/barseghyanartur/graphene-elastic>`__.
Demos
=====
Online demo
-----------
Check the `live demo app <https://django-elasticsearch-dsl-drf.herokuapp.com>`__
(Django 3.1 + Django REST Framework 3.12 + Elasticsearch 7.5) hosted on Heroku
and bonsai.io.
Local demo
----------
A frontend demo (React based) is available. See the `dedicated docs
<https://github.com/barseghyanartur/django-elasticsearch-dsl-drf/blob/master/examples/frontend/README.rst>`_
for more information.
To bootstrap evaluation, clone the repository locally and run `docker-compose`.
.. code-block:: sh
docker-compose up
It will set up:
- Elasticsearch on `http://localhost:9200 <http://localhost:9200>`_
- Django REST framework on `http://localhost:8000 <http://localhost:8000>`_
- React on `http://localhost:3000 <http://localhost:3000>`_
Installation
============
(1) Install latest stable version from PyPI:
.. code-block:: sh
pip install django-elasticsearch-dsl-drf
or latest stable version from GitHub:
.. code-block:: sh
pip install https://github.com/barseghyanartur/django-elasticsearch-dsl-drf/archive/stable.tar.gz
(2) Add ``rest_framework``, ``django_elasticsearch_dsl`` and
``django_elasticsearch_dsl_drf`` to ``INSTALLED_APPS``:
.. code-block:: python
INSTALLED_APPS = (
# ...
# REST framework
'rest_framework',
# Django Elasticsearch integration
'django_elasticsearch_dsl',
# Django REST framework Elasticsearch integration (this package)
'django_elasticsearch_dsl_drf',
# ...
)
Quick start
===========
Perhaps the easiest way to get acquainted with ``django-elasticsearch-dsl-drf``
is to read the `quick start tutorial <http://django-elasticsearch-dsl-drf.readthedocs.io/en/0.22.5/quick_start.html>`_.
See it as a guide of diving into integration of Elasticsearch with Django
with very low knowledge entry level.
Testing
=======
Project is covered with tests.
To test with all supported Python/Django versions type:
.. code-block:: sh
tox
To test against specific environment, type:
.. code-block:: sh
tox -e py38-django30
To test just your working environment type:
.. code-block:: sh
./runtests.py
To run a single test in your working environment type:
.. code-block:: sh
./runtests.py src/django_elasticsearch_dsl_drf/tests/test_filtering.py
Or:
.. code-block:: sh
./manage.py test django_elasticsearch_dsl_drf.tests.test_ordering
To run a single test class in a given test module in your working environment
type:
.. code-block:: sh
./runtests.py src/django_elasticsearch_dsl_drf/tests/test_suggesters.py::TestSuggesters
It's assumed that you have all the requirements installed. If not, first
install the test requirements:
.. code-block:: sh
pip install -r examples/requirements/test.txt
Writing documentation
=====================
Keep the following hierarchy.
.. code-block:: text
=====
title
=====
header
======
sub-header
----------
sub-sub-header
~~~~~~~~~~~~~~
sub-sub-sub-header
^^^^^^^^^^^^^^^^^^
sub-sub-sub-sub-header
++++++++++++++++++++++
sub-sub-sub-sub-sub-header
**************************
License
=======
GPL-2.0-only OR LGPL-2.1-or-later
Support
=======
For any issues contact me at the e-mail given in the `Author`_ section.
Author
======
Artur Barseghyan <artur.barseghyan@gmail.com>
Raw data
{
"_id": null,
"home_page": "https://github.com/barseghyanartur/django-elasticsearch-dsl-drf/",
"name": "django-elasticsearch-dsl-drf",
"maintainer": "",
"docs_url": null,
"requires_python": ">=2.7",
"maintainer_email": "",
"keywords": "django,elasticsearch,elasticsearch-dsl,django rest framework",
"author": "Artur Barseghyan",
"author_email": "artur.barseghyan@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/0a/b1/5a6366036349d384ae7fa1a9cd589b921419213ae504f7924c3363a7b239/django-elasticsearch-dsl-drf-0.22.5.tar.gz",
"platform": null,
"description": "============================\ndjango-elasticsearch-dsl-drf\n============================\nIntegrate `Elasticsearch DSL\n<https://pypi.python.org/pypi/elasticsearch-dsl>`_ with\n`Django REST framework <https://pypi.python.org/pypi/djangorestframework>`_ in\nthe shortest way possible, with least efforts possible.\n\nPackage provides views, serializers, filter backends, pagination and other\nhandy add-ons.\n\nYou are expected to use `django-elasticsearch-dsl\n<https://pypi.python.org/pypi/django-elasticsearch-dsl>`_ for defining your\nElasticsearch documents.\n\n.. image:: https://img.shields.io/pypi/v/django-elasticsearch-dsl-drf.svg\n :target: https://pypi.python.org/pypi/django-elasticsearch-dsl-drf\n :alt: PyPI Version\n\n.. image:: https://img.shields.io/pypi/pyversions/django-elasticsearch-dsl-drf.svg\n :target: https://pypi.python.org/pypi/django-elasticsearch-dsl-drf/\n :alt: Supported Python versions\n\n.. image:: https://github.com/barseghyanartur/django-elasticsearch-dsl-drf/workflows/test/badge.svg\n :target: https://github.com/barseghyanartur/django-elasticsearch-dsl-drf/actions\n :alt: Build Status\n\n.. image:: https://readthedocs.org/projects/django-elasticsearch-dsl-drf/badge/?version=latest\n :target: http://django-elasticsearch-dsl-drf.readthedocs.io/en/latest/?badge=latest\n :alt: Documentation Status\n\n.. image:: https://img.shields.io/badge/license-GPL--2.0--only%20OR%20LGPL--2.1--or--later-blue.svg\n :target: https://github.com/barseghyanartur/django-elasticsearch-dsl-drf/#License\n :alt: GPL-2.0-only OR LGPL-2.1-or-later\n\n.. image:: https://coveralls.io/repos/github/barseghyanartur/django-elasticsearch-dsl-drf/badge.svg?branch=master\n :target: https://coveralls.io/github/barseghyanartur/django-elasticsearch-dsl-drf?branch=master\n :alt: Coverage\n\nDocumentation\n=============\nDocumentation is available on `Read the Docs\n<http://django-elasticsearch-dsl-drf.readthedocs.io/>`_.\n\nMake sure to read `FAQ <https://github.com/barseghyanartur/django-elasticsearch-dsl-drf/blob/master/docs/faq.rst>`_.\n\nPrerequisites\n=============\n- Django 2.2, 3.1 and 3.2.\n- Python 3.6, 3.7, 3.8 and 3.9.\n- Elasticsearch 6.x, 7.x. For older versions use\n ``django-elasticsearch-dsl-drf`` version 0.18.\n\nMain features and highlights\n============================\n\n- `Dynamic serializer for Documents <http://django-elasticsearch-dsl-drf.readthedocs.io/en/0.22.5/basic_usage_examples.html#sample-serializer>`_.\n- `Search filter backend <http://django-elasticsearch-dsl-drf.readthedocs.io/en/0.22.5/advanced_usage_examples.html#search>`_.\n- `Ordering filter backend <http://django-elasticsearch-dsl-drf.readthedocs.io/en/0.22.5/advanced_usage_examples.html#ordering>`_.\n- `Filtering filter backend <http://django-elasticsearch-dsl-drf.readthedocs.io/en/0.22.5/advanced_usage_examples.html#filtering>`_ (big variety of\n native- and functional- query lookups, such as ``gt``, ``gte``, ``lt``,\n ``lte``, ``endswith``, ``contains``, ``wildcard``, ``exists``, ``exclude``,\n ``isnull``, ``range``, ``in``, ``prefix`` (same as ``startswith``), ``term``\n and ``terms`` is implemented.\n- `Geo-spatial filtering filter backend <http://django-elasticsearch-dsl-drf.readthedocs.io/en/0.22.5/advanced_usage_examples.html#geo-spatial-features>`_ (the\n following filters implemented: ``geo_distance``, ``geo_polygon`` and\n ``geo_bounding_box``).\n- `Geo-spatial ordering filter backend <http://django-elasticsearch-dsl-drf.readthedocs.io/en/0.22.5/advanced_usage_examples.html#geo-spatial-features>`_ (the\n following filters implemented: ``geo_distance``).\n- `Faceted search filter backend <http://django-elasticsearch-dsl-drf.readthedocs.io/en/0.22.5/advanced_usage_examples.html#faceted-search>`_.\n- `Post-filter filter backend <http://django-elasticsearch-dsl-drf.readthedocs.io/en/0.22.5/advanced_usage_examples.html#post-filter>`_.\n- `Nested filtering filter backend <http://django-elasticsearch-dsl-drf.readthedocs.io/en/0.22.5/nested_fields_usage_examples.html#nested-filtering>`_.\n- `Highlight backend <http://django-elasticsearch-dsl-drf.readthedocs.io/en/0.22.5/advanced_usage_examples.html#highlighting>`_.\n- `Suggester filter backend <http://django-elasticsearch-dsl-drf.readthedocs.io/en/0.22.5/advanced_usage_examples.html#suggestions>`_.\n- `Functional suggester filter backend <http://django-elasticsearch-dsl-drf.readthedocs.io/en/0.22.5/advanced_usage_examples.html#functional-suggestions>`_.\n- `Pagination (Page number and limit/offset pagination) <http://django-elasticsearch-dsl-drf.readthedocs.io/en/0.22.5/advanced_usage_examples.html#pagination>`_.\n- `Ids filter backend <http://django-elasticsearch-dsl-drf.readthedocs.io/en/0.22.5/advanced_usage_examples.html#ids-filter>`_.\n- `Multi match search filter backend <http://django-elasticsearch-dsl-drf.readthedocs.io/en/0.22.5/search_backends.html#multi-match-search-filter-backend>`_.\n- `Simple search query filter backend <http://django-elasticsearch-dsl-drf.readthedocs.io/en/0.22.5/search_backends.html#simple-query-string-filter-backend>`_.\n- `More-like-this support (detail action) <http://django-elasticsearch-dsl-drf.readthedocs.io/en/0.22.5/more_like_this.html>`_.\n- `Global aggregations support <http://django-elasticsearch-dsl-drf.readthedocs.io/en/0.22.5/global_aggregations.html>`_.\n- `Source filter backend <http://django-elasticsearch-dsl-drf.readthedocs.io/en/0.22.5/source_backend.html>`_.\n\nDo you need a similar tool for GraphQL? Check `graphene-elastic\n<https://github.com/barseghyanartur/graphene-elastic>`__.\n\nDemos\n=====\nOnline demo\n-----------\nCheck the `live demo app <https://django-elasticsearch-dsl-drf.herokuapp.com>`__\n(Django 3.1 + Django REST Framework 3.12 + Elasticsearch 7.5) hosted on Heroku\nand bonsai.io.\n\nLocal demo\n----------\nA frontend demo (React based) is available. See the `dedicated docs\n<https://github.com/barseghyanartur/django-elasticsearch-dsl-drf/blob/master/examples/frontend/README.rst>`_\nfor more information.\n\nTo bootstrap evaluation, clone the repository locally and run `docker-compose`.\n\n.. code-block:: sh\n\n docker-compose up\n\nIt will set up:\n\n- Elasticsearch on `http://localhost:9200 <http://localhost:9200>`_\n- Django REST framework on `http://localhost:8000 <http://localhost:8000>`_\n- React on `http://localhost:3000 <http://localhost:3000>`_\n\nInstallation\n============\n(1) Install latest stable version from PyPI:\n\n .. code-block:: sh\n\n pip install django-elasticsearch-dsl-drf\n\n or latest stable version from GitHub:\n\n .. code-block:: sh\n\n pip install https://github.com/barseghyanartur/django-elasticsearch-dsl-drf/archive/stable.tar.gz\n\n(2) Add ``rest_framework``, ``django_elasticsearch_dsl`` and\n ``django_elasticsearch_dsl_drf`` to ``INSTALLED_APPS``:\n\n .. code-block:: python\n\n INSTALLED_APPS = (\n # ...\n # REST framework\n 'rest_framework',\n\n # Django Elasticsearch integration\n 'django_elasticsearch_dsl',\n\n # Django REST framework Elasticsearch integration (this package)\n 'django_elasticsearch_dsl_drf',\n # ...\n )\n\nQuick start\n===========\nPerhaps the easiest way to get acquainted with ``django-elasticsearch-dsl-drf``\nis to read the `quick start tutorial <http://django-elasticsearch-dsl-drf.readthedocs.io/en/0.22.5/quick_start.html>`_.\n\nSee it as a guide of diving into integration of Elasticsearch with Django\nwith very low knowledge entry level.\n\nTesting\n=======\nProject is covered with tests.\n\nTo test with all supported Python/Django versions type:\n\n.. code-block:: sh\n\n tox\n\nTo test against specific environment, type:\n\n.. code-block:: sh\n\n tox -e py38-django30\n\nTo test just your working environment type:\n\n.. code-block:: sh\n\n ./runtests.py\n\nTo run a single test in your working environment type:\n\n.. code-block:: sh\n\n ./runtests.py src/django_elasticsearch_dsl_drf/tests/test_filtering.py\n\nOr:\n\n.. code-block:: sh\n\n ./manage.py test django_elasticsearch_dsl_drf.tests.test_ordering\n\nTo run a single test class in a given test module in your working environment\ntype:\n\n.. code-block:: sh\n\n ./runtests.py src/django_elasticsearch_dsl_drf/tests/test_suggesters.py::TestSuggesters\n\nIt's assumed that you have all the requirements installed. If not, first\ninstall the test requirements:\n\n.. code-block:: sh\n\n pip install -r examples/requirements/test.txt\n\nWriting documentation\n=====================\nKeep the following hierarchy.\n\n.. code-block:: text\n\n =====\n title\n =====\n\n header\n ======\n\n sub-header\n ----------\n\n sub-sub-header\n ~~~~~~~~~~~~~~\n\n sub-sub-sub-header\n ^^^^^^^^^^^^^^^^^^\n\n sub-sub-sub-sub-header\n ++++++++++++++++++++++\n\n sub-sub-sub-sub-sub-header\n **************************\n\nLicense\n=======\nGPL-2.0-only OR LGPL-2.1-or-later\n\nSupport\n=======\nFor any issues contact me at the e-mail given in the `Author`_ section.\n\nAuthor\n======\nArtur Barseghyan <artur.barseghyan@gmail.com>\n",
"bugtrack_url": null,
"license": "GPL-2.0-only OR LGPL-2.1-or-later",
"summary": "Integrate Elasticsearch DSL with Django REST framework.",
"version": "0.22.5",
"split_keywords": [
"django",
"elasticsearch",
"elasticsearch-dsl",
"django rest framework"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "a6b9a3b2f1db26ebf0eb41630ac9d182",
"sha256": "fc0b3960e16f6c06de4f2ca4daf1134376fce4d496c1ddc218c23daddf6bcaa0"
},
"downloads": -1,
"filename": "django_elasticsearch_dsl_drf-0.22.5-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "a6b9a3b2f1db26ebf0eb41630ac9d182",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=2.7",
"size": 151890,
"upload_time": "2022-07-03T22:17:09",
"upload_time_iso_8601": "2022-07-03T22:17:09.717068Z",
"url": "https://files.pythonhosted.org/packages/54/4d/4432adbe667791a621b0dc5421c9d32817f010b22e53656038f427eca5c0/django_elasticsearch_dsl_drf-0.22.5-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "a7a28b8938fb766ea8ace7f24a7b32eb",
"sha256": "b444f168535ff99244cc995ec354a31abcbf3fc03bd7b11ec1a3f43c7208f63a"
},
"downloads": -1,
"filename": "django-elasticsearch-dsl-drf-0.22.5.tar.gz",
"has_sig": false,
"md5_digest": "a7a28b8938fb766ea8ace7f24a7b32eb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=2.7",
"size": 99055,
"upload_time": "2022-07-03T22:17:12",
"upload_time_iso_8601": "2022-07-03T22:17:12.364750Z",
"url": "https://files.pythonhosted.org/packages/0a/b1/5a6366036349d384ae7fa1a9cd589b921419213ae504f7924c3363a7b239/django-elasticsearch-dsl-drf-0.22.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-07-03 22:17:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "barseghyanartur",
"github_project": "django-elasticsearch-dsl-drf",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [],
"tox": true,
"lcname": "django-elasticsearch-dsl-drf"
}
JSON
