Metadata-Version: 2.0
Name: algoliasearch-django
Version: 1.3.0
Summary: Algolia Search integration for Django
Home-page: https://github.com/algolia/algoliasearch-django
Author: Algolia Team
Author-email: support@algolia.com
License: MIT License
Keywords: algolia,pyalgolia,search,backend,hosted,cloud,full-text search,faceted search,django
Platform: UNKNOWN
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Dist: algoliasearch
Requires-Dist: django (>=1.7)

Algolia Search API Client for Django
====================================

`Algolia Search <https://www.algolia.com>`__ is a hosted full-text,
numerical, and faceted search engine capable of delivering realtime
results from the first keystroke.

|Build Status| |Coverage Status| |PyPI version|

This package lets you easily integrate the Algolia Search API to your
`Django <https://www.djangoproject.com/>`__ project. It's based on the
`algoliasearch-client-python <https://github.com/algolia/algoliasearch-client-python>`__
package.

You might be interested in this sample Django application providing a
typeahead.js based auto-completion and Google-like instant search:
`algoliasearch-django-example <https://github.com/algolia/algoliasearch-django-example>`__

Compatible with **Python 2.7**, **Python 3.3+** and **Django 1.7+**

API Documentation
-----------------

You can find the full reference on `Algolia's
website <https://www.algolia.com/doc/api-client/django/>`__.

Table of Contents
-----------------

1. **`Setup <#setup>`__**

   -  `Install <#install>`__
   -  `Setup <#setup>`__
   -  `Quick Start <#quick-start>`__

2. **`Commands <#commands>`__**

   -  `Commands <#commands>`__

3. **`Search <#search>`__**

   -  `Search <#search>`__

4. **`Geo-Search <#geo-search>`__**

   -  `Geo-Search <#geo-search>`__

5. **`Tags <#tags>`__**

   -  `Tags <#tags>`__

6. **`Options <#options>`__**

   -  `Custom ``objectID`` <#custom-objectid>`__
   -  `Custom index name <#custom-index-name>`__
   -  `Index settings <#index-settings>`__
   -  `Restrict indexing to a subset of your
      data <#restrict-indexing-to-a-subset-of-your-data>`__

7. **`Tests <#tests>`__**

   -  `Run Tests <#run-tests>`__

Setup
=====

Install
-------

.. code:: sh

    pip install algoliasearch-django

Setup
-----

In your Django settings, add ``django.contrib.algoliasearch`` to
``INSTALLED_APPS`` and add these two settings:

.. code:: python

    ALGOLIA = {
        'APPLICATION_ID': 'MyAppID',
        'API_KEY': 'MyApiKey'
    }

There are three optional settings:

-  ``INDEX_PREFIX``: prefix all indexes. Use it to separate different
   applications, like ``site1_Products`` and ``site2_Products``.
-  ``INDEX_SUFFIX``: suffix all indexes. Use it to differenciate
   development and production environment, like ``Location_dev`` and
   ``Location_prod``.
-  ``AUTO_INDEXING``: automatically synchronize the models with Algolia
   (default to **True**).

Quick Start
-----------

Simply call ``algoliasearch.register()`` for each of the models you want
to index. A good place to do this is in your application's AppConfig
(generally named ``apps.py``). More info in the
`documentation <https://docs.djangoproject.com/en/1.8/ref/applications/>`__

.. code:: python

    from django.apps import AppConfig
    from django.contrib import algoliasearch

    class YourAppConfig(AppConfig):
        name = 'your_app'

        def ready(self):
            YourModel = self.get_model('your_model')
            algoliasearch.register(YourModel)

And then, don't forget the line below in the ``__init__.py`` file of
your Django application.

.. code:: python

    default_app_config = 'your_django_app.apps.YourAppConfig'

By default, all the fields of your model will be used. You can configure
the index by creating a subclass of ``AlgoliaIndex``. A good place to do
this is in a separate file, like ``index.py``.

.. code:: python

    from django.contrib.algoliasearch import AlgoliaIndex

    class YourModelIndex(AlgoliaIndex):
        fields = ('name', 'date')
        geo_field = 'location'
        settings = {'searchableAttributes': ['name']}
        index_name = 'my_index'

And then replace ``algoliasearch.register(YourModel)`` with
``algoliasearch.register(YourModel, YourModelIndex)``.

Commands
========

Commands
--------

-  ``python manage.py algolia_reindex``: reindex all the registered
   models. This command will first send all the record to a temporary
   index and then moves it.

   -  you can pass ``--model`` parameter to reindex a given model

-  ``python manage.py algolia_applysettings``: (re)apply the index
   settings.
-  ``python manage.py algolia_clearindex``: clear the index

Search
======

Search
------

We recommend the usage of our `JavaScript API
Client <https://github.com/algolia/algoliasearch-client-javascript>`__
to perform queries directly from the end-user browser without going
through your server.

However, if you want to search from your backend you can use the
``raw_search(YourModel, 'yourQuery', params)`` method. It retrieves the
raw JSON answer from the API.

.. code:: python

    from django.contrib.algoliasearch import raw_search

    params = { "hitsPerPage": 5 }
    raw_search(Contact, "jim", params)

Geo-Search
==========

Geo-Search
----------

Use the ``geo_field`` attribute to localize your record. ``geo_field``
should be a callable that returns a tuple (latitude, longitude).

.. code:: python

    class Contact(models.model):
        name = models.CharField(max_lenght=20)
        lat = models.FloatField()
        lng = models.FloatField()

        def location(self):
            return (self.lat, self.lng)

    class ContactIndex(AlgoliaIndex):
        fields = 'name'
        geo_field = 'location'

    algoliasearch.register(Contact, ContactIndex)

Tags
====

Tags
----

Use the ``tags`` attributes to add tags to your record. It can be a
field or a callable.

.. code:: python

    class ArticleIndex(AlgoliaIndex):
        tags = 'category'

At query time, specify ``{ tagFilters: 'tagvalue' }`` or
``{ tagFilters: ['tagvalue1', 'tagvalue2'] }`` as search parameters to
restrict the result set to specific tags.

Options
=======

Custom ``objectID``
-------------------

You can choose which field will be used as the ``objectID``. The field
should be unique and can be a string or integer. By default, we use the
``pk`` field of the model.

.. code:: python

    class ArticleIndex(AlgoliaIndex):
        custom_objectID = 'post_id'

Custom index name
-----------------

You can customize the index name. By default, the index name will be the
name of the model class.

.. code:: python

    class ContactIndex(algoliaindex):
        index_name = 'Enterprise'

Index settings
--------------

We provide many ways to configure your index allowing you to tune your
overall index relevancy. All the configuration is explained on `our
doc <https://www.algolia.com/doc/api-client/python/parameters/>`__.

.. code:: python

    class ArticleIndex(AlgoliaIndex):
        settings = {
            'searchableAttributes': ['name', 'description', 'url'],
            'customRanking': ['desc(vote_count)', 'asc(name)']
        }

Restrict indexing to a subset of your data
------------------------------------------

You can add constraints controlling if a record must be indexed or not.
``should_index`` should be a callable that returns a boolean.

.. code:: python

    class Contact(models.model):
        name = models.CharField(max_lenght=20)
        age = models.IntegerField()

        def is_adult(self):
            return (self.age >= 18)

    class ContactIndex(AlgoliaIndex):
        should_index = 'is_adult'

Tests
=====

Run Tests
---------

To run the tests, first find your Algolia application id and Admin API
key (found on the Credentials page).

.. code:: shell

    ALGOLIA_APPLICATION_ID={APPLICATION_ID} ALGOLIA_API_KEY={ADMIN_API_KEY} tox

.. |Build Status| image:: https://travis-ci.org/algolia/algoliasearch-django.svg?branch=master
   :target: https://travis-ci.org/algolia/algoliasearch-django
.. |Coverage Status| image:: https://coveralls.io/repos/algolia/algoliasearch-django/badge.svg?branch=master
   :target: https://coveralls.io/r/algolia/algoliasearch-django
.. |PyPI version| image:: https://badge.fury.io/py/algoliasearch-django.svg?branch=master
   :target: http://badge.fury.io/py/algoliasearch-django


