.. Revision: $Id: README 17 2007-01-31 07:13:08Z krys $

TurboLucene
===========

TurboLucene is a library that allows TurboGears_ applications to use PyLucene_
for full text searching.  It features a simple interface and takes care of all
the nasty threading issues that exist between PyLucene and CherryPy_ (which is
used by TurboGears).


.. _TurboGears: http://turbogears.org/
.. _PyLucene: http://pylucene.osafoundation.org/
.. _CherryPy: http://cherrypy.org


Requirements
------------

 * PyLucene 2.0.0 or better
 * TurboGears 1.0 or better

Thanks to setuptools, TurboGears and it's dependencies will be installed
automatically, if necessary.  However, PyLucene must be downloaded and
installed manually.

TurboLucene is not very demanding and may work with earlier versions of both
PyLucene and TurboGears, but other versions have not been tested.


Installation
------------

TurboLucene uses setuptools, so installation is as easy as::

  easy_install TurboLucene

or::

  python setup.py install

For more installation options, try::

  python setup.py --help


Manual Download
---------------

The latest version can always be downloaded at http://dev.krys.ca/turbolucene.


Usage
-----

Better documentation is to come, but in the mean time, please check out the
source code as it is well commented and the API is very simple.


Limitations
-----------

TurboLucene is still in early stages of development.  Currently it only
supports English stemming, etc.  It also will only create the index directory
in the current working directory and it's not configurable yet.  It has also
not been optimised, extensively tested, benchmarked or profiled for performance
or memory usage.  Finally, there are no test cases yet.

The plan is to eliminate all these limitations, eventually, but in it's current
state, it satisfies the author's needs.

Patches and suggestions are welcome! :-)


License
-------

TurboLucene is licensed under the MIT license.  See the LICENSE file for
details.


Contact
-------

TurboLucene's web site is

  http://dev.krys.ca/turbolucene

You can find more documentation there.  It is also where you can submit bugs.
The TurboLucene mailing list can be found at

  http://lists.krys.ca/mailman/listinfo/turbolucene

That is the place to ask any questions or make suggestions.  Patches, bug
reports, bug fixes and suggestions are all welcome! :-)


Author
======

The author of TurboLucene is Krys Wilken.  Feel free to contact him at krys AT
krys DOT ca.
