Flying Sphinx for Python

This is a python client for flying-sphinx.com (initially just as a Heroku add-on, but other platforms will be added too). Consider it an alpha at the moment – the functionality’s there, things work, but you may need to read the source a little. Will be improving documentation as soon as I can!

Installation

You can obtain the flyingsphinx package through easy_install or pip. Currently it’s written with just Heroku in mind, though with a slightly more manual approach, you can use the library anywhere (see below).

Still using Heroku’s legacy shared database? Then this library won’t work, as those databases don’t allow external ingress. It’s technically possible to work around that limitation, but given most/all apps are now migrated, I won’t be supporting any such approach.

Usage

First thing to note is that the default credentials are sourced from the environment (FLYING_SPHINX_IDENTIFIER and FLYING_SPHINX_API_KEY). On Heroku, these are provided automatically with the add-on, so you shouldn’t need to tweak anything. Elsewhere you probably will though.

Also: every command-line call specified can be (and usually should be) called within the context of Heroku. For example, flying-sphinx index becomes heroku run flying-sphinx index.

Configuration

When you’re getting started, you’ll need to make sure you’ve got your Sphinx configuration loaded on the Flying Sphinx servers. This can be done like so:

$ flying-sphinx configure /path/to/sphinx.conf

However, if you want to upload a dynamically generated configuration, or you have associated files for stopwords, exceptions or wordforms, then you’ll need to use this library via some Python code:

import flyingsphinx

flyingsphinx.configuration().upload('raw sphinx configuration')
# or
flyingsphinx.configuration().upload_from_file('/path/to/file.conf')

flyingsphinx.configuration().upload_settings('wordforms', 'wordforms.txt', 'contents of file')
# or
flyingsphinx.configuration().upload_settings_from_file('wordforms', '/path/to/wordforms.txt')

Processing Indices

The next step is to have Sphinx index all of your data. This will require Flying Sphinx to talk directly to your database – so please ensure the database credentials in your configuration are correct.

$ flying-sphinx index

When you only want to process certain indices, provide them as additional arguments from the command line:

$ flying-sphinx index article user

Controlling the Daemon

And – provided the indexes were processed without any issues, you can then get the daemon running:

$ flying-sphinx start
$ flying-sphinx stop

Convenience Commands

There’s two other useful commands: restart, which stops Sphinx and starts it up again, and rebuild, which stops Sphinx, processes the indices, then starts it up again. The latter is particularly useful when you’re changing your Sphinx configuration structure.

$ flying-sphinx restart
$ flying-sphinx rebuild

All of these commands can be run through via Heroku’s command line tool:

heroku run flying-sphinx index

And they can also be called through Heroku’s scheduler – and given regular indexing is important, you’ll probably want to add flyingsphinx index as a regular job there.

Searching is dependant on whichever Sphinx client library you’re using – but the server and port are available on Heroku via environment variables: FLYING_SPHINX_HOST and FLYING_SPHINX_PORT. You can also get this information from the Flying Sphinx API as well from within Python:

import flyingsphinx

flyingsphinx.info() # Hash/Dictionary with configuration

Compatibility and Limitations

This library is built for Python 2.7, as that’s what Heroku uses. I will happily accept patches for Python 3, but not sure there’s any point supporting 2.6 or older.

Contributing

Patches are indeed welcome (especially given Python is not a language I’m familiar with at the moment). flying-sphinx.com API documentation will be provided at some point in the future, but generally keep in mind the following:

• The environment is managed via pip/virtualenv. To install requirements via pip, run the following command: pip install -r requirements.txt --use-mirrors.
• I use soft indentation set to two spaces – please follow that convention in your patches.
• Write tests using nose and fudge. They can be run like so: nosetests spec/**/*.py
• Keep your commits in a separate branch.
• Don’t mess around with the version number in your branch – this keeps merges easier for me to manage.

Licence

Copyright © 2012 Pat Allan, released under an MIT licence.