Django API docs¶
The S class¶
- class elasticutils.contrib.django.S(mapping_type)¶
S that’s based on Django settings
This shows the Django-specific documentation. See elasticutils.S for more the rest.
- __init__(mapping_type)¶
Create and return an S.
Parameters: mapping_type – class; the mapping type that this S is based on Note
The elasticutils.S doesn’t require the mapping_type argument, but the elasticutils.contrib.django.S does.
- get_doctypes(default_doctypes=None)¶
Returns the doctypes (or mapping type names) to use.
- get_es(default_builder=<function get_es at 0x4061f50>)¶
Returns the pyelasticsearch ElasticSearch object to use.
This uses the django get_es builder by default which takes into account settings in settings.py.
- get_indexes(default_indexes=None)¶
Returns the list of indexes to act on based on ES_INDEXES setting
The MappingType class¶
- class elasticutils.contrib.django.MappingType¶
MappingType that ties to Django ORM models
You probably want to subclass this and override at least get_model().
This shows the Django-specific documentation. See elasticutils.MappingType for more the rest.
- classmethod get_index()¶
Gets the index for this model.
The index for this model is specified in settings.ES_INDEXES which is a dict of mapping type -> index name.
By default, this uses .get_mapping_type() to determine the mapping and returns the value in settings.ES_INDEXES for that or settings.ES_INDEXES['default'].
Override this to compute it differently.
Returns: index name to use
- classmethod get_mapping_type_name()¶
Returns the name of the mapping.
By default, this is:
cls.get_model()._meta.db_table
Override this if you want to compute the mapping type name differently.
Returns: mapping type string
- classmethod get_model()¶
Return the model related to this DjangoMappingType.
This can be any class that has an instance related to this DjangoMappingtype by id.
Override this to return a model class.
Returns: model class
- get_object()¶
Returns the database object for this result
By default, this is:
self.get_model().objects.get(pk=self._id)
- classmethod search()¶
Returns a typed S for this class.
Returns: an S for this DjangoMappingType
The Indexable class¶
- class elasticutils.contrib.django.Indexable¶
MappingType mixin that has indexing bits
Add this mixin to your MappingType subclass and it gives you super indexing power.
This shows the Django-specific documentation. See elasticutils.Indexable for more the rest.
- classmethod get_es(**overrides)¶
Returns an ElasticSearch object using Django settings
Override this if you need special functionality.
Parameters: overrides – Allows you to override defaults to create the ElasticSearch object. You can override any of the arguments listed in elasticutils.get_es(). Returns: a pyelasticsearch ElasticSearch instance
- classmethod get_indexable()¶
Returns the queryset of ids of all things to be indexed.
Defaults to:
cls.get_model().objects.order_by('id').values_list( 'id', flat=True)
Returns: iterable of ids of objects to be indexed
View decorators¶
- elasticutils.contrib.django.es_required(fun)¶
Wrap a callable and return None if ES_DISABLED is False.
This also adds an additional es argument to the callable giving you an ElasticSearch instance to use.
- elasticutils.contrib.django.es_required_or_50x(*m_args, **m_kwargs)¶
The ESExceptionMiddleware class¶
- class elasticutils.contrib.django.ESExceptionMiddleware(disabled_template=None, error_template=None)¶
Middleware to handle Elasticsearch errors.
- HTTP 501
- Returned when ES_DISABLED is True.
- HTTP 503
Returned when any of the following exceptions are thrown:
- pyelasticsearch.exceptions.ConnectionError
- pyelasticsearch.exceptions.ElasticHttpError
- pyelasticsearch.exceptions.ElasticHttpNotFoundError
- pyelasticsearch.exceptions.InvalidJsonResponseError
- pyelasticsearch.exceptions.Timeout
Template variables:
- error: A string version of the exception thrown.
Parameters: - disabled_template –
The template to use when ES_DISABLED is True.
Defaults to elasticutils/501.html.
- error_template –
The template to use when Elasticsearch isn’t working properly, is missing an index, or something along those lines.
Defaults to elasticutils/503.html.
Note
In order to use the included templates, you must add elasticutils.contrib.django to INSTALLED_APPS.
Tasks¶
- elasticutils.contrib.django.tasks.index_objects(model, ids=[...])¶
Index documents of a specified mapping type.
This allows for asynchronous indexing.
If a mapping_type extends Indexable, you can add a post_save hook for the model that it’s based on like this:
@receiver(dbsignals.post_save, sender=MyModel) def update_in_index(sender, instance, **kw): from elasticutils.contrib.django import tasks tasks.index_objects.delay(MyMappingType, [instance.id])
Parameters: - mapping_type – the mapping type for these ids
- ids – the list of ids of things to index
- chunk_size – the size of the chunk for bulk indexing
Note
The default chunk_size is 100. The number of documents you can bulk index at once depends on the size of the documents.
The ESTestCase class¶
Subclass this and make it do what you need it to do. It’s definitely worth reading the code.
- class elasticutils.contrib.django.estestcase.ESTestCase(methodName='runTest')¶
Test case scaffolding for ElasticUtils-using tests.
If ES_URLS is empty or missing or you can’t connect to Elasticsearch specified in ES_URLS, then this will skip each individual test. This works with py.test, nose, and unittest in Python 2.7. If you don’t have one of those, then this will print to stdout and just skip the test silently.
- classmethod create_index(index, settings=None)¶
Creates index with given settings
Parameters: - index – the name of the index to create
- settings – dict of settings to set in create_index call
- classmethod get_es()¶
Returns an ES
Override this if you need different settings for your ES.
- classmethod index_data(documents, index, doctype, id_field='id')¶
Bulk indexes given data.
This does a refresh after the data is indexed.
Parameters: - documents – list of python dicts each a document to index
- index – name of the index
- doctype – mapping type name
- id_field – the field the document id is stored in in the document
- classmethod refresh(index)¶
Refresh index after indexing.
Parameters: index – the name of the index to refresh. use _all to refresh all of them
- setUp()¶
Skips the test if this class is skipping tests.
- classmethod setUpClass()¶
Sets up the environment for ES tests
- pings the ES server—if this fails, it marks all the tests for skipping
- fixes settings
- deletes the test index if there is one
- classmethod tearDownClass()¶
Tears down environment
- unfixes settings
- deletes the test index