Source Code for Module ProcImap.Utils.CLI

  1  ############################################################################ 
  2  #    Copyright (C) 2008 by Michael Goerz                                   # 
  3  #    http://www.physik.fu-berlin.de/~goerz                                 # 
  4  #                                                                          # 
  5  #    This program is free software; you can redistribute it and#or modify  # 
  6  #    it under the terms of the GNU General Public License as published by  # 
  7  #    the Free Software Foundation; either version 3 of the License, or     # 
  8  #    (at your option) any later version.                                   # 
  9  #                                                                          # 
 10  #    This program is distributed in the hope that it will be useful,       # 
 11  #    but WITHOUT ANY WARRANTY; without even the implied warranty of        # 
 12  #    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         # 
 13  #    GNU General Public License for more details.                          # 
 14  #                                                                          # 
 15  #    You should have received a copy of the GNU General Public License     # 
 16  #    along with this program; if not, write to the                         # 
 17  #    Free Software Foundation, Inc.,                                       # 
 18  #    59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             # 
 19  ############################################################################ 
 20   
 21  """ This package contains a specialized OptionParser for use with ProcImap. 
 22   
 23      All CLI tools developed from the ProcImap package should uniformly  
 24      provide an option '-p' / '--profile' to read a MailboxFactory profile 
 25   
 26      Optionally, the filename for the profile is read from the 
 27      PROC_IMAP_PROFILE environment variable. 
 28   
 29      This allows the user to keep account information (passwords) in one 
 30      place for a variety of tools. 
 31  """ 
 32   
 33  from ProcImap.Utils.MailboxFactory import MailboxFactory 
 34   
 35  from optparse import OptionParser, IndentedHelpFormatter 
 36  import os 
 37   
 38   
 39 -class ProcImapOptParser(OptionParser): 
 40      """ A special OptionParser for ProcImap. This takes the exact same 
 41          arguments as optparse.OptionParser. 
 42   
 43          However, there is a predefined option '-p' or '--profile'. If 
 44          not given explicitely, this option takes the value of the 
 45          environment variable PROC_IMAP_PROFILE. If the option is not 
 46          given, neither explicitely nor implicitely through the envirnoment 
 47          variable, ProcImapOptParser will shoot down the program it's 
 48          running in with an error message. 
 49   
 50          You can use ProcImapOptParser in this manner: 
 51   
 52          >>> opt = ProcImapOptParser() 
 53          >>> (options, args) = opt.parse_args(args=sys.argv) 
 54   
 55          if sys.argv included e.g. '-p mailboxes.cfg', options.profile will 
 56          NOT be the string 'mailboxes.cfg', but instead will be an instance  
 57          of MailboxFactory, generated from the file mailboxes.cfg. 
 58   
 59          ProcImapOptParser also has a modified default formatter that  
 60          allows explicit linebreaks (for paragraphs) in help-generating 
 61          arguments like 'epilogue'. 
 62      """ 
 63 -    def __init__(self, **args): 
 64          """ See documentation of optparse.OptionParser for arguments. """ 
 65          class MyIndentedHelpFormatter(IndentedHelpFormatter): 
 66              """ Slightly modified formatter for help output:  
 67                  allow paragraphs  
 68              """ 
 69              def format_paragraphs(self, text): 
 70                  """ wrap text per paragraph """ 
 71                  result = "" 
 72                  for paragraph in text.split("\n"): 
 73                      result += self._format_text(paragraph) + "\n" 
 74                  return result 
 75              def format_description(self, description): 
 76                  """ format description, honoring paragraphs """ 
 77                  if description: 
 78                      return self.format_paragraphs(description) + "\n" 
 79                  else: 
 80                      return "" 
 81              def format_epilog(self, epilog): 
 82                  """ format epilog, honoring paragraphs """ 
 83                  if epilog: 
 84                      return "\n" + self.format_paragraphs(epilog) + "\n" 
 85                  else: 
 86                      return "" 
 87          OptionParser.__init__(self, **args) 
 88          self.add_option("-p", "--profile", dest="profile", 
 89                          help="Use FILE as the MailboxFactory config file " 
 90                          "defining all the mailboxes for this program.",  
 91                          metavar="FILE") 
 92          if not args.has_key('formatter'): 
 93              self.formatter = MyIndentedHelpFormatter() 
 94          if os.environ.has_key('PROC_IMAP_PROFILE'): 
 95              self.set_defaults(profile=os.environ['PROC_IMAP_PROFILE']) 
 96   
 97 -    def parse_args(self, args=None, values=None): 
 98          """ 
 99          parse_args(args : [string] = sys.argv[1:], 
100                     values : Values = None) 
101          -> (values : Values, args : [string]) 
102   
103          Parse the command-line options found in 'args' (default: 
104          sys.argv[1:]).  Any errors result in a call to 'error()', which 
105          by default prints the usage message to stderr and calls 
106          sys.exit() with an error message.  On success returns a pair 
107          (values, args) where 'values' is an Values instance (with all 
108          your option values) and 'args' is the list of arguments left 
109          over after parsing options. 
110          """ 
111          result = OptionParser.parse_args(self, args, values) 
112          if self.values.profile is None: 
113              self.exit(status=1, msg="You did not provide a profile, and the " 
114                        "PROC_IMAP_PROFILE environment variable is not set.\n") 
115          else: 
116              try: 
117                  self.values.profile = MailboxFactory(self.values.profile) 
118              except: 
119                  raise 
120          return result 
121