README for the spigot Python module
===================================

This directory contains a native-code Python module, and a Python
wrapper on that, which between them provide a programmatic Python
interface to spigot's exact real computation system.

The system permits parsing expressions from strings in spigot's native
expression language, and also taking numbers as input from any of
Python's natively supported formats. Unlike spigot proper, expressions
can include variable names, which will be looked up in a dictionary
provided to the parse function, so that you can parametrise your
expression with variables you had lying around anyway without having
to mess about constructing expression strings out of them. Results can
be extracted in forms convenient to further processing, such as an
iterator returning continued fraction terms as Python long integers,
or convergents as pairs of long integers, or boolean comparison
functions.

A small test program is provided, and also a more interesting demo
program 'powbegin.py' which answers a more or less frivolous question
by using spigot's unlimited precision to implement a search strategy
far more efficient than the obvious one.

WARNING: This Python module is NOT FINISHED! I didn't spend a lot of
time on devising the API; I just threw together whatever seemed
simplest. It might very well get a redesign in the future, so beware
of writing any applications based on it.

On the other hand, if you do want to write applications based on this,
please get in touch and let me know what you do and don't like about
it - that will be useful if I ever do think about a redesign.

This system reuses the spigot source files, but is independent of the
main spigot autoconf build system. Use setup.py in this subdirectory
to build the extension in the standard Python manner.
