Metadata-Version: 2.0
Name: django-elasticsearch-dsl-drf
Version: 0.16.2
Summary: Integrate Elasticsearch DSL with Django REST framework.
Home-page: https://github.com/barseghyanartur/django-elasticsearch-dsl-drf/
Author: Artur Barseghyan
Author-email: artur.barseghyan@gmail.com
License: GPL 2.0/LGPL 2.1
Description-Content-Type: UNKNOWN
Keywords: django,elasticsearch,elasticsearch-dsl,django rest framework
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Environment :: Web Environment
Classifier: License :: OSI Approved :: GNU General Public License v2 (GPLv2)
Classifier: License :: OSI Approved :: GNU Lesser General Public License v2 or later (LGPLv2+)
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 4 - Beta
Requires-Dist: six (>=1.9)
Requires-Dist: django-nine (>=0.1.10)
Requires-Dist: django-elasticsearch-dsl (>=0.3)
Requires-Dist: elasticsearch-dsl
Requires-Dist: elasticsearch
Requires-Dist: djangorestframework

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

Prerequisites
=============

- Django 1.8, 1.9, 1.10, 1.11, 2.0 and 2.1.
- Python 2.7, 3.4, 3.5, 3.6, 3.7
- Elasticsearch 2.x, 5.x, 6.x

Dependencies
============

**elasticsearch and elasticsearch-dsl**

Depending on your Elasticsearch version (either 2.x, 5.x or 6.x) you should
use 2.x, 5.x or 6.x versions of the ``elasticsearch`` and ``elasticsearch-dsl``
packages accordingly.

**django-elasticsearch-dsl**

You are advised to use the latest version of `django-elasticsearch-dsl
<https://pypi.python.org/pypi/django-elasticsearch-dsl>`_.

**djangorestframework**

Initial version of this package was written for `djangorestframework
<https://pypi.python.org/pypi/djangorestframework>`_ 3.6.2.

Documentation
=============

Documentation is available on `Read the Docs
<http://django-elasticsearch-dsl-drf.readthedocs.io/>`_.

Main features and highlights
============================

- `Dynamic serializer for Documents <http://django-elasticsearch-dsl-drf.readthedocs.io/en/0.16.2/basic_usage_examples.html#sample-serializer>`_.
- `Search filter backend <http://django-elasticsearch-dsl-drf.readthedocs.io/en/0.16.2/advanced_usage_examples.html#search>`_.
- `Ordering filter backend <http://django-elasticsearch-dsl-drf.readthedocs.io/en/0.16.2/advanced_usage_examples.html#ordering>`_.
- `Filtering filter backend <http://django-elasticsearch-dsl-drf.readthedocs.io/en/0.16.2/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.16.2/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.16.2/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.16.2/advanced_usage_examples.html#faceted-search>`_.
- `Post-filter filter backend <http://django-elasticsearch-dsl-drf.readthedocs.io/en/0.16.2/advanced_usage_examples.html#post-filter>`_.
- `Nested filtering filter backend <http://django-elasticsearch-dsl-drf.readthedocs.io/en/0.16.2/nested_fields_usage_examples.html#nested-filtering>`_.
- `Highlight backend <http://django-elasticsearch-dsl-drf.readthedocs.io/en/0.16.2/advanced_usage_examples.html#highlighting>`_.
- `Suggester filter backend <http://django-elasticsearch-dsl-drf.readthedocs.io/en/0.16.2/advanced_usage_examples.html#suggestions>`_.
- `Functional suggester filter backend <http://django-elasticsearch-dsl-drf.readthedocs.io/en/0.16.2/advanced_usage_examples.html#functional-suggestions>`_.
- `Pagination (Page number and limit/offset pagination) <http://django-elasticsearch-dsl-drf.readthedocs.io/en/0.16.2/advanced_usage_examples.html#pagination>`_.
- `Ids filter backend <http://django-elasticsearch-dsl-drf.readthedocs.io/en/0.16.2/advanced_usage_examples.html#ids-filter>`_.
- `Multi match search filter backend <http://django-elasticsearch-dsl-drf.readthedocs.io/en/0.16.2/search_backends.html#multi-match-search-filter-backend>`_.
- `Simple search query filter backend <http://django-elasticsearch-dsl-drf.readthedocs.io/en/0.16.2/search_backends.html#simple-query-string-filter-backend>`_.
- `More-like-this support (detail action) <http://django-elasticsearch-dsl-drf.readthedocs.io/en/0.16.2/more_like_this.html>`_.
- `Global aggregations support <http://django-elasticsearch-dsl-drf.readthedocs.io/en/0.16.2/global_aggregations.html>`_.

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

    or latest stable version from BitBucket:

    .. code-block:: sh

        pip install https://bitbucket.org/barseghyanartur/django-elasticsearch-dsl-drf/get/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.16.2/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 py37-django21

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

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/LGPL 2.1

Support
=======

For any issues contact me at the e-mail given in the `Author`_ section.

Author
======

Artur Barseghyan <artur.barseghyan@gmail.com>


