roundup/scripts/roundup_mailgw.py

   1 # Copyright (c) 2001 Bizar Software Pty Ltd (http://www.bizarsoftware.com.au/)
   2 # This module is free software, and you may redistribute it and/or modify
   3 # under the same terms as Python, so long as this copyright message and
   4 # disclaimer are retained in their original form.
   5 #
   6 # IN NO EVENT SHALL BIZAR SOFTWARE PTY LTD BE LIABLE TO ANY PARTY FOR
   7 # DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING
   8 # OUT OF THE USE OF THIS CODE, EVEN IF THE AUTHOR HAS BEEN ADVISED OF THE
   9 # POSSIBILITY OF SUCH DAMAGE.
  10 #
  11 # BIZAR SOFTWARE PTY LTD SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING,
  12 # BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  13 # FOR A PARTICULAR PURPOSE.  THE CODE PROVIDED HEREUNDER IS ON AN "AS IS"
  14 # BASIS, AND THERE IS NO OBLIGATION WHATSOEVER TO PROVIDE MAINTENANCE,
  15 # SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  16 #
  17 # $Id: roundup_mailgw.py,v 1.25 2008-08-19 01:06:01 richard Exp $
  18
  19 """Command-line script stub that calls the roundup.mailgw.
  20 """
  21 __docformat__ = 'restructuredtext'
  22
  23 # python version check
  24 from roundup import version_check
  25 from roundup import __version__ as roundup_version
  26
  27 import sys, os, re, cStringIO, getopt, socket, netrc
  28
  29 from roundup import mailgw
  30 from roundup.i18n import _
  31
  32 def usage(args, message=None):
  33     if message is not None:
  34         print message
  35     print _(
  36 """Usage: %(program)s [-v] [-c class] [[-C class] -S field=value]* <instance home> [method]
  37
  38 Options:
  39  -v: print version and exit
  40  -c: default class of item to create (else the tracker's MAIL_DEFAULT_CLASS)
  41  -C / -S: see below
  42
  43 The roundup mail gateway may be called in one of four ways:
  44  . with an instance home as the only argument,
  45  . with both an instance home and a mail spool file,
  46  . with both an instance home and a POP/APOP server account, or
  47  . with both an instance home and a IMAP/IMAPS server account.
  48
  49 It also supports optional -C and -S arguments that allows you to set a
  50 fields for a class created by the roundup-mailgw. The default class if
  51 not specified is msg, but the other classes: issue, file, user can
  52 also be used. The -S or --set options uses the same
  53 property=value[;property=value] notation accepted by the command line
  54 roundup command or the commands that can be given on the Subject line
  55 of an email message.
  56
  57 It can let you set the type of the message on a per email address basis.
  58
  59 PIPE:
  60  In the first case, the mail gateway reads a single message from the
  61  standard input and submits the message to the roundup.mailgw module.
  62
  63 UNIX mailbox:
  64  In the second case, the gateway reads all messages from the mail spool
  65  file and submits each in turn to the roundup.mailgw module. The file is
  66  emptied once all messages have been successfully handled. The file is
  67  specified as:
  68    mailbox /path/to/mailbox
  69
  70 In all of the following the username and password can be stored in a
  71 ~/.netrc file. In this case only the server name need be specified on
  72 the command-line.
  73
  74 The username and/or password will be prompted for if not supplied on
  75 the command-line or in ~/.netrc.
  76
  77 POP:
  78  In the third case, the gateway reads all messages from the POP server
  79  specified and submits each in turn to the roundup.mailgw module. The
  80  server is specified as:
  81     pop username:password@server
  82  Alternatively, one can omit one or both of username and password:
  83     pop username@server
  84     pop server
  85  are both valid.
  86
  87 POPS:
  88  Connect to a POP server over ssl. This requires python 2.4 or later.
  89  This supports the same notation as POP.
  90
  91 APOP:
  92  Same as POP, but using Authenticated POP:
  93     apop username:password@server
  94
  95 IMAP:
  96  Connect to an IMAP server. This supports the same notation as that of
  97  POP mail.
  98     imap username:password@server
  99  It also allows you to specify a specific mailbox other than INBOX using
 100  this format:
 101     imap username:password@server mailbox
 102
 103 IMAPS:
 104  Connect to an IMAP server over ssl.
 105  This supports the same notation as IMAP.
 106     imaps username:password@server [mailbox]
 107
 108 """)%{'program': args[0]}
 109     return 1
 110
 111 def main(argv):
 112     '''Handle the arguments to the program and initialise environment.
 113     '''
 114     # take the argv array and parse it leaving the non-option
 115     # arguments in the args array.
 116     try:
 117         optionsList, args = getopt.getopt(argv[1:], 'vc:C:S:', ['set=',
 118             'class='])
 119     except getopt.GetoptError:
 120         # print help information and exit:
 121         usage(argv)
 122         sys.exit(2)
 123
 124     for (opt, arg) in optionsList:
 125         if opt == '-v':
 126             print '%s (python %s)'%(roundup_version, sys.version.split()[0])
 127             return
 128
 129     # figure the instance home
 130     if len(args) > 0:
 131         instance_home = args[0]
 132     else:
 133         instance_home = os.environ.get('ROUNDUP_INSTANCE', '')
 134     if not (instance_home and os.path.isdir(instance_home)):
 135         return usage(argv)
 136
 137     # get the instance
 138     import roundup.instance
 139     instance = roundup.instance.open(instance_home)
 140
 141     if hasattr(instance, 'MailGW'):
 142         handler = instance.MailGW(instance, optionsList)
 143     else:
 144         handler = mailgw.MailGW(instance, optionsList)
 145
 146     # if there's no more arguments, read a single message from stdin
 147     if len(args) == 1:
 148         return handler.do_pipe()
 149
 150     # otherwise, figure what sort of mail source to handle
 151     if len(args) < 3:
 152         return usage(argv, _('Error: not enough source specification information'))
 153     source, specification = args[1:3]
 154
 155     # time out net connections after a minute if we can
 156     if source not in ('mailbox', 'imaps'):
 157         if hasattr(socket, 'setdefaulttimeout'):
 158             socket.setdefaulttimeout(60)
 159
 160     if source == 'mailbox':
 161         return handler.do_mailbox(specification)
 162
 163     # the source will be a network server, so obtain the credentials to
 164     # use in connecting to the server
 165     try:
 166         # attempt to obtain credentials from a ~/.netrc file
 167         authenticator = netrc.netrc().authenticators(specification)
 168         username = authenticator[0]
 169         password = authenticator[2]
 170         server = specification
 171         # IOError if no ~/.netrc file, TypeError if the hostname
 172         # not found in the ~/.netrc file:
 173     except (IOError, TypeError):
 174         match = re.match(r'((?P<user>[^:]+)(:(?P<pass>.+))?@)?(?P<server>.+)',
 175                          specification)
 176         if match:
 177             username = match.group('user')
 178             password = match.group('pass')
 179             server = match.group('server')
 180         else:
 181             return usage(argv, _('Error: %s specification not valid') % source)
 182
 183     # now invoke the mailgw handler depending on the server handler requested
 184     if source.startswith('pop'):
 185         ssl = source.endswith('s')
 186         if ssl and sys.version_info<(2,4):
 187             return usage(argv, _('Error: a later version of python is required'))
 188         return handler.do_pop(server, username, password, ssl)
 189     elif source == 'apop':
 190         return handler.do_apop(server, username, password)
 191     elif source.startswith('imap'):
 192         ssl = source.endswith('s')
 193         mailbox = ''
 194         if len(args) > 3:
 195             mailbox = args[3]
 196         return handler.do_imap(server, username, password, mailbox, ssl)
 197
 198     return usage(argv, _('Error: The source must be either "mailbox",'
 199         ' "pop", "pops", "apop", "imap" or "imaps"'))
 200
 201 def run():
 202     sys.exit(main(sys.argv))
 203
 204 # call main
 205 if __name__ == '__main__':
 206     run()
 207
 208 # vim: set filetype=python ts=4 sw=4 et si