Package documentation

Djangoes package aims to provide a simple way to integrate ElasticSearch.

This package mimics the behavior of the Django database configuration layer, using project settings and a global connections handler.

The simplest way to use djangoes is to import djangoes.connection and to perform queries with it:

>>> from djangoes import connections
>>> conn = connections['conn_name']
>>> result = conn.search(...)

The ConnectionHandler.load_backend() is called whenever a connection is requested in the application, which will then call multiple methods to ensure default values and test values.

There is a shortcut to get the default connection:

>>> from djangoes import connection, connections
>>> connection == connections['default']
True
>>> result = connection.search(...)

It works exactly like getting the default connection from connections.

Note

This module is based on the django.db module, which is quite simple in its way to deal with connections. The djangoes package hope to stay as simple as possible for everyone, and to take benefit from the hard works that make Django a great framework.

• backends
  • backends.abstracts
  • backends.elasticsearch
• test
  • test.runner
  • test.testcases
  • test.utils

connections

Module-level attribute, instance of ConnectionHandler.

It can be considered as a singleton: it is the default connections handler to use with djangoes. It is instantiated at import with the default arguments.

Therefore, this object will automatically use the settings of your django project: ES_SERVERS and ES_INDICES.

class ConnectionHandler(servers=None, indices=None)

Handle connections to ElasticSearch.

Based on django.db.utils.ConnectionHandler, it aims to be an interface to integrate ElasticSearch connections in the same way database connections are integrated in Django.

However, instead of relaying on one setting variable, it needs two:

• servers: ElasticSearch clusters connections settings (host, port, etc.)
• indices: indices (or indexes) settings (name, aliases, analyzers, etc.)

These two will be defined in the django project settings with ES_SERVERS and ES_INDICES.

all()

Return all configured connection object.

It is a shortcut method to get all connections instead of manually doing a list-comprehension each time all connections are needed.

check_for_multiprocess()

Reset connections if PID has changed.

When using multi-processing (or fork), one may want to use a connection already used by the main process. Therefore, we need to make sure we are not sharing connections between multiple process.

This could happen because a fork on Linux won’t copy an object after a fork until it is modified. The read-only mode will “share” connections and that’s not what we want.

ensure_index_defaults(alias)

Put the defaults into the settings dictionary for alias.

ensure_server_defaults(alias)

Put the defaults into the settings dictionary for alias.

get_server_indices(server)

Prepare and return a given server’s indices settings.

Do not validate if the given server is available in self.servers: it is expected to find an INDICES key into server and that’s all.

It is expected to find indices configured with the same name in self.indices.

load_backend(alias)

Prepare and load a backend for the given alias.

prepare_index_test_settings(alias)

Make sure the test settings are available in TEST.

prepare_server_test_settings(alias)

Make sure the test settings are available in TEST.