Sobol implements a generic search interface, which can be used to search databases or websites. No assumptions are made about the search method. If SOBOL_USE_CACHE is True (default), the results will be cached using django’s cache framework. Be aware that this may use a large number of cache entries, as a unique entry will be made for each search string for each type of search.


Whether sobol will use django’s cache framework. Defaults to True; this may cause a lot of entries in the cache.
If eventlet is installed and this setting is True, sobol web searches will use instead of the built-in urllib2 module. Default: False.


For convenience, sobol provides a template at sobol/search/_list.html which can be used with an {% include %} tag inside a full search page template to list the search results. The _list.html template also uses a basic jQuery script (static/sobol/ajax_search.js) to handle AJAX search result loading if the AJAX API of the current SearchView is enabled. If you want to use _list.html, but want to provide your own version of jQuery or your own AJAX loading script, or if you want to include the basic script somewhere else (like inside the <head>) simply do the following:

{% include "sobol/search/_list.html" with suppress_scripts=1 %}


class philo.contrib.sobol.models.Search(*args, **kwargs)

Represents all attempts to search for a unique string.


The string which was searched for.


Returns a list of ResultURL instances related to the search and ordered by decreasing weight. This will be cached on the instance.

Parameters:threshhold – The earliest datetime that a Click can have been made on a related ResultURL in order to be included in the weighted results (or None to include all Clicks and ResultURLs).
get_favored_results(error=5, threshhold=None)

Calculates the set of most-favored results based on their weight. Evenly-weighted results will be grouped together and either added or excluded as a group.

  • error – An arbitrary number; higher values will cause this method to be more reticent about adding new items to the favored results.
  • threshhold – Will be passed directly into get_weighted_results()
class philo.contrib.sobol.models.ResultURL(*args, **kwargs)

Represents a URL which has been selected one or more times for a Search.


A ForeignKey to the Search which the ResultURL is related to.


The URL which was selected.


Calculates, caches, and returns the weight of the ResultURL.

Parameters:threshhold – The datetime limit before which Clicks will not contribute to the weight of the ResultURL.

Calculates, caches, and returns the weight of the ResultURL.

Parameters:threshhold – The datetime limit before which Clicks will not contribute to the weight of the ResultURL.
class philo.contrib.sobol.models.Click(*args, **kwargs)

Represents a click on a ResultURL.


A ForeignKey to the ResultURL which the Click is related to.


The datetime when the click was registered in the system.

get_weight(default=1, weighted=<function <lambda> at 0x28bb1b8>)

Calculates and returns the weight of the Click.


Calculates and returns the weight of the Click.

class philo.contrib.sobol.models.SearchView(*args, **kwargs)

Handles a view for the results of a search, anonymously tracks the selections made by end users, and provides an AJAX API for asynchronous search result loading. This can be particularly useful if some searches are slow.


ForeignKey to a Page which will be used to render the search results.


A SlugMultipleChoiceField whose choices are the contents of


A BooleanField which controls whether or not the AJAX API is enabled.


If the AJAX API is enabled, a ajax_api_url attribute will be added to each search instance containing the url and get parameters for an AJAX request to retrieve results for that search.


Be careful not to access search_instance.results if the AJAX API is enabled - otherwise the search will be run immediately rather than on the AJAX request.


A CharField containing the placeholder text which is intended to be used for the search box for the SearchView. It is the template author’s responsibility to make use of this information.


The form which will be used to validate the input to the search box for this SearchView.

results_view(request, extra_context=None)

Renders results_page with a context containing an instance of search_form. If the form was submitted and was valid, then one of two things has happened:

  • A search has been initiated. In this case, a list of search instances will be added to the context as searches. If enable_ajax_api is enabled, each instance will have an ajax_api_url attribute containing the url needed to make an AJAX request for the search results.
  • A link has been chosen. In this case, corresponding Search, ResultURL, and Click instances will be created and the user will be redirected to the link’s actual url.
ajax_api_view(request, slug, extra_context=None)

Returns a JSON object containing the following variables:

Contains the slug for the search.
Contains the results of Result.get_context() for each result.
Contains the results of Result.render() for each result.
True or False whether the search has more results according to BaseSearch.has_more_results()
Contains None or a querystring which, once accessed, will note the Click and redirect the user to a page containing more results.

Search API

A registry for BaseSearch subclasses that should be available in the admin., search_arg)

Returns a search instance for the given slug, either from the cache or newly-instantiated.

class, result)

Result is a helper class that, given a search and a result of that search, is able to correctly render itself with a template defined by the search. Every Result will pass a title, a url (if applicable), and the raw result returned by the search into the template context when rendering.

  • search – An instance of a BaseSearch subclass or an object that implements the same API.
  • result – An arbitrary result from the search.

Returns the title of the result by calling BaseSearch.get_result_title() on the raw result.


Returns the url of the result or None by calling BaseSearch.get_result_url() on the raw result. This url will contain a querystring which, if used, will track a Click for the actual url.


Returns the actual url of the result by calling BaseSearch.get_actual_result_url() on the raw result.


Returns the content of the result by calling BaseSearch.get_result_content() on the raw result.


Returns the template which will be used to render the Result by calling BaseSearch.get_result_template() on the raw result.


Returns the context dictionary for the result. This is used both in rendering the result and in the AJAX return value for SearchView.ajax_api_view(). The context will contain the following keys:

The result of calling get_title()
The result of calling get_url()
The result of calling get_content()

Returns the template from get_template() rendered with the context from get_context().


Defines a generic search api. Accessing results will attempt to retrieve cached results and, if that fails, will initiate a new search and store the results in the cache. Each search has a verbose_name and a slug. If these are not provided as attributes, they will be automatically generated based on the name of the class.

Parameters:search_arg – The string which is being searched for.

The number of results to return from the complete list. Default: 5


The path to the template which will be used to render the Results for this search. If this is None, then the framework will try sobol/search/<slug>/result.html and sobol/search/result.html.


The path to the template which will be used to generate the title of the Results for this search. If this is None, then the framework will try sobol/search/<slug>/title.html and sobol/search/title.html.


The path to the template which will be used to generate the content of the Results for this search. If this is None, then the framework will try sobol/search/<slug>/content.html and sobol/search/content.html.


Retrieves cached results or initiates a new search via get_results() and caches the results.

get_results(limit=None, result_class=<class ''>)

Calls search() and parses the return value into Result instances.

  • limit – Passed directly to search().
  • result_class – The class used to represent the results. This will be instantiated with the BaseSearch instance and the raw result from the search.

Returns an iterable of up to limit results. The get_result_title(), get_result_url(), get_result_template(), and get_result_extra_context() methods will be used to interpret the individual items that this function returns, so the result can be an object with attributes as easily as a dictionary with keys. However, keep in mind that the raw results will be stored with django’s caching mechanisms and will be converted to JSON.


Returns the actual URL for the result or None if there is no URL. Must be implemented by subclasses.


Returns a querydict for tracking selection of the result, or None if there is no URL for the result.


Returns None or a url which, when accessed, will register a Click for that url.


Returns the title of the result. By default, renders sobol/search/<slug>/title.html or sobol/search/title.html with the result in the context. This can be overridden by setting title_template or simply overriding get_result_title(). If no template can be found, this will raise TemplateDoesNotExist.


Returns the content for the result. By default, renders sobol/search/<slug>/content.html or sobol/search/content.html with the result in the context. This can be overridden by setting content_template or simply overriding get_result_content(). If no template is found, this will return an empty string.


Returns the template to be used for rendering the result. For a search with slug google, this would first try sobol/search/google/result.html, then fall back on sobol/search/result.html. Subclasses can override this by setting result_template to the path of another template.


Returns True if there are more results than result_limit and False otherwise.


Returns the actual url for more results. By default, simply returns None.


Returns a QueryDict for tracking whether people click on a ‘more results’ link.


Returns a URL which consists of a querystring which, when accessed, will log a Click for the actual URL.


Implements search() and get_queryset() methods to handle database queries.


The model which should be searched by the DatabaseSearch.


Returns a QuerySet of all instances of model. This method should be overridden by subclasses to specify how the search should actually be implemented for the model.


Defines a generic interface for searches that require accessing a certain url to get search results.


The base URL which will be accessed to get the search results.


The url-encoded query string to be used for fetching search results from search_url. Must have one %s to contain the search argument.


The URL where the search gets its results. Composed from search_url and query_format_str.

parse_response(response, limit=None)

Handles the response from accessing url (with urllib2.urlopen()) and returns a list of up to limit results.


Makes a GET request and parses the results as JSON. The default behavior assumes that the response contains a list of results.


An example implementation of a JSONSearch.


Unquoted default arguments for the GoogleSearch.

Project Versions

Table Of Contents

Previous topic


Next topic


This Page