___________
Spyce mail module

1. Foreword

  Sorry for you people that do not use Python 2.2, but this module is not for
  you !
	
  The mail module make extensive use of the 'email' module, which appeared
  only with the 2.2 release of Python. If you don't have it, then the mail
  module won't work at all.
	
2. Content

	1.  Foreword
	2.  Content
	3.  Introduction
	4.  Module content
	4.1     setServer
	4.2     mail
	5.  More informations
	
3. Introduction

  The mail module is a spyce module which allows to send a mail from a spyce
  script. It's usage is simple due to it's restricted number of functions, but
  it's capabilities are very impressive:
	
		- Named recipients;
		- Cc and Bcc;
		- Multipart MIME message for attachment;
		- Quoted-printable and base64 encoding;
		- Sending of text or files.
		
	All this is performed with two function.
	
4. Module content

	The mail module provides the following functions:
	
 4.1 setServer
		
	Declaration:
		setServer(host, [port=25], [user], [password])
	
	Parameters:
		host:     The smtp server to which you will connect to send your mail.
		
		port:     The tcp/ip port to use for this connection.
		
		user:     For smtp server with authentication, those parameters allows you 
		password: to identify yourself to the server.

 4.2 send
		
	Declaration:
		send(from_field, to_field, subject_field, content, [cc_field=None], [bcc_field=None])
		
	Parameters:
		from_field:    The people who this mail comes from (see syntax below).
		to_field:      The people who should receive this mail (see syntax below).
		subject_field: The subject, a simple string.
		content:       The content (see syntax below).
		cc_field:      The people who should receive a copy of this mail.
		bcc_field:     The people who should receive a copy of this mail but without 
			           the others knowing it (see syntax below).

	Syntax:
		The from_field, to_field, cc_field and bcc_field all have the same syntax.
		They can be:
			- a simple string containing the address. 
			  eg: 'rien@yeepa.org'

			- a string containing a RFC822 mail address, that is containing the name
			  and the mailbox. 
			  eg: '"Adrien Plisson" <rien@yeepa.org>'

			- a tuple containing the name and the mailbox. 
			  eg: ('Adrien Plisson', 'rien@yeepa.org')

			- a list where each element is of one of the three syntax given before.
			  eg: [('Adrien Plisson', 'rien@yeepa.org'), '"Rimon Barr" <barr@cs.cornell.edu>', 
			       'grisha@modpython.org']

    you don't have to worry about the encoding of the subject field, the mail
    function will encode it automatically in quoted-printable if necessary.

		The content can be expressed in these ways:
			- a string (what more simple ?).
			  eg: "this is the content of the mail"

			- an open file which is simply dumped onto the mail.
			  eg: data = open('/usr/bin/spyce/spyce.py', 'r')
			      mail.send('rien@yeepa.org', 'barr@cs.cornell.edu', 'spyce', data)

			- a dictionnary containing the folowing keys: 
				- content, 
				- type, 
				- encoding (optional),
				- additional_fields (optional)
        Content can be aany of the possible form for content. Type is the MIME
        type, you can precise here some arguments, i.e. the name of a file.
        Encoding is one of the encoding specified in the MIME definition, that
        is 'quoted-printable', 'base64', '7bit' or '8bit'. Additional_fields
        allows you to add some more fields in the header of the current
        message part.
			  eg: { 'content': 'this is the content',
				    'type': 'text/plain',
				    'encoding': 'quoted-printable',
				    'additional_fields': {'X-Mailer': 'Spyce mail module (the power of mail in one function)' } }
				
			- a list where each element is of one of the possible form for content (string, file, dict or list)
			  eg: ["this is the content of spyce",
			       {'content': data,
				    'type': 'application/octet-stream',
				    'encoding': 'base64',
				    'additional_fields':  {'Content-Disposition': 'attachment; filename="spyce.py"'} }
			      ]

    Please note that the content syntax definition is redundant: each content
    can contain content. This way you can build multipart MIME mails the way
    you want. You can also provide some extra headers.
		
    When you specify an encoding, the mail function will encode the content
    according to the specified algorithm. Don't bother encoding it yourself...

5. More informations

	RFC 2821:   Simple Mail Transfert Protocol
	RFC 2822:   Internet Message Format
	RFC 2045:   MIME Part One: Format of Internet Message Bodies
	RFC 2046:   MIME Part Two: Media Types
	RFC 2047:   MIME Part Three: Message Header Extensions for Non-ASCII Text