Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/barseghyanartur/django-elasticsearch-dsl-drf

Integrate Elasticsearch DSL with Django REST framework.
https://github.com/barseghyanartur/django-elasticsearch-dsl-drf

django django-rest-framework django-rest-framework-addon djangorestframework elasticsearch elasticsearch-dsl

Last synced: about 14 hours ago
JSON representation

Integrate Elasticsearch DSL with Django REST framework.

Awesome Lists containing this project

README 

        
============================

django-elasticsearch-dsl-drf

============================

Integrate `Elasticsearch DSL

`_ with

`Django REST framework `_ 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

`_ 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

`_.



Make sure to read `FAQ `_.



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

============================



- :doc:`Dynamic serializer for Documents `.

- :doc:`Search filter backend `.

- :doc:`Ordering filter backend `.

- :doc:`Filtering filter backend ` (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.

- :doc:`Geo-spatial filtering filter backend ` (the

  following filters implemented: ``geo_distance``, ``geo_polygon`` and

  ``geo_bounding_box``).

- :doc:`Geo-spatial ordering filter backend ` (the

  following filters implemented: ``geo_distance``).

- :doc:`Faceted search filter backend `.

- :doc:`Post-filter filter backend `.

- :doc:`Nested filtering filter backend `.

- :doc:`Highlight backend `.

- :doc:`Suggester filter backend `.

- :doc:`Functional suggester filter backend `.

- :doc:`Pagination (Page number and limit/offset pagination) `.

- :doc:`Ids filter backend `.

- :doc:`Multi match search filter backend `.

- :doc:`Simple search query search filter backend `.

- :doc:`More-like-this support (detail action) `.

- :doc:`Global aggregations support `.

- :doc:`Source filter backend `.



Do you need a similar tool for GraphQL? Check `graphene-elastic

`__.



Demos

=====

Online demo

-----------

Check the `live demo app `__

(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

`_

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 `_

- Django REST framework on `http://localhost:8000 `_

- React on `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 :doc:`quick start tutorial `.



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