h1. Flying Sphinx for Python

Nowhere near complete at the time of writing, but this will be a python client for "flying-sphinx.com":https://flying-sphinx.com (initially just as a Heroku add-on, but other platforms will be added too).

h2. 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.

h2. 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.

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:

<pre><code>import flyingsphinx

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

If you have additional files used by certain settings (such as wordforms and stopwords), then these should be sent through as well:

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

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.

<pre><code>flyingsphinx.index().run()</code></pre>

When you only want to process certain indices, pass their names in to the @run@ method as an array:

<pre><code>flyingsphinx.index().run(['article', 'user'])</code></pre>

If you wish to view the output of the most recently run indexing request, here's the relevant code:

<pre><code>flyingsphinx.index().last()</code></pre>

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

<pre><code>flyingsphinx.sphinx().start() # start the remote Sphinx daemon
flyingsphinx.sphinx().stop()  # stop the remote Sphinx daemon</code></pre>

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:

<pre><code>import flyingsphinx

flyingsphinx.info() # Hash/Dictionary with configuration</code></pre>

h2. 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.

h2. 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.

h2. Licence

Copyright &copy; 2012 Pat Allan, released under an MIT licence.
