Changeset 57

Show
Ignore:
Timestamp:
11/05/07 14:00:13 (1 year ago)
Author:
amcgregor
Message:

Brought documentation into sync with Wiki.

Files:
1 modified

Legend:

Unmodified
Added
Removed

  • branches/2.1.1/documentation/guide.wiki

    r31 r57  
     1= Welcome to the TurboMail Project = 
     2 
     3{{{ 
     4#!html 
     5<div class="system-message"><strong>Website moved.</strong><pre>We have moved to <a href="http://www.python-turbomail.org/">http://www.python-turbomail.org/</a>. 
     6Please update your links as appropriate.</pre></div> 
     7}}} 
     8 
    19[[PageOutline(2-3, Table of Contents)]] 
    210 
    3 = The !TurboMail Guide = 
     11TurboMail is a TurboGears extension, meaning that it starts up and shuts down alongside any TurboGears applications you write, in the same way that visit tracking and identity do. TurboMail uses built-in Python modules for SMTP communication and MIME e-mail creation, but greatly simplifies these tasks by performing the grunt-work for you.  Additionally, TurboMail is multi-threaded, allowing for single or batch enqueueing and background delivery of mail. 
    412 
    5 !TurboMail is a !TurboGears extension, meaning that it starts up and shuts down alongside any !TurboGears applications you write, in the same way that visit tracking and identity do. !TurboMail uses built-in Python modules for SMTP communication and MIME e-mail creation, but greatly simplifies these tasks by performing the grunt-work for you. Additionally, !TurboMail is multi-threaded, allowing for single or batch enqueueing and background delivery of mail. 
     13== Quick Example == 
    614 
    7 == Compatibility == 
    8  
    9 !TurboMail is compatible with Python 2.4 and 2.5, and should be compatible with Python 2.3, although this is untested. 
    10  
    11 == Installation & Upgrade Instructions == 
    12  
    13 If you already have a copy of ''setup_tools'' installed, installation is as easy as running the following command: 
    14  
    15 {{{ 
    16 easy_install [-U] TurboMail 
    17 }}} 
    18  
    19 !TurboMail installs no external scripts.  (Only include `-U` if upgrading an existing installation.  If you do not have ''setup_tools'' installed... you haven't installed !TurboGears yet, and !TurboMail is a !TurboGears extension, and thus requires that it be present. 
    20  
    21 == Configuration == 
    22  
    23 Before you can use !TurboMail, you must enable a few options within your !TurboGears application's configuration files.  Some of these options make sense to have included in the development- or production-specific configurations, while others make sense in the global configuration.  All of these options can be placed in any of the three files. 
    24  
    25 === Basic Options === 
    26  
    27  * `mail.on` (Default: ''False'') Enable !TurboMail. '''Required.''' 
    28  * `mail.server` (Default: ''None'') SMTP server address.  '''Required.''' 
    29  * `mail.username` (Default: ''None'') 
    30  * `mail.password` (Default: ''None'') 
    31  
    32 Both a username and password are required to enable authentication—passwords can be blank strings. 
    33  
    34 === Advanced Options === 
    35  
    36  * `mail.debug` (Default: ''False'') Output all SMTP server communications. 
    37  * `mail.interval` (Default: ''10'') Polling delay between new thread creation, in seconds. 
    38  * `mail.threads` (Default: ''4'') Maximum number of concurrent threads. 
    39  * `mail.jobs` (Default: ''10'') Maximum number of job units per thread. 
    40  * `mail.timeout` (Default: ''60'') Maximum time a worker thread will wait for additional jobs, in seconds. 
    41  * `mail.tls` (Defalut: ''None'') Enable or disable TLS, None will attempt to auto-detect TLS. This will not always work. 
    42  * `mail.encoding` (Default: ''us-ascii'') Set the character set and encoding on the MIMEText parts of the message. Common character sets include: 
    43     * `us-ascii` -- Performs no encoding, but is 7bit only. 
    44     * `iso-8859-1` -- Uses quoted-printable encoding. 
    45     * `utf-8` -- Uses base64 encoding. 
    46     * `utf-8-qp` -- Configures utf-8 to use quoted-printable encoding.  (Note: this is not a real character set and can only be used with !TurboMail.  Note also that this setting reconfigures the global ''utf-8'' setting to use a different encoding and will effect other processes using this mechanism.) 
    47  * `mail.polling` (Default: ''False'') If enabled, configures the thread pool to poll every mail.interval seconds for new jobs. This may give performance benefits to the running application. The default behaviour is to create new threads as soon as work is enqueued, resulting in faster delivery, but greater initial load. 
    48  * `mail.testmode` (Default: ''False'') If enabled, configures TurboMail NOT to send any mail to the specified server. Enqueued mails will just sit in the queue. This is very useful for unit tests where no interaction with the environment should take place.  
    49  
    50 In debug mode, using a single thread with a maximum of one job can be advantageous. Having a single thread with a maximum of a single job limits !TurboMail to a single SMTP connection at a time and automatically disconnects after sending each message. 
    51  
    52 == Basic Usage == 
    53  
    54 To use !TurboMail in your !TurboGears application, after adding the appropriate configuration options to your application, use the following as a guide: 
     15It is very, very easy to use TurboMail inside your TurboGears application.  After configuring TurboMail (see the TurboMailGuide for details), the following will send mail: 
    5516 
    5617{{{ 
    5718#!python 
    58 # Import TurboMail. 
    5919import turbomail 
    6020 
    61 # Create a Message instance. 
     21# ... 
     22 
    6223message = turbomail.Message("from@example.com", "to@example.com", subject) 
    6324message.plain = "Hello world!" 
    6425 
    65 # Enqueue the message. 
    6626turbomail.enqueue(message) 
    6727}}} 
    6828 
    69 Your message will now have been enqueued. Depending on how you have configured !TurboMail, your message will either be delivered immediately (if a thread is idle), create a thread immediately, or delay up to `mail.interval` seconds before creating a thread. 
     29It's just that easy. 
    7030 
    71 == Advanced == 
     31== Using Trac == 
    7232 
    73 There are many additional options which are best described in the source or API reference guides.  The API reference guide can be generated using [http://epydoc.sourceforge.net/ Epydoc] and the included configuration file.  Use the following command to generate the documentation: 
     33Due to spam anonymous posting and ticket modification has been disabled.  Please log in using the `realuser` account using the password `nospammersplease`.  Sorry for the inconvenience. 
    7434 
    75 {{{ 
    76 epydoc --config=epydoc.cfg 
    77 }}} 
     35== What People are Saying == 
    7836 
    79 Documentation will be generated (along with a few harmless errors because !TurboMail is not running within !TurboGears) inside the documentation/api folder of the source tree.  No documentation will be installed if you use ``easy_install`` or a binary package—it is included with the source only. 
     37"I've used today TurboMail for the first time... It was quick to set up, and... it just works." 
    8038 
    81 == Reference == 
     39  — Nadav Samet 
    8240 
    83 === Message Class === 
     41== Who Uses TurboMail? == 
    8442 
    85 Simple e-mail message class. 
    86  
    87 Message provides a means to easily create e-mail messages to be sent through the Dispatch mechanism or by using a !MailPool. Message provides various helper functions to correctly format plain text, dual plain text and rich text MIME encoded messages, as well as handle embedded and external attachments. 
    88  
    89 All properties can be set from the constructor. 
    90  
    91 E-mail addresses can be represented as any of the following: 
    92  
    93  * A string. 
    94  * A 2-tuple of ("Full Name", "name@host.tld") 
    95  
    96 Encoding can be overridden on a per-message basis, but note that 'utf-8-qp' modifies the default 'utf-8' behaviour to output quoted-printable, and you will have to change it back yourself if you want base64 encoding. 
    97  
    98 ((The plain- and rich-text parts of the message may be defined as any callable which returns plain- or rich-text.  The callable is executed at the time the message is built - usually just prior to being delivered. -- Not true until next release.)) 
    99  
    100 ==== Methods ==== 
    101  
    102  * `attach(file, name=None)` -- Attach a given file (either on-disk by passing a path, or in-memory by passing a File descendant) to the message.  The `name` argument is required if passing an in-memory File descendant. 
    103  * `embed(file, name)` -- As per attach, but limited to image files for embedding in the rich-text (HTML) part of the message.  Name is the desired CID of the embedded image. 
    104  
    105 ==== Properties ==== 
    106  
    107  * `bcc` -- Blind carbon-copy address or addresses. 
    108  * `cc` -- Carbon-copy address or addresses. 
    109  * `date` -- The Date header. 
    110  * `disposition` -- Request disposition notification be sent to this address. 
    111  * `encoding` -- Content encoding specific to this message. 
    112  * `headers` -- Additional headers for this message (dict, list or tuple of tuples/lists) 
    113  * `organization` -- The descriptive Organization header. 
    114  * `plain` -- Plain text content.  Can be automatically generated. 
    115  * `priority` -- The X-Priority header, in the range of 1-5. 
    116  * `recipient` -- The To header, containing one or more addresses. 
    117  * `replyto` -- The X-Reply-To header, allowing you to request alternative return routing for replies. 
    118  * `rich` -- The rich-text part.  If this part is set the plain-text part will be automatically generated unless otherwise specified. 
    119  * `sender` -- The From header. 
    120  * `smtpfrom` -- The envelope address, if different from the sender. 
    121  * `subject` -- A textual description or summary of the content of the message. 
    122  
    123 ---- 
    124  
    125 This [http://purl.org/dc/dcmitype/Text work] is licensed under a [http://creativecommons.org/licenses/by-nd/2.5/ca/ Creative Commons Attribution-No Derivative Works 2.5 Canada License]. 
     43 * [http://www.oprius.com/ Oprius Software], an online hosted CRM and networking tool for marketing professionals. 
     44 * The Fedora Project hosted application [https://hosted.fedoraproject.org/projects/bodhi Bodhi], a modular web-system that facilitates the process of publishing updates for a Fedora-based software distribution—currently used to push out all package updates for Fedora 7.