-------------------------------------------------------------------------------
 streamtuner-python overview
-------------------------------------------------------------------------------

Index

	0. About this document
	1. About streamtuner-python
	2. Implementation
	3. Usage
	4. Documentation map

0. About this document

	$Id: README,v 1.5 2004/01/31 17:08:21 jylefort Exp $

	Copyright (c) 2003, 2004 Jean-Yves Lefort.

	This document is part of streamtuner-python. It may be
	distributed under the same terms as streamtuner-python.

1. About streamtuner-python

	streamtuner-python is a streamtuner plugin providing an
	embedded Python interpreter.

	streamtuner is a stream directory browser, available at
	http://www.nongnu.org/streamtuner/.

	Python is an interpreted, interactive, object-oriented
	programming language, available at http://www.python.org/.

	The plugin allows to write a streamtuner handler in Python.
	Scripts will be loaded from LIBDIR/scripts and
	~/.streamtuner/streamtuner-python/scripts. They must have the
	.py extension.

	An example script, google-stations.py, is shipped with the plugin.
	It handles http://directory.google.com/Top/Arts/Radio/Internet/
	and http://directory.google.com/Top/Arts/Music/Sound_Files/
	MP3/Streaming/Stations/.

2. Implementation

	The C core of the plugin provides a flat Python API closely
	matching the C plugin interface of streamtuner. The Python
	core is used to wrap an object-oriented interface over the
	flat API.

	The subset of the GLib library required for interacting with
	streamtuner is also mapped.

	Despite its low version number, the plugin is already fairly
	stable. However, beware: the functions won't check the type of
	complex objects; hence, it is possible to crash streamtuner
	from a Python script (for instance ST.Handlers.add() might
	crash if you don't pass it a STHandler instance).

3. Usage

	The API is left undocumented for now; you can base your work
	on the provided example script, google-stations.py.

	Note that the plugin has only been tested with the 2.3 branch
	of Python. It might not work or even build with previous
	versions of Python.
	
4. Documentation map

	The following documents are included in the distribution:

		COPYING		licensing information

		README		this document

		INSTALL		installation instructions

		NEWS		reverse chronology of changes,
				manually edited

		ChangeLog	reverse chronology of changes,
				automatically generated from CVS
				commit messages

		TODO		to-do list, mostly useful for developers
