Lunr.py

A Python implementation of Lunr.js by Oliver Nightingale.

A bit like Solr, but much smaller and not as bright.

This Python version of Lunr.js aims to bring the simple and powerful full text search capabilities into Python guaranteeing results as close as the original implementation as possible.

• Documentation

What does this even do?

Lunr is a simple full text search solution for situations where deploying a full scale solution like Elasticsearch isn't possible, viable or you're simply prototyping.

Lunr parses a set of documents and creates an inverted index for quick full text searches.

The typical use case is to integrate Lunr in a web application, an example would be the MkDocs documentation library. In order to do this, you'd integrate Lunr.js in the Javascript code of your application, which will need to fetch and parse a JSON of your documents and create the index at startup of your application. Depending on the size of your document set this can take some time and potentially block the browser's main thread.

Lunr.py provides a backend solution, allowing you to parse the documents ahead of time and create a Lunr.js compatible index you can pass have the browser version read, minimizing start up time of your application.

Of course you could also use Lunr.py to power full text search in desktop applications or backend services to search on your documents mimicking Elasticsearch.

Installation

Simply pip install lunr for the english only, best compatibility with Lunr.js version.

An optional and experimental support for other languages via the Natural Language Toolkit stemmers is also available via pip install lunr[languages].

Supported languages are arabic, danish, dutch, english, finnish, french, german, hungarian, italian, norwegian, portuguese, romanian, russian, spanish and swedish.

Note the compatibility with Lunr.js is not guaranteed at the moment when using this experimental feature.

Current state

Each version of lunr.py targets a specific version of lunr.js and produces the same results as it both in Python 2.7 and 3 for non-trivial corpus of documents.

Lunr.py also serializes Index instances respecting the lunr-schema which are consumable by Lunr.js and viceversa.

The API is in alpha stage and likely to change.

Usage

You'll need a list of dicts representing the documents you want to search on. These documents must have a unique field which will serve as a reference and a series of fields you'd like to search on.

Lunr provides a convenience lunr function to quickly index this set of documents:

>>> from lunr import lunr
>>>
>>> documents = [{
...     'id': 'a',
...     'title': 'Mr. Green kills Colonel Mustard',
...     'body': 'Mr. Green killed Colonel Mustard in the study with the candlestick.',
... }, {
...     'id': 'b',
...     'title': 'Plumb waters plant',
...     'body': 'Professor Plumb has a green plant in his study',
... }]
>>> idx = lunr(
...     ref='id', fields=('title', 'body'), documents=documents
... )
>>> idx.search('kill')
[{'ref': 'a', 'score': 0.6931722372559913, 'match_data': <MatchData "kill">}]
>>> idx.search('study')
[{'ref': 'b', 'score': 0.23576799568081389, 'match_data': <MatchData "studi">}, {'ref': 'a', 'score': 0.2236629211724517, 'match_data': <MatchData "studi">}]

Please refer to the documentation for more usage examples.