Permalink
Browse files

Issue 41. Move django bits to contrib

This reworks the codebase so that it doesn't require Django. There
are some API breaking things here, but hopefully the changes required
for users will be minimal.
  • Loading branch information...
1 parent e5b06fe commit 587e3071bf9ed06051fa879670f1299f455e6d2c Will Kahn-Greene committed Jun 28, 2012
View
@@ -8,8 +8,22 @@ Version 0.4: Released xxx
**API-breaking changes:**
-* Moved `ESTestCase` from ``elasticutils.tests`` to
- ``elasticutils.djangolib``
+* **ElasticUtils no longer requires Django.** If you're using Django,
+ you should change your import statements from things like::
+
+ from elasticutils import get_es, S, F
+
+ to::
+
+ from elasticutils.contrib.django import get_es, S, F
+
+ Further, Django helper modules like ``cron``, ``tasks``, and
+ ``models`` were all moved to ``elasticutils.contrib.django``.
+
+ We moved `ESTestCase` from ``elasticutils.tests`` to
+ ``elasticutils.contrib.django.estestcase``
+
+ If you don't use Django, ElasticUtils is easier to use!
**Changes:**
@@ -19,6 +33,25 @@ Version 0.4: Released xxx
DJANGO_SETTINGS_MODULE=es_settings nosetests
+* Default timeout was changed from 1 second to 5 seconds.
+
+* Added ``es`` transform: it allows you to specify the settings with which
+ to create an ES when the search is executed.
+
+* Added ``es_builder`` transform: it allows you to specify a function
+ that builds an ES which will be executed to create an ES when the
+ search is executed.
+
+* Added ``indexes`` transform: it allows you to specify the indexes to
+ use for the search.
+
+* Added ``doctypes`` transform: it allows you to specify the doctypes
+ to use for the search.
+
+* Removed requirement for nuggits.
+
+* Continued to improve documentation.
+
Version 0.3: Released June 1st, 2012
====================================
View
@@ -0,0 +1 @@
+.. include:: ../CHANGELOG
@@ -1,61 +0,0 @@
-=============
-Configuration
-=============
-
-ElasticUtils depends on the following settings:
-
-.. module:: django.conf.settings
-
-.. data:: ES_DISABLED
-
- Disables talking to ElasticSearch from your app. Any method
- wrapped with `es_required` will return and log a warning. This is
- useful while developing, so you don't have to have ElasticSearch
- running.
-
-.. data:: ES_DUMP_CURL
-
- If set to a path all the requests that `ElasticUtils` makes will
- be dumped into the designated file.
-
- .. note:: Python does not write this file until the process is
- finished.
-
-
-.. data:: ES_HOSTS
-
- This is a list of hosts. In development this will look like::
-
- ES_HOSTS = ['127.0.0.1:9200']
-
-.. data:: ES_INDEXES
-
- This is a mapping of doctypes to indexes. A `default` mapping is
- required for types that don't have a specific index.
-
- When ElasticUtils queries the index for a model, it derives the
- doctype from `Model._meta.db_table`. When you build your indexes
- and doctypes, make sure to name them after your model db_table.
-
- Example 1::
-
- ES_INDEXES = {'default': 'main_index'}
-
- This only has a default, so ElasticUtils queries will look in
- `main_index` for all doctypes.
-
- Example 2::
-
- ES_INDEXES = {'default': 'main_index',
- 'splugs': 'splugs_index'}
-
- Assuming you have a `Splug` model which has a
- `Splug._meta.db_table` value of `splugs`, then ElasticUtils will
- run queries for `Splug` in the `splugs_index`. ElasticUtils will
- run queries for other models in `main_index` because that's the
- default.
-
-.. data:: ES_TIMEOUT
-
- Defines the timeout for the `ES` connection. This defaults to 1
- second.
View
@@ -6,26 +6,124 @@ Using with Django
:local:
+Summary
+=======
+
+Django helpers are all located in `elasticutils.contrib.django`.
+
+This chapter covers using ElasticUtils Django bits.
+
+
+Configuration
+=============
+
+ElasticUtils depends on the following settings:
+
+.. module:: django.conf.settings
+
+.. data:: ES_DISABLED
+
+ Disables talking to ElasticSearch from your app. Any method
+ wrapped with `es_required` will return and log a warning. This is
+ useful while developing, so you don't have to have ElasticSearch
+ running.
+
+.. data:: ES_DUMP_CURL
+
+ If set to a path all the requests that `ElasticUtils` makes will
+ be dumped into the designated file.
+
+ .. note:: Python does not write this file until the process is
+ finished.
+
+
+.. data:: ES_HOSTS
+
+ This is a list of hosts. In development this will look like::
+
+ ES_HOSTS = ['127.0.0.1:9200']
+
+.. data:: ES_INDEXES
+
+ This is a mapping of doctypes to indexes. A `default` mapping is
+ required for types that don't have a specific index.
+
+ When ElasticUtils queries the index for a model, it derives the
+ doctype from `Model._meta.db_table`. When you build your indexes
+ and doctypes, make sure to name them after your model db_table.
+
+ Example 1::
+
+ ES_INDEXES = {'default': 'main_index'}
+
+ This only has a default, so ElasticUtils queries will look in
+ `main_index` for all doctypes.
+
+ Example 2::
+
+ ES_INDEXES = {'default': 'main_index',
+ 'splugs': 'splugs_index'}
+
+ Assuming you have a `Splug` model which has a
+ `Splug._meta.db_table` value of `splugs`, then ElasticUtils will
+ run queries for `Splug` in the `splugs_index`. ElasticUtils will
+ run queries for other models in `main_index` because that's the
+ default.
+
+.. data:: ES_TIMEOUT
+
+ Defines the timeout for the `ES` connection. This defaults to 5
+ seconds.
+
+
+ES
+==
+
+The `get_es()` in the Django contrib will helpfully cache your ES
+objects thread-local.
+
+It is built with the settings from your `django.conf.settings`.
+
+.. Note::
+
+ `get_es()` only caches the `ES` if you don't pass in any override
+ arguments. If you pass in override arguments, it doesn't cache it,
+ but instead creates a new one.
+
+
Using with Django ORM models
============================
Django models and ElasticSearch indices make a natural fit. It would
be terribly useful if a Django model knew how to add and remove itself
from ElasticSearch. This is where the
-:class:`elasticutils.models.SearchMixin` comes in.
+:class:`elasticutils.contrib.django.models.SearchMixin` comes in.
+
+Two things to know:
+
+1. The doctype for the model is `cls._meta.db_table`.
+
+2. The index that's searched is ``settings.ES_INDEXES[doctype]`` and
+ if that doesn't exist, it defaults to
+ ``settings.ES_INDEXES['default']``
+
+
+
+Other helpers
+=============
You can then utilize things such as
-:func:`~elasticutils.tasks.index_objects` to automatically index all
-new items.
+:func:`~elasticutils.contrib.django.tasks.index_objects` to
+automatically index all new items.
-.. autoclass:: elasticutils.models.SearchMixin
+.. autoclass:: elasticutils.contrib.django.models.SearchMixin
:members:
-.. automodule:: elasticutils.tasks
+.. automodule:: elasticutils.contrib.django.tasks
.. autofunction:: index_objects(model, ids=[...])
-.. automodule:: elasticutils.cron
+.. automodule:: elasticutils.contrib.django.cron
.. autofunction:: reindex_objects(model, chunk_size[=150])
@@ -38,8 +136,8 @@ Requires:
* `test_utils <https://github.com/jbalogh/test-utils>`_
* `nose <http://nose.readthedocs.org/en/latest/>`_
-In `elasticutils.djangolib`, is `ESTestCase` which can be subclassed
-in your app's test cases.
+In `elasticutils.contrib.django.estestcase`, is `ESTestCase` which can
+be subclassed in your app's test cases.
It does the following:
View
@@ -3,21 +3,14 @@ ES
==
`pyes` comes with a handy `ES` object. `elasticutils` has a `get_es()`
-function which builds an `ES` and if it's generic, will cache it
-thread-local.
+function which builds an `ES`.
.. autofunction:: elasticutils.get_es
-.. Note::
-
- `get_es()` only caches the `ES` if you don't pass in any override
- arguments. If you pass in override arguments, it doesn't cache it,
- but instead creates a new one.
-
.. Warning::
- ElasticUtils works best with ``pyes`` 0.15. The API for later
- versions has changed too drastically. While we'd welcome
+ ElasticUtils works best with ``pyes`` 0.15 and 0.16. The API for
+ later versions has changed too drastically. While we'd welcome
compatibility patches, we feel a better approach would be to remove
our dependency on ``pyes``.
View
@@ -26,7 +26,6 @@ User's Guide
changelog
installation
- configuration
es
queries
django
View
@@ -16,18 +16,18 @@ For example:
.. code-block:: python
- q = (S(model).query(title='Example')
- .filter(product='firefox')
- .filter(version='4.0', platform='all')
- .facet(products={'field':'product', 'global': True})
- .facet(versions={'field': 'version'})
- .facet(platforms={'field': 'platform'})
- .facet(types={'field': 'type'}))
-
-
-Assume that `model` here dictated that we're looking in the
-`addon_index` for `addon` document type. Then the elasticsearch REST
-API curl for that looks like::
+ q = (S(MyModel).filter(product='firefox')
+ .filter(version='4.0', platform='all')
+ .facet(products={'field':'product', 'global': True})
+ .facet(versions={'field': 'version'})
+ .facet(platforms={'field': 'platform'})
+ .facet(types={'field': 'type'})
+ .doctypes('addon')
+ .indexes('addon_index')
+ .query(title='Example'))
+
+
+The ElasticSearch REST API curl would look like this::
$ curl -XGET 'http://localhost:9200/addon_index/addon/_search' -d '{
'query': {'term': {'title': 'Example'}},
Oops, something went wrong. Retry.

0 comments on commit 587e307

Please sign in to comment.