# Common usage:
	from pygale import *
	# (or)
	from pygale import pygale, gale_env
	import sys

	pygale.init()
	sys.exitfunc = pygale.shutdown

	# do stuff

---------------------------------------------------------------------------
# Methods in pygale:

init()
	Initialize the pygale library.  This function should be called before
	any other functions in pygale.

shutdown()
	Shut down the pygale library before exiting Python.  If you don't call
	this function, nothing will go horribly wrong except that you might
	get a lot of exceptions printed to your terminal on program exit.
	This function cleans up some of the memory structures used in pygale
	because the Python builtin garbage collector collects them in the
	wrong order.  Tip: try setting sys.exitfunc to pygale.shutdown.

set_error_handler(callback(msg))
set_update_handler(callback(msg))
	These two functions take a callback argument, which will be called
	with a single string argument on error or status update, respectively.

call_error_handler(msg)
call_update_handler(msg)
	These functions call the appropriate handler with the message
	argument (which should be coercable to string).

# Functions related to gale locations:

lookup_location(location_string, callback=None)
	Look up a NWO location and find out what keys are to be used to
	encrypt to the location.  Return a tuple of (new_loc,
	list_of_key_names).  The new location is the location to be used
	to send to this location (it may not be the same as the original
	location because of symlink locations).  The list of key names is a
	list of strings naming keys to be used to encrypt to this location.
	If it contains the empty string (aka a null key), no encryption
	should be done.  If the list of keynames is None, then the lookup
	failed and this is not a valid location.

	If callback is None, this function blocks until it can return an
	answer.  If callback is a function, lookup_location returns
	immediately and the callback will be called with two arguments: the
	new location, and the list of key names.

lookup_all_locations(list_of_locations, callback([(newloc, keylist)])=None)
	Call lookup_location once for each location in the list.  Return 
	a list of tuples, where each tuple is a 2-tuple containing the
	return values from lookup_location.  If callback is None, block and
	return the value when computed.  Otherwise, return immediately and
	call the callback with the single argument of a list of tuples.
	This function call with first try to find keys in the disk cache.
	If that fails, it will try AKD.

expand_aliases(short_loc)
	This function canonicalizes abbreviated location strings into fully
	qualified locations.  If the location does not include a domain,
	append '@' and the default domain.  Processing of filesystem
	aliases (broken symlinks) should happen here, although it's not
	implemented yet. 

# General utility functions:

gale_user()
	Return the Gale ID of the current user.  Uses the variables GALE_USER
	and GALE_DOMAIN.

gale_domain()
	Return the Gale domain (basically the variable GALE_DOMAIN, or a
	default value if not set---that is an error).

# Key management functions

export_pubkey(gale_id, callback=None)
	Return a string representing the complete public key corresponding
	to this Gale ID.  Useful for implementing automatic key
	distribution (AKD) to send out a public key when it is
	requested.  If callback is None, this function blocks until it can
	return the requested data.  Otherwise, it returns immediately and
	calls the callback with the requested data as a single argument.

# Presence notifications:

notify_in(presence, gale_client, gale_id=None, fullname=None, version=None,
	instance=None)
notify_out(presence, gale_client, gale_id=None, fullname=None, version=None,
	instance=None)
	Using gale_client as a send-capable server connection, notify the
	server on login or when this client exits (also known as a will).
	Gale_id is the userid of the person logging in or out (defaults
	to gale_user()). Fullname (if not None) is used to set the
	message/sender of the puff.  Presence is the presence string sent
	along with the notification (e.g., "in/present").  Version, if
	set, is the id/class of the client being used, and instance is
	the id/instance.  If version or instance is None, they are set
	automatically from PyGale.  Neither of these two operations
	blocks.

------------------------------------------------------------------------------

# The class pygale.GaleClient encapsulations information about a connection
# to a gale server.  It supports the following methods:

GaleClient.GaleClient(hostname=None, retry=1)
	Construct a GaleClient instance.  If the optional hostname argument
	is passed, use it as the server:port to connect to, otherwise the
	host(s) to connect to will be gleaned from the info in pygale.conf
	(accessible via the gale_env interface).

	If retry is true, automatically retry connections to the server
	when they are disconnected.

GaleClient.set_onconnect(callback(hostname))
	Set up a callback with this GaleClient, which is to be called on
	successful connection to a server.  The callback will be called with a
	string denoting the host that made the successful connection.

	If retry is set to true, this callback will also be called when a
	server connection is reestablished after a failure.

	The callback is only called if the connection is successful.  If the
	server connection is not successful, the callback will never be
	called.  Pass a callback to connect() instead if you want to be
	notified on connection failure.  On successful connection, this
	callback will be called after connect's callback.

	The callback should perform the work that is necessary whenever
	a new connection to the server is made, such as setting up the
	subscriptions and registering a puff callback.

GaleClient.set_ondisconnect(callback())
	Set up a callback with this GaleClient that will be called when the
	server connection fails.  If retry is true, this callback will be
	called prior to beginning the retry-connection process.

GaleClient.connect(callback(hostname)=None)
	Makes a connection to the gale server(s).  If a connection is made
	successfully, then the return value is the host:port of the
	connected server.  If the connection fails, None is returned.
	
	If a callback function is passed to connect(), the callback
	function will be called with host:port or None once the connection
	is complete.  If the callback function is not given, connect() will
	block until a connection is made (or fails), and return host:port
	or None.

GaleClient.sub_to([list_of_locations], callback(b,g)=None)
	Subscribe to the desired subscription, which is a list of string
	locations.  Locations will be looked up using lookup_all_locations.
	The return value is a two-tuple.  The first element is a list of
	invalid locations in the subscription; this will be a subset of the
	locations passed to sub_to.  The second element is a list of good
	locations which have been sucessfully subscribed to.

	If the callback is not None, this function returns immediately and
	calls the callback with two arguments (badlocs and goodlocs) when
	subscription has been completed.

GaleClient.socket()
	Returns the socket object used to connect to the server.  Useful for
	passing to select().

GaleClient.transmit_puff(p, will=0)
	For an object p of type pygale.Puff, transmit p to the server.
	If will is true, this puff will be transmitted as a "will".

GaleClient.set_puff_callback(callback(puff))
GaleClient.set_verify_callback(callback(puff))
	These functions register puff callbacks on this connection.  If the
	verify callback is set, then when a puff arrives, the puff callback
	will be called with it, and verification will take place
	asynchronously.  The verify callback will be called with the verified
	puff when it has been completely verified.

	If the verify callback is not set, but the puff callback is set,
	the puff callback is called with the verified puff, upon
	completion of the verification process.

GaleClient.next()
	Read from the server forever, calling the puff callback whenever
	a puff arrives.  See also next_puffs() and set_puff_callback().
	
GaleClient.next_puffs()
	Return a list of puffs read from the server (possibly empty).  This
	call does not block.  See also the callback interface
	(set_puff_callback and set_verify_callback).

------------------------------------------------------------------------------

The Puff class encapsulates information about a single puff.  It is used
both for sending and receiving puffs.  It supports the following methods:

Puff.set_loc(location_list)
Puff.get_loc()
	Set or get the puff location.  The location_list is single string
	containing a space-separated list of locations.

Puff.get_signer()
	Get the signer of the puff.  The return value is None if a verification
	operation is in progress (see GaleClient.set_verify_callback), a
	string representing the signer's id (e.g.  "tlau@cs.washington.edu")
	if the puff was signed, the string "*unsigned*" if the puff was not
	signed, or the string "*unverified*" if it was signed but the
	signature could not be verified.

Puff.get_recipients()
	Get the message recipients of a puff, if it was encrypted.  This
	function returns a list of Gale IDs the puff was encrypted to
	(which could possibly be the empty list, if the puff was not
	encrypted).

Puff.get_text(fragname)
Puff.get_binary(fragname)
Puff.get_time(fragname)
Puff.get_int(fragname)
	Returns a list of fragments of the specified fragment type matching
	the fragname.

Puff.get_text_first(fragname, default=None)
Puff.get_binary_first(fragname, default=None)
Puff.get_time_first(fragname, default=None)
Puff.get_int_first(fragname, default=None)
	Get the value of the first puff fragment of the specified type
	matching the name fragname.  If the puff does not have such a
	fragment, return the default.

Puff.set_text(name, val)
Puff.set_time(name, val)
Puff.set_int(name, val)
Puff.set_binary(name, val)
	Set the value of a text, time, integer, or binary fragment in the puff.

Puff.sign_message(signer)
	Sign the puff as the given signer.  Return a new, signed, puff if
	successful, or return None if the sign operation failed.

Puff.encrypt_message(recipient_list, callback=None)
	Encrypt the puff using the list of gale_ids in recipient_list.  On
	completion, callback will be called with a new, encrypted, puff, or
	with None if the encryption failed.  If callback is None, this
	operation will block until the encryption is completed and return
	either the encrypted puff or None.

------------------------------------------------------------------------------

The asynchronous event loop engine resides in module pygale.engine.  It
defines three types of engines: a Select engine that uses multiplexed
select(), a TkEngine using the Tcl event loop, and a GtkEngine using the
Gtk event loop.

All engines support the following interface to manage callbacks associated
with each engine:

engine.add_callback(handle, callback())
engine.add_write_callback(handle, callback())
	Add a read or write callback (respectively) to the engine, using the
	specified handle.  The handle is a Python object with a fileno()
	method which is used to poll for read/write readiness.  Examples of
	supported objects are socket objects and file objects.

engine.del_callback(handle)
engine.del_write_callback(handle)
	Remove the callback associated with the specified handle.

engine.add_timeout(millisecs, callback())
	Register a timeout callback to be called after a millisecs delay (in
	milliseconds).  Returns a handle that can be used to cancel the
	timeout.
engine.del_timeout(handle)
	Handle must have been returned by engine.add_timeout().  Cancels the
	associated callback.

engine.process(timeout=None)
	In the case of the Tk and Gtk engines, this function is a no-op.

	For the Select engine, this function calls select().  If the timeout
	value is None, then select will block until one of the registered file
	descriptors is ready or until the next scheduled timeout occurs.  The
	timeout value can be set to zero, in which case this function will
	return immediately (polling).

	When a registered file descriptor turns up ready for reading or
	writing, its associated callback is called with no arguments.
