Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 1 | """A powerful, extensible, and easy-to-use option parser. |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 2 | |
| 3 | By Greg Ward <gward@python.net> |
| 4 | |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 5 | Originally distributed as Optik. |
Greg Ward | 2492fcf | 2003-04-21 02:40:34 +0000 | [diff] [blame] | 6 | |
| 7 | For support, use the optik-users@lists.sourceforge.net mailing list |
| 8 | (http://lists.sourceforge.net/lists/listinfo/optik-users). |
Georg Brandl | f3532df | 2009-04-27 16:41:41 +0000 | [diff] [blame] | 9 | |
| 10 | Simple usage example: |
| 11 | |
| 12 | from optparse import OptionParser |
| 13 | |
| 14 | parser = OptionParser() |
| 15 | parser.add_option("-f", "--file", dest="filename", |
| 16 | help="write report to FILE", metavar="FILE") |
| 17 | parser.add_option("-q", "--quiet", |
| 18 | action="store_false", dest="verbose", default=True, |
| 19 | help="don't print status messages to stdout") |
| 20 | |
| 21 | (options, args) = parser.parse_args() |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 22 | """ |
| 23 | |
Thomas Wouters | 0e3f591 | 2006-08-11 14:57:12 +0000 | [diff] [blame] | 24 | __version__ = "1.5.3" |
Greg Ward | 2492fcf | 2003-04-21 02:40:34 +0000 | [diff] [blame] | 25 | |
Greg Ward | 4656ed4 | 2003-05-08 01:38:52 +0000 | [diff] [blame] | 26 | __all__ = ['Option', |
Benjamin Peterson | d23f822 | 2009-04-05 19:13:16 +0000 | [diff] [blame] | 27 | 'make_option', |
Greg Ward | 4656ed4 | 2003-05-08 01:38:52 +0000 | [diff] [blame] | 28 | 'SUPPRESS_HELP', |
| 29 | 'SUPPRESS_USAGE', |
Greg Ward | 4656ed4 | 2003-05-08 01:38:52 +0000 | [diff] [blame] | 30 | 'Values', |
| 31 | 'OptionContainer', |
| 32 | 'OptionGroup', |
| 33 | 'OptionParser', |
| 34 | 'HelpFormatter', |
| 35 | 'IndentedHelpFormatter', |
| 36 | 'TitledHelpFormatter', |
| 37 | 'OptParseError', |
| 38 | 'OptionError', |
| 39 | 'OptionConflictError', |
| 40 | 'OptionValueError', |
| 41 | 'BadOptionError'] |
Greg Ward | 2492fcf | 2003-04-21 02:40:34 +0000 | [diff] [blame] | 42 | |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 43 | __copyright__ = """ |
Thomas Wouters | 477c8d5 | 2006-05-27 19:21:47 +0000 | [diff] [blame] | 44 | Copyright (c) 2001-2006 Gregory P. Ward. All rights reserved. |
| 45 | Copyright (c) 2002-2006 Python Software Foundation. All rights reserved. |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 46 | |
| 47 | Redistribution and use in source and binary forms, with or without |
| 48 | modification, are permitted provided that the following conditions are |
| 49 | met: |
| 50 | |
| 51 | * Redistributions of source code must retain the above copyright |
| 52 | notice, this list of conditions and the following disclaimer. |
| 53 | |
| 54 | * Redistributions in binary form must reproduce the above copyright |
| 55 | notice, this list of conditions and the following disclaimer in the |
| 56 | documentation and/or other materials provided with the distribution. |
| 57 | |
| 58 | * Neither the name of the author nor the names of its |
| 59 | contributors may be used to endorse or promote products derived from |
| 60 | this software without specific prior written permission. |
| 61 | |
| 62 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS |
| 63 | IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED |
| 64 | TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A |
| 65 | PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR |
| 66 | CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, |
| 67 | EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, |
| 68 | PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR |
| 69 | PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF |
| 70 | LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING |
| 71 | NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS |
| 72 | SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| 73 | """ |
| 74 | |
| 75 | import sys, os |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 76 | import textwrap |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 77 | |
| 78 | def _repr(self): |
| 79 | return "<%s at 0x%x: %s>" % (self.__class__.__name__, id(self), self) |
| 80 | |
| 81 | |
| 82 | # This file was generated from: |
Thomas Wouters | 0e3f591 | 2006-08-11 14:57:12 +0000 | [diff] [blame] | 83 | # Id: option_parser.py 527 2006-07-23 15:21:30Z greg |
| 84 | # Id: option.py 522 2006-06-11 16:22:03Z gward |
| 85 | # Id: help.py 527 2006-07-23 15:21:30Z greg |
Thomas Wouters | 477c8d5 | 2006-05-27 19:21:47 +0000 | [diff] [blame] | 86 | # Id: errors.py 509 2006-04-20 00:58:24Z gward |
| 87 | |
| 88 | try: |
| 89 | from gettext import gettext |
| 90 | except ImportError: |
| 91 | def gettext(message): |
| 92 | return message |
| 93 | _ = gettext |
| 94 | |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 95 | |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 96 | class OptParseError (Exception): |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 97 | def __init__(self, msg): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 98 | self.msg = msg |
| 99 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 100 | def __str__(self): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 101 | return self.msg |
| 102 | |
Greg Ward | 2492fcf | 2003-04-21 02:40:34 +0000 | [diff] [blame] | 103 | |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 104 | class OptionError (OptParseError): |
| 105 | """ |
| 106 | Raised if an Option instance is created with invalid or |
| 107 | inconsistent arguments. |
| 108 | """ |
| 109 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 110 | def __init__(self, msg, option): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 111 | self.msg = msg |
| 112 | self.option_id = str(option) |
| 113 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 114 | def __str__(self): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 115 | if self.option_id: |
| 116 | return "option %s: %s" % (self.option_id, self.msg) |
| 117 | else: |
| 118 | return self.msg |
| 119 | |
| 120 | class OptionConflictError (OptionError): |
| 121 | """ |
| 122 | Raised if conflicting options are added to an OptionParser. |
| 123 | """ |
| 124 | |
| 125 | class OptionValueError (OptParseError): |
| 126 | """ |
| 127 | Raised if an invalid option value is encountered on the command |
| 128 | line. |
| 129 | """ |
| 130 | |
| 131 | class BadOptionError (OptParseError): |
| 132 | """ |
Thomas Wouters | 477c8d5 | 2006-05-27 19:21:47 +0000 | [diff] [blame] | 133 | Raised if an invalid option is seen on the command line. |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 134 | """ |
Thomas Wouters | 477c8d5 | 2006-05-27 19:21:47 +0000 | [diff] [blame] | 135 | def __init__(self, opt_str): |
| 136 | self.opt_str = opt_str |
| 137 | |
| 138 | def __str__(self): |
| 139 | return _("no such option: %s") % self.opt_str |
| 140 | |
| 141 | class AmbiguousOptionError (BadOptionError): |
| 142 | """ |
| 143 | Raised if an ambiguous option is seen on the command line. |
| 144 | """ |
| 145 | def __init__(self, opt_str, possibilities): |
| 146 | BadOptionError.__init__(self, opt_str) |
| 147 | self.possibilities = possibilities |
| 148 | |
| 149 | def __str__(self): |
| 150 | return (_("ambiguous option: %s (%s?)") |
| 151 | % (self.opt_str, ", ".join(self.possibilities))) |
Greg Ward | 2492fcf | 2003-04-21 02:40:34 +0000 | [diff] [blame] | 152 | |
| 153 | |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 154 | class HelpFormatter: |
| 155 | |
| 156 | """ |
| 157 | Abstract base class for formatting option help. OptionParser |
| 158 | instances should use one of the HelpFormatter subclasses for |
| 159 | formatting help; by default IndentedHelpFormatter is used. |
| 160 | |
| 161 | Instance attributes: |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 162 | parser : OptionParser |
| 163 | the controlling OptionParser instance |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 164 | indent_increment : int |
| 165 | the number of columns to indent per nesting level |
| 166 | max_help_position : int |
| 167 | the maximum starting column for option help text |
| 168 | help_position : int |
| 169 | the calculated starting column for option help text; |
| 170 | initially the same as the maximum |
| 171 | width : int |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 172 | total number of columns for output (pass None to constructor for |
| 173 | this value to be taken from the $COLUMNS environment variable) |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 174 | level : int |
| 175 | current indentation level |
| 176 | current_indent : int |
| 177 | current indentation level (in columns) |
| 178 | help_width : int |
| 179 | number of columns available for option help text (calculated) |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 180 | default_tag : str |
| 181 | text to replace with each option's default value, "%default" |
| 182 | by default. Set to false value to disable default value expansion. |
| 183 | option_strings : { Option : str } |
| 184 | maps Option instances to the snippet of help text explaining |
| 185 | the syntax of that option, e.g. "-h, --help" or |
| 186 | "-fFILE, --file=FILE" |
| 187 | _short_opt_fmt : str |
| 188 | format string controlling how short options with values are |
| 189 | printed in help text. Must be either "%s%s" ("-fFILE") or |
| 190 | "%s %s" ("-f FILE"), because those are the two syntaxes that |
| 191 | Optik supports. |
| 192 | _long_opt_fmt : str |
| 193 | similar but for long options; must be either "%s %s" ("--file FILE") |
| 194 | or "%s=%s" ("--file=FILE"). |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 195 | """ |
| 196 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 197 | NO_DEFAULT_VALUE = "none" |
| 198 | |
| 199 | def __init__(self, |
| 200 | indent_increment, |
| 201 | max_help_position, |
| 202 | width, |
| 203 | short_first): |
| 204 | self.parser = None |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 205 | self.indent_increment = indent_increment |
| 206 | self.help_position = self.max_help_position = max_help_position |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 207 | if width is None: |
| 208 | try: |
| 209 | width = int(os.environ['COLUMNS']) |
| 210 | except (KeyError, ValueError): |
| 211 | width = 80 |
| 212 | width -= 2 |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 213 | self.width = width |
| 214 | self.current_indent = 0 |
| 215 | self.level = 0 |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 216 | self.help_width = None # computed later |
Greg Ward | 2492fcf | 2003-04-21 02:40:34 +0000 | [diff] [blame] | 217 | self.short_first = short_first |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 218 | self.default_tag = "%default" |
| 219 | self.option_strings = {} |
| 220 | self._short_opt_fmt = "%s %s" |
| 221 | self._long_opt_fmt = "%s=%s" |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 222 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 223 | def set_parser(self, parser): |
| 224 | self.parser = parser |
| 225 | |
| 226 | def set_short_opt_delimiter(self, delim): |
| 227 | if delim not in ("", " "): |
| 228 | raise ValueError( |
| 229 | "invalid metavar delimiter for short options: %r" % delim) |
| 230 | self._short_opt_fmt = "%s" + delim + "%s" |
| 231 | |
| 232 | def set_long_opt_delimiter(self, delim): |
| 233 | if delim not in ("=", " "): |
| 234 | raise ValueError( |
| 235 | "invalid metavar delimiter for long options: %r" % delim) |
| 236 | self._long_opt_fmt = "%s" + delim + "%s" |
| 237 | |
| 238 | def indent(self): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 239 | self.current_indent += self.indent_increment |
| 240 | self.level += 1 |
| 241 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 242 | def dedent(self): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 243 | self.current_indent -= self.indent_increment |
| 244 | assert self.current_indent >= 0, "Indent decreased below 0." |
| 245 | self.level -= 1 |
| 246 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 247 | def format_usage(self, usage): |
Collin Winter | ce36ad8 | 2007-08-30 01:19:48 +0000 | [diff] [blame] | 248 | raise NotImplementedError("subclasses must implement") |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 249 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 250 | def format_heading(self, heading): |
Collin Winter | ce36ad8 | 2007-08-30 01:19:48 +0000 | [diff] [blame] | 251 | raise NotImplementedError("subclasses must implement") |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 252 | |
Thomas Wouters | 477c8d5 | 2006-05-27 19:21:47 +0000 | [diff] [blame] | 253 | def _format_text(self, text): |
| 254 | """ |
| 255 | Format a paragraph of free-form text for inclusion in the |
| 256 | help output at the current indentation level. |
| 257 | """ |
| 258 | text_width = self.width - self.current_indent |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 259 | indent = " "*self.current_indent |
Thomas Wouters | 477c8d5 | 2006-05-27 19:21:47 +0000 | [diff] [blame] | 260 | return textwrap.fill(text, |
| 261 | text_width, |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 262 | initial_indent=indent, |
Thomas Wouters | 477c8d5 | 2006-05-27 19:21:47 +0000 | [diff] [blame] | 263 | subsequent_indent=indent) |
| 264 | |
| 265 | def format_description(self, description): |
| 266 | if description: |
| 267 | return self._format_text(description) + "\n" |
| 268 | else: |
| 269 | return "" |
| 270 | |
| 271 | def format_epilog(self, epilog): |
| 272 | if epilog: |
| 273 | return "\n" + self._format_text(epilog) + "\n" |
| 274 | else: |
| 275 | return "" |
| 276 | |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 277 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 278 | def expand_default(self, option): |
| 279 | if self.parser is None or not self.default_tag: |
| 280 | return option.help |
| 281 | |
| 282 | default_value = self.parser.defaults.get(option.dest) |
| 283 | if default_value is NO_DEFAULT or default_value is None: |
| 284 | default_value = self.NO_DEFAULT_VALUE |
| 285 | |
| 286 | return option.help.replace(self.default_tag, str(default_value)) |
| 287 | |
| 288 | def format_option(self, option): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 289 | # The help for each option consists of two parts: |
| 290 | # * the opt strings and metavars |
| 291 | # eg. ("-x", or "-fFILENAME, --file=FILENAME") |
| 292 | # * the user-supplied help string |
| 293 | # eg. ("turn on expert mode", "read data from FILENAME") |
| 294 | # |
| 295 | # If possible, we write both of these on the same line: |
| 296 | # -x turn on expert mode |
| 297 | # |
| 298 | # But if the opt string list is too long, we put the help |
| 299 | # string on a second line, indented to the same column it would |
| 300 | # start in if it fit on the first line. |
| 301 | # -fFILENAME, --file=FILENAME |
| 302 | # read data from FILENAME |
| 303 | result = [] |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 304 | opts = self.option_strings[option] |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 305 | opt_width = self.help_position - self.current_indent - 2 |
| 306 | if len(opts) > opt_width: |
| 307 | opts = "%*s%s\n" % (self.current_indent, "", opts) |
| 308 | indent_first = self.help_position |
| 309 | else: # start help on same line as opts |
| 310 | opts = "%*s%-*s " % (self.current_indent, "", opt_width, opts) |
| 311 | indent_first = 0 |
| 312 | result.append(opts) |
| 313 | if option.help: |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 314 | help_text = self.expand_default(option) |
| 315 | help_lines = textwrap.wrap(help_text, self.help_width) |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 316 | result.append("%*s%s\n" % (indent_first, "", help_lines[0])) |
| 317 | result.extend(["%*s%s\n" % (self.help_position, "", line) |
| 318 | for line in help_lines[1:]]) |
| 319 | elif opts[-1] != "\n": |
| 320 | result.append("\n") |
| 321 | return "".join(result) |
| 322 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 323 | def store_option_strings(self, parser): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 324 | self.indent() |
| 325 | max_len = 0 |
| 326 | for opt in parser.option_list: |
| 327 | strings = self.format_option_strings(opt) |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 328 | self.option_strings[opt] = strings |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 329 | max_len = max(max_len, len(strings) + self.current_indent) |
| 330 | self.indent() |
| 331 | for group in parser.option_groups: |
| 332 | for opt in group.option_list: |
| 333 | strings = self.format_option_strings(opt) |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 334 | self.option_strings[opt] = strings |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 335 | max_len = max(max_len, len(strings) + self.current_indent) |
| 336 | self.dedent() |
| 337 | self.dedent() |
| 338 | self.help_position = min(max_len + 2, self.max_help_position) |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 339 | self.help_width = self.width - self.help_position |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 340 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 341 | def format_option_strings(self, option): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 342 | """Return a comma-separated list of option strings & metavariables.""" |
Greg Ward | 2492fcf | 2003-04-21 02:40:34 +0000 | [diff] [blame] | 343 | if option.takes_value(): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 344 | metavar = option.metavar or option.dest.upper() |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 345 | short_opts = [self._short_opt_fmt % (sopt, metavar) |
| 346 | for sopt in option._short_opts] |
| 347 | long_opts = [self._long_opt_fmt % (lopt, metavar) |
| 348 | for lopt in option._long_opts] |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 349 | else: |
Greg Ward | 2492fcf | 2003-04-21 02:40:34 +0000 | [diff] [blame] | 350 | short_opts = option._short_opts |
| 351 | long_opts = option._long_opts |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 352 | |
Greg Ward | 2492fcf | 2003-04-21 02:40:34 +0000 | [diff] [blame] | 353 | if self.short_first: |
| 354 | opts = short_opts + long_opts |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 355 | else: |
Greg Ward | 2492fcf | 2003-04-21 02:40:34 +0000 | [diff] [blame] | 356 | opts = long_opts + short_opts |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 357 | |
Greg Ward | 2492fcf | 2003-04-21 02:40:34 +0000 | [diff] [blame] | 358 | return ", ".join(opts) |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 359 | |
| 360 | class IndentedHelpFormatter (HelpFormatter): |
| 361 | """Format help with indented section bodies. |
| 362 | """ |
| 363 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 364 | def __init__(self, |
| 365 | indent_increment=2, |
| 366 | max_help_position=24, |
| 367 | width=None, |
| 368 | short_first=1): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 369 | HelpFormatter.__init__( |
| 370 | self, indent_increment, max_help_position, width, short_first) |
| 371 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 372 | def format_usage(self, usage): |
Thomas Wouters | 477c8d5 | 2006-05-27 19:21:47 +0000 | [diff] [blame] | 373 | return _("Usage: %s\n") % usage |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 374 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 375 | def format_heading(self, heading): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 376 | return "%*s%s:\n" % (self.current_indent, "", heading) |
| 377 | |
| 378 | |
| 379 | class TitledHelpFormatter (HelpFormatter): |
| 380 | """Format help with underlined section headers. |
| 381 | """ |
| 382 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 383 | def __init__(self, |
| 384 | indent_increment=0, |
| 385 | max_help_position=24, |
| 386 | width=None, |
| 387 | short_first=0): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 388 | HelpFormatter.__init__ ( |
| 389 | self, indent_increment, max_help_position, width, short_first) |
| 390 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 391 | def format_usage(self, usage): |
| 392 | return "%s %s\n" % (self.format_heading(_("Usage")), usage) |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 393 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 394 | def format_heading(self, heading): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 395 | return "%s\n%s\n" % (heading, "=-"[self.level] * len(heading)) |
Greg Ward | 2492fcf | 2003-04-21 02:40:34 +0000 | [diff] [blame] | 396 | |
| 397 | |
Thomas Wouters | 477c8d5 | 2006-05-27 19:21:47 +0000 | [diff] [blame] | 398 | def _parse_num(val, type): |
| 399 | if val[:2].lower() == "0x": # hexadecimal |
| 400 | radix = 16 |
| 401 | elif val[:2].lower() == "0b": # binary |
| 402 | radix = 2 |
| 403 | val = val[2:] or "0" # have to remove "0b" prefix |
| 404 | elif val[:1] == "0": # octal |
| 405 | radix = 8 |
| 406 | else: # decimal |
| 407 | radix = 10 |
| 408 | |
| 409 | return type(val, radix) |
| 410 | |
| 411 | def _parse_int(val): |
| 412 | return _parse_num(val, int) |
| 413 | |
| 414 | def _parse_long(val): |
Guido van Rossum | e2a383d | 2007-01-15 16:59:06 +0000 | [diff] [blame] | 415 | return _parse_num(val, int) |
Thomas Wouters | 477c8d5 | 2006-05-27 19:21:47 +0000 | [diff] [blame] | 416 | |
| 417 | _builtin_cvt = { "int" : (_parse_int, _("integer")), |
| 418 | "long" : (_parse_long, _("long integer")), |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 419 | "float" : (float, _("floating-point")), |
| 420 | "complex" : (complex, _("complex")) } |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 421 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 422 | def check_builtin(option, opt, value): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 423 | (cvt, what) = _builtin_cvt[option.type] |
| 424 | try: |
| 425 | return cvt(value) |
| 426 | except ValueError: |
| 427 | raise OptionValueError( |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 428 | _("option %s: invalid %s value: %r") % (opt, what, value)) |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 429 | |
| 430 | def check_choice(option, opt, value): |
| 431 | if value in option.choices: |
| 432 | return value |
| 433 | else: |
| 434 | choices = ", ".join(map(repr, option.choices)) |
| 435 | raise OptionValueError( |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 436 | _("option %s: invalid choice: %r (choose from %s)") |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 437 | % (opt, value, choices)) |
| 438 | |
| 439 | # Not supplying a default is different from a default of None, |
| 440 | # so we need an explicit "not supplied" value. |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 441 | NO_DEFAULT = ("NO", "DEFAULT") |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 442 | |
| 443 | |
| 444 | class Option: |
| 445 | """ |
| 446 | Instance attributes: |
| 447 | _short_opts : [string] |
| 448 | _long_opts : [string] |
| 449 | |
| 450 | action : string |
| 451 | type : string |
| 452 | dest : string |
| 453 | default : any |
| 454 | nargs : int |
| 455 | const : any |
| 456 | choices : [string] |
| 457 | callback : function |
| 458 | callback_args : (any*) |
| 459 | callback_kwargs : { string : any } |
| 460 | help : string |
| 461 | metavar : string |
| 462 | """ |
| 463 | |
| 464 | # The list of instance attributes that may be set through |
| 465 | # keyword args to the constructor. |
| 466 | ATTRS = ['action', |
| 467 | 'type', |
| 468 | 'dest', |
| 469 | 'default', |
| 470 | 'nargs', |
| 471 | 'const', |
| 472 | 'choices', |
| 473 | 'callback', |
| 474 | 'callback_args', |
| 475 | 'callback_kwargs', |
| 476 | 'help', |
| 477 | 'metavar'] |
| 478 | |
| 479 | # The set of actions allowed by option parsers. Explicitly listed |
| 480 | # here so the constructor can validate its arguments. |
| 481 | ACTIONS = ("store", |
| 482 | "store_const", |
| 483 | "store_true", |
| 484 | "store_false", |
| 485 | "append", |
Thomas Wouters | 477c8d5 | 2006-05-27 19:21:47 +0000 | [diff] [blame] | 486 | "append_const", |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 487 | "count", |
| 488 | "callback", |
| 489 | "help", |
| 490 | "version") |
| 491 | |
| 492 | # The set of actions that involve storing a value somewhere; |
| 493 | # also listed just for constructor argument validation. (If |
| 494 | # the action is one of these, there must be a destination.) |
| 495 | STORE_ACTIONS = ("store", |
| 496 | "store_const", |
| 497 | "store_true", |
| 498 | "store_false", |
| 499 | "append", |
Thomas Wouters | 477c8d5 | 2006-05-27 19:21:47 +0000 | [diff] [blame] | 500 | "append_const", |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 501 | "count") |
| 502 | |
| 503 | # The set of actions for which it makes sense to supply a value |
Greg Ward | 48aa84b | 2004-10-27 02:20:04 +0000 | [diff] [blame] | 504 | # type, ie. which may consume an argument from the command line. |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 505 | TYPED_ACTIONS = ("store", |
| 506 | "append", |
| 507 | "callback") |
| 508 | |
Greg Ward | 48aa84b | 2004-10-27 02:20:04 +0000 | [diff] [blame] | 509 | # The set of actions which *require* a value type, ie. that |
| 510 | # always consume an argument from the command line. |
| 511 | ALWAYS_TYPED_ACTIONS = ("store", |
| 512 | "append") |
| 513 | |
Thomas Wouters | 477c8d5 | 2006-05-27 19:21:47 +0000 | [diff] [blame] | 514 | # The set of actions which take a 'const' attribute. |
| 515 | CONST_ACTIONS = ("store_const", |
| 516 | "append_const") |
| 517 | |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 518 | # The set of known types for option parsers. Again, listed here for |
| 519 | # constructor argument validation. |
| 520 | TYPES = ("string", "int", "long", "float", "complex", "choice") |
| 521 | |
| 522 | # Dictionary of argument checking functions, which convert and |
| 523 | # validate option arguments according to the option type. |
| 524 | # |
| 525 | # Signature of checking functions is: |
| 526 | # check(option : Option, opt : string, value : string) -> any |
| 527 | # where |
| 528 | # option is the Option instance calling the checker |
| 529 | # opt is the actual option seen on the command-line |
| 530 | # (eg. "-a", "--file") |
| 531 | # value is the option argument seen on the command-line |
| 532 | # |
| 533 | # The return value should be in the appropriate Python type |
| 534 | # for option.type -- eg. an integer if option.type == "int". |
| 535 | # |
| 536 | # If no checker is defined for a type, arguments will be |
| 537 | # unchecked and remain strings. |
| 538 | TYPE_CHECKER = { "int" : check_builtin, |
| 539 | "long" : check_builtin, |
| 540 | "float" : check_builtin, |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 541 | "complex": check_builtin, |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 542 | "choice" : check_choice, |
| 543 | } |
| 544 | |
| 545 | |
| 546 | # CHECK_METHODS is a list of unbound method objects; they are called |
| 547 | # by the constructor, in order, after all attributes are |
| 548 | # initialized. The list is created and filled in later, after all |
| 549 | # the methods are actually defined. (I just put it here because I |
| 550 | # like to define and document all class attributes in the same |
| 551 | # place.) Subclasses that add another _check_*() method should |
| 552 | # define their own CHECK_METHODS list that adds their check method |
| 553 | # to those from this class. |
| 554 | CHECK_METHODS = None |
| 555 | |
| 556 | |
| 557 | # -- Constructor/initialization methods ---------------------------- |
| 558 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 559 | def __init__(self, *opts, **attrs): |
Greg Ward | 2492fcf | 2003-04-21 02:40:34 +0000 | [diff] [blame] | 560 | # Set _short_opts, _long_opts attrs from 'opts' tuple. |
| 561 | # Have to be set now, in case no option strings are supplied. |
| 562 | self._short_opts = [] |
| 563 | self._long_opts = [] |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 564 | opts = self._check_opt_strings(opts) |
| 565 | self._set_opt_strings(opts) |
| 566 | |
| 567 | # Set all other attrs (action, type, etc.) from 'attrs' dict |
| 568 | self._set_attrs(attrs) |
| 569 | |
| 570 | # Check all the attributes we just set. There are lots of |
| 571 | # complicated interdependencies, but luckily they can be farmed |
| 572 | # out to the _check_*() methods listed in CHECK_METHODS -- which |
| 573 | # could be handy for subclasses! The one thing these all share |
| 574 | # is that they raise OptionError if they discover a problem. |
| 575 | for checker in self.CHECK_METHODS: |
| 576 | checker(self) |
| 577 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 578 | def _check_opt_strings(self, opts): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 579 | # Filter out None because early versions of Optik had exactly |
| 580 | # one short option and one long option, either of which |
| 581 | # could be None. |
Guido van Rossum | c1f779c | 2007-07-03 08:25:58 +0000 | [diff] [blame] | 582 | opts = [opt for opt in opts if opt] |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 583 | if not opts: |
Greg Ward | 2492fcf | 2003-04-21 02:40:34 +0000 | [diff] [blame] | 584 | raise TypeError("at least one option string must be supplied") |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 585 | return opts |
| 586 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 587 | def _set_opt_strings(self, opts): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 588 | for opt in opts: |
| 589 | if len(opt) < 2: |
| 590 | raise OptionError( |
| 591 | "invalid option string %r: " |
| 592 | "must be at least two characters long" % opt, self) |
| 593 | elif len(opt) == 2: |
| 594 | if not (opt[0] == "-" and opt[1] != "-"): |
| 595 | raise OptionError( |
| 596 | "invalid short option string %r: " |
| 597 | "must be of the form -x, (x any non-dash char)" % opt, |
| 598 | self) |
| 599 | self._short_opts.append(opt) |
| 600 | else: |
| 601 | if not (opt[0:2] == "--" and opt[2] != "-"): |
| 602 | raise OptionError( |
| 603 | "invalid long option string %r: " |
| 604 | "must start with --, followed by non-dash" % opt, |
| 605 | self) |
| 606 | self._long_opts.append(opt) |
| 607 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 608 | def _set_attrs(self, attrs): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 609 | for attr in self.ATTRS: |
Guido van Rossum | e2b70bc | 2006-08-18 22:13:04 +0000 | [diff] [blame] | 610 | if attr in attrs: |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 611 | setattr(self, attr, attrs[attr]) |
| 612 | del attrs[attr] |
| 613 | else: |
| 614 | if attr == 'default': |
| 615 | setattr(self, attr, NO_DEFAULT) |
| 616 | else: |
| 617 | setattr(self, attr, None) |
| 618 | if attrs: |
Georg Brandl | c2d9d7f | 2007-02-11 23:06:17 +0000 | [diff] [blame] | 619 | attrs = sorted(attrs.keys()) |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 620 | raise OptionError( |
Thomas Wouters | 4d70c3d | 2006-06-08 14:42:34 +0000 | [diff] [blame] | 621 | "invalid keyword arguments: %s" % ", ".join(attrs), |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 622 | self) |
| 623 | |
| 624 | |
| 625 | # -- Constructor validation methods -------------------------------- |
| 626 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 627 | def _check_action(self): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 628 | if self.action is None: |
| 629 | self.action = "store" |
| 630 | elif self.action not in self.ACTIONS: |
| 631 | raise OptionError("invalid action: %r" % self.action, self) |
| 632 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 633 | def _check_type(self): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 634 | if self.type is None: |
Greg Ward | 48aa84b | 2004-10-27 02:20:04 +0000 | [diff] [blame] | 635 | if self.action in self.ALWAYS_TYPED_ACTIONS: |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 636 | if self.choices is not None: |
| 637 | # The "choices" attribute implies "choice" type. |
| 638 | self.type = "choice" |
| 639 | else: |
| 640 | # No type given? "string" is the most sensible default. |
| 641 | self.type = "string" |
| 642 | else: |
Thomas Wouters | 477c8d5 | 2006-05-27 19:21:47 +0000 | [diff] [blame] | 643 | # Allow type objects or builtin type conversion functions |
| 644 | # (int, str, etc.) as an alternative to their names. (The |
Georg Brandl | 1a3284e | 2007-12-02 09:40:06 +0000 | [diff] [blame] | 645 | # complicated check of builtins is only necessary for |
Thomas Wouters | 477c8d5 | 2006-05-27 19:21:47 +0000 | [diff] [blame] | 646 | # Python 2.1 and earlier, and is short-circuited by the |
| 647 | # first check on modern Pythons.) |
Georg Brandl | 1a3284e | 2007-12-02 09:40:06 +0000 | [diff] [blame] | 648 | import builtins |
Guido van Rossum | 1325790 | 2007-06-07 23:15:56 +0000 | [diff] [blame] | 649 | if ( isinstance(self.type, type) or |
Thomas Wouters | 477c8d5 | 2006-05-27 19:21:47 +0000 | [diff] [blame] | 650 | (hasattr(self.type, "__name__") and |
Georg Brandl | 1a3284e | 2007-12-02 09:40:06 +0000 | [diff] [blame] | 651 | getattr(builtins, self.type.__name__, None) is self.type) ): |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 652 | self.type = self.type.__name__ |
Thomas Wouters | 477c8d5 | 2006-05-27 19:21:47 +0000 | [diff] [blame] | 653 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 654 | if self.type == "str": |
| 655 | self.type = "string" |
| 656 | |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 657 | if self.type not in self.TYPES: |
| 658 | raise OptionError("invalid option type: %r" % self.type, self) |
| 659 | if self.action not in self.TYPED_ACTIONS: |
| 660 | raise OptionError( |
| 661 | "must not supply a type for action %r" % self.action, self) |
| 662 | |
| 663 | def _check_choice(self): |
| 664 | if self.type == "choice": |
| 665 | if self.choices is None: |
| 666 | raise OptionError( |
| 667 | "must supply a list of choices for type 'choice'", self) |
Guido van Rossum | 1325790 | 2007-06-07 23:15:56 +0000 | [diff] [blame] | 668 | elif not isinstance(self.choices, (tuple, list)): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 669 | raise OptionError( |
| 670 | "choices must be a list of strings ('%s' supplied)" |
| 671 | % str(type(self.choices)).split("'")[1], self) |
| 672 | elif self.choices is not None: |
| 673 | raise OptionError( |
| 674 | "must not supply choices for type %r" % self.type, self) |
| 675 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 676 | def _check_dest(self): |
| 677 | # No destination given, and we need one for this action. The |
| 678 | # self.type check is for callbacks that take a value. |
| 679 | takes_value = (self.action in self.STORE_ACTIONS or |
| 680 | self.type is not None) |
| 681 | if self.dest is None and takes_value: |
| 682 | |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 683 | # Glean a destination from the first long option string, |
| 684 | # or from the first short option string if no long options. |
| 685 | if self._long_opts: |
| 686 | # eg. "--foo-bar" -> "foo_bar" |
| 687 | self.dest = self._long_opts[0][2:].replace('-', '_') |
| 688 | else: |
| 689 | self.dest = self._short_opts[0][1] |
| 690 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 691 | def _check_const(self): |
Thomas Wouters | 477c8d5 | 2006-05-27 19:21:47 +0000 | [diff] [blame] | 692 | if self.action not in self.CONST_ACTIONS and self.const is not None: |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 693 | raise OptionError( |
| 694 | "'const' must not be supplied for action %r" % self.action, |
| 695 | self) |
| 696 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 697 | def _check_nargs(self): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 698 | if self.action in self.TYPED_ACTIONS: |
| 699 | if self.nargs is None: |
| 700 | self.nargs = 1 |
| 701 | elif self.nargs is not None: |
| 702 | raise OptionError( |
| 703 | "'nargs' must not be supplied for action %r" % self.action, |
| 704 | self) |
| 705 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 706 | def _check_callback(self): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 707 | if self.action == "callback": |
Florent Xicluna | 5d1155c | 2011-10-28 14:45:05 +0200 | [diff] [blame] | 708 | if not callable(self.callback): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 709 | raise OptionError( |
| 710 | "callback not callable: %r" % self.callback, self) |
| 711 | if (self.callback_args is not None and |
Guido van Rossum | 1325790 | 2007-06-07 23:15:56 +0000 | [diff] [blame] | 712 | not isinstance(self.callback_args, tuple)): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 713 | raise OptionError( |
| 714 | "callback_args, if supplied, must be a tuple: not %r" |
| 715 | % self.callback_args, self) |
| 716 | if (self.callback_kwargs is not None and |
Guido van Rossum | 1325790 | 2007-06-07 23:15:56 +0000 | [diff] [blame] | 717 | not isinstance(self.callback_kwargs, dict)): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 718 | raise OptionError( |
| 719 | "callback_kwargs, if supplied, must be a dict: not %r" |
| 720 | % self.callback_kwargs, self) |
| 721 | else: |
| 722 | if self.callback is not None: |
| 723 | raise OptionError( |
| 724 | "callback supplied (%r) for non-callback option" |
| 725 | % self.callback, self) |
| 726 | if self.callback_args is not None: |
| 727 | raise OptionError( |
| 728 | "callback_args supplied for non-callback option", self) |
| 729 | if self.callback_kwargs is not None: |
| 730 | raise OptionError( |
| 731 | "callback_kwargs supplied for non-callback option", self) |
| 732 | |
| 733 | |
| 734 | CHECK_METHODS = [_check_action, |
| 735 | _check_type, |
| 736 | _check_choice, |
| 737 | _check_dest, |
| 738 | _check_const, |
| 739 | _check_nargs, |
| 740 | _check_callback] |
| 741 | |
| 742 | |
| 743 | # -- Miscellaneous methods ----------------------------------------- |
| 744 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 745 | def __str__(self): |
Greg Ward | 2492fcf | 2003-04-21 02:40:34 +0000 | [diff] [blame] | 746 | return "/".join(self._short_opts + self._long_opts) |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 747 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 748 | __repr__ = _repr |
| 749 | |
| 750 | def takes_value(self): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 751 | return self.type is not None |
| 752 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 753 | def get_opt_string(self): |
| 754 | if self._long_opts: |
| 755 | return self._long_opts[0] |
| 756 | else: |
| 757 | return self._short_opts[0] |
| 758 | |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 759 | |
| 760 | # -- Processing methods -------------------------------------------- |
| 761 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 762 | def check_value(self, opt, value): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 763 | checker = self.TYPE_CHECKER.get(self.type) |
| 764 | if checker is None: |
| 765 | return value |
| 766 | else: |
| 767 | return checker(self, opt, value) |
| 768 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 769 | def convert_value(self, opt, value): |
| 770 | if value is not None: |
| 771 | if self.nargs == 1: |
| 772 | return self.check_value(opt, value) |
| 773 | else: |
| 774 | return tuple([self.check_value(opt, v) for v in value]) |
| 775 | |
| 776 | def process(self, opt, value, values, parser): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 777 | |
| 778 | # First, convert the value(s) to the right type. Howl if any |
| 779 | # value(s) are bogus. |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 780 | value = self.convert_value(opt, value) |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 781 | |
| 782 | # And then take whatever action is expected of us. |
| 783 | # This is a separate method to make life easier for |
| 784 | # subclasses to add new actions. |
| 785 | return self.take_action( |
| 786 | self.action, self.dest, opt, value, values, parser) |
| 787 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 788 | def take_action(self, action, dest, opt, value, values, parser): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 789 | if action == "store": |
| 790 | setattr(values, dest, value) |
| 791 | elif action == "store_const": |
| 792 | setattr(values, dest, self.const) |
| 793 | elif action == "store_true": |
Greg Ward | 2492fcf | 2003-04-21 02:40:34 +0000 | [diff] [blame] | 794 | setattr(values, dest, True) |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 795 | elif action == "store_false": |
Greg Ward | 2492fcf | 2003-04-21 02:40:34 +0000 | [diff] [blame] | 796 | setattr(values, dest, False) |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 797 | elif action == "append": |
| 798 | values.ensure_value(dest, []).append(value) |
Thomas Wouters | 477c8d5 | 2006-05-27 19:21:47 +0000 | [diff] [blame] | 799 | elif action == "append_const": |
| 800 | values.ensure_value(dest, []).append(self.const) |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 801 | elif action == "count": |
| 802 | setattr(values, dest, values.ensure_value(dest, 0) + 1) |
| 803 | elif action == "callback": |
| 804 | args = self.callback_args or () |
| 805 | kwargs = self.callback_kwargs or {} |
| 806 | self.callback(self, opt, value, parser, *args, **kwargs) |
| 807 | elif action == "help": |
| 808 | parser.print_help() |
Greg Ward | 48aa84b | 2004-10-27 02:20:04 +0000 | [diff] [blame] | 809 | parser.exit() |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 810 | elif action == "version": |
| 811 | parser.print_version() |
Greg Ward | 48aa84b | 2004-10-27 02:20:04 +0000 | [diff] [blame] | 812 | parser.exit() |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 813 | else: |
Benjamin Peterson | 4469d0c | 2008-11-30 22:46:23 +0000 | [diff] [blame] | 814 | raise ValueError("unknown action %r" % self.action) |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 815 | |
| 816 | return 1 |
| 817 | |
| 818 | # class Option |
Greg Ward | 2492fcf | 2003-04-21 02:40:34 +0000 | [diff] [blame] | 819 | |
| 820 | |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 821 | SUPPRESS_HELP = "SUPPRESS"+"HELP" |
| 822 | SUPPRESS_USAGE = "SUPPRESS"+"USAGE" |
| 823 | |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 824 | class Values: |
| 825 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 826 | def __init__(self, defaults=None): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 827 | if defaults: |
| 828 | for (attr, val) in defaults.items(): |
| 829 | setattr(self, attr, val) |
| 830 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 831 | def __str__(self): |
| 832 | return str(self.__dict__) |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 833 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 834 | __repr__ = _repr |
| 835 | |
Guido van Rossum | 47b9ff6 | 2006-08-24 00:41:19 +0000 | [diff] [blame] | 836 | def __eq__(self, other): |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 837 | if isinstance(other, Values): |
Guido van Rossum | 47b9ff6 | 2006-08-24 00:41:19 +0000 | [diff] [blame] | 838 | return self.__dict__ == other.__dict__ |
Guido van Rossum | 1325790 | 2007-06-07 23:15:56 +0000 | [diff] [blame] | 839 | elif isinstance(other, dict): |
Guido van Rossum | 47b9ff6 | 2006-08-24 00:41:19 +0000 | [diff] [blame] | 840 | return self.__dict__ == other |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 841 | else: |
Guido van Rossum | 47b9ff6 | 2006-08-24 00:41:19 +0000 | [diff] [blame] | 842 | return NotImplemented |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 843 | |
| 844 | def _update_careful(self, dict): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 845 | """ |
| 846 | Update the option values from an arbitrary dictionary, but only |
| 847 | use keys from dict that already have a corresponding attribute |
| 848 | in self. Any keys in dict without a corresponding attribute |
| 849 | are silently ignored. |
| 850 | """ |
| 851 | for attr in dir(self): |
Guido van Rossum | e2b70bc | 2006-08-18 22:13:04 +0000 | [diff] [blame] | 852 | if attr in dict: |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 853 | dval = dict[attr] |
| 854 | if dval is not None: |
| 855 | setattr(self, attr, dval) |
| 856 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 857 | def _update_loose(self, dict): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 858 | """ |
| 859 | Update the option values from an arbitrary dictionary, |
| 860 | using all keys from the dictionary regardless of whether |
| 861 | they have a corresponding attribute in self or not. |
| 862 | """ |
| 863 | self.__dict__.update(dict) |
| 864 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 865 | def _update(self, dict, mode): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 866 | if mode == "careful": |
| 867 | self._update_careful(dict) |
| 868 | elif mode == "loose": |
| 869 | self._update_loose(dict) |
| 870 | else: |
Collin Winter | ce36ad8 | 2007-08-30 01:19:48 +0000 | [diff] [blame] | 871 | raise ValueError("invalid update mode: %r" % mode) |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 872 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 873 | def read_module(self, modname, mode="careful"): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 874 | __import__(modname) |
| 875 | mod = sys.modules[modname] |
| 876 | self._update(vars(mod), mode) |
| 877 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 878 | def read_file(self, filename, mode="careful"): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 879 | vars = {} |
Neal Norwitz | 0168802 | 2007-08-12 00:43:29 +0000 | [diff] [blame] | 880 | exec(open(filename).read(), vars) |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 881 | self._update(vars, mode) |
| 882 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 883 | def ensure_value(self, attr, value): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 884 | if not hasattr(self, attr) or getattr(self, attr) is None: |
| 885 | setattr(self, attr, value) |
| 886 | return getattr(self, attr) |
| 887 | |
| 888 | |
| 889 | class OptionContainer: |
| 890 | |
| 891 | """ |
| 892 | Abstract base class. |
| 893 | |
| 894 | Class attributes: |
| 895 | standard_option_list : [Option] |
| 896 | list of standard options that will be accepted by all instances |
| 897 | of this parser class (intended to be overridden by subclasses). |
| 898 | |
| 899 | Instance attributes: |
| 900 | option_list : [Option] |
| 901 | the list of Option objects contained by this OptionContainer |
| 902 | _short_opt : { string : Option } |
| 903 | dictionary mapping short option strings, eg. "-f" or "-X", |
| 904 | to the Option instances that implement them. If an Option |
| 905 | has multiple short option strings, it will appears in this |
| 906 | dictionary multiple times. [1] |
| 907 | _long_opt : { string : Option } |
| 908 | dictionary mapping long option strings, eg. "--file" or |
| 909 | "--exclude", to the Option instances that implement them. |
| 910 | Again, a given Option can occur multiple times in this |
| 911 | dictionary. [1] |
| 912 | defaults : { string : any } |
| 913 | dictionary mapping option destination names to default |
| 914 | values for each destination [1] |
| 915 | |
| 916 | [1] These mappings are common to (shared by) all components of the |
| 917 | controlling OptionParser, where they are initially created. |
| 918 | |
| 919 | """ |
| 920 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 921 | def __init__(self, option_class, conflict_handler, description): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 922 | # Initialize the option list and related data structures. |
| 923 | # This method must be provided by subclasses, and it must |
| 924 | # initialize at least the following instance attributes: |
| 925 | # option_list, _short_opt, _long_opt, defaults. |
| 926 | self._create_option_list() |
| 927 | |
| 928 | self.option_class = option_class |
| 929 | self.set_conflict_handler(conflict_handler) |
| 930 | self.set_description(description) |
| 931 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 932 | def _create_option_mappings(self): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 933 | # For use by OptionParser constructor -- create the master |
| 934 | # option mappings used by this OptionParser and all |
| 935 | # OptionGroups that it owns. |
| 936 | self._short_opt = {} # single letter -> Option instance |
| 937 | self._long_opt = {} # long option -> Option instance |
| 938 | self.defaults = {} # maps option dest -> default value |
| 939 | |
| 940 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 941 | def _share_option_mappings(self, parser): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 942 | # For use by OptionGroup constructor -- use shared option |
| 943 | # mappings from the OptionParser that owns this OptionGroup. |
| 944 | self._short_opt = parser._short_opt |
| 945 | self._long_opt = parser._long_opt |
| 946 | self.defaults = parser.defaults |
| 947 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 948 | def set_conflict_handler(self, handler): |
Greg Ward | 48aa84b | 2004-10-27 02:20:04 +0000 | [diff] [blame] | 949 | if handler not in ("error", "resolve"): |
Collin Winter | ce36ad8 | 2007-08-30 01:19:48 +0000 | [diff] [blame] | 950 | raise ValueError("invalid conflict_resolution value %r" % handler) |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 951 | self.conflict_handler = handler |
| 952 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 953 | def set_description(self, description): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 954 | self.description = description |
| 955 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 956 | def get_description(self): |
| 957 | return self.description |
| 958 | |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 959 | |
Thomas Wouters | 477c8d5 | 2006-05-27 19:21:47 +0000 | [diff] [blame] | 960 | def destroy(self): |
| 961 | """see OptionParser.destroy().""" |
| 962 | del self._short_opt |
| 963 | del self._long_opt |
| 964 | del self.defaults |
| 965 | |
| 966 | |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 967 | # -- Option-adding methods ----------------------------------------- |
| 968 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 969 | def _check_conflict(self, option): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 970 | conflict_opts = [] |
| 971 | for opt in option._short_opts: |
Guido van Rossum | e2b70bc | 2006-08-18 22:13:04 +0000 | [diff] [blame] | 972 | if opt in self._short_opt: |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 973 | conflict_opts.append((opt, self._short_opt[opt])) |
| 974 | for opt in option._long_opts: |
Guido van Rossum | e2b70bc | 2006-08-18 22:13:04 +0000 | [diff] [blame] | 975 | if opt in self._long_opt: |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 976 | conflict_opts.append((opt, self._long_opt[opt])) |
| 977 | |
| 978 | if conflict_opts: |
| 979 | handler = self.conflict_handler |
Greg Ward | 48aa84b | 2004-10-27 02:20:04 +0000 | [diff] [blame] | 980 | if handler == "error": |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 981 | raise OptionConflictError( |
| 982 | "conflicting option string(s): %s" |
| 983 | % ", ".join([co[0] for co in conflict_opts]), |
| 984 | option) |
Greg Ward | 48aa84b | 2004-10-27 02:20:04 +0000 | [diff] [blame] | 985 | elif handler == "resolve": |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 986 | for (opt, c_option) in conflict_opts: |
| 987 | if opt.startswith("--"): |
| 988 | c_option._long_opts.remove(opt) |
| 989 | del self._long_opt[opt] |
| 990 | else: |
| 991 | c_option._short_opts.remove(opt) |
| 992 | del self._short_opt[opt] |
| 993 | if not (c_option._short_opts or c_option._long_opts): |
| 994 | c_option.container.option_list.remove(c_option) |
| 995 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 996 | def add_option(self, *args, **kwargs): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 997 | """add_option(Option) |
| 998 | add_option(opt_str, ..., kwarg=val, ...) |
| 999 | """ |
Guido van Rossum | 3172c5d | 2007-10-16 18:12:55 +0000 | [diff] [blame] | 1000 | if isinstance(args[0], str): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1001 | option = self.option_class(*args, **kwargs) |
| 1002 | elif len(args) == 1 and not kwargs: |
| 1003 | option = args[0] |
| 1004 | if not isinstance(option, Option): |
Collin Winter | ce36ad8 | 2007-08-30 01:19:48 +0000 | [diff] [blame] | 1005 | raise TypeError("not an Option instance: %r" % option) |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1006 | else: |
Collin Winter | ce36ad8 | 2007-08-30 01:19:48 +0000 | [diff] [blame] | 1007 | raise TypeError("invalid arguments") |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1008 | |
| 1009 | self._check_conflict(option) |
| 1010 | |
| 1011 | self.option_list.append(option) |
| 1012 | option.container = self |
| 1013 | for opt in option._short_opts: |
| 1014 | self._short_opt[opt] = option |
| 1015 | for opt in option._long_opts: |
| 1016 | self._long_opt[opt] = option |
| 1017 | |
| 1018 | if option.dest is not None: # option has a dest, we need a default |
| 1019 | if option.default is not NO_DEFAULT: |
| 1020 | self.defaults[option.dest] = option.default |
Guido van Rossum | e2b70bc | 2006-08-18 22:13:04 +0000 | [diff] [blame] | 1021 | elif option.dest not in self.defaults: |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1022 | self.defaults[option.dest] = None |
| 1023 | |
| 1024 | return option |
| 1025 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1026 | def add_options(self, option_list): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1027 | for option in option_list: |
| 1028 | self.add_option(option) |
| 1029 | |
| 1030 | # -- Option query/removal methods ---------------------------------- |
| 1031 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1032 | def get_option(self, opt_str): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1033 | return (self._short_opt.get(opt_str) or |
| 1034 | self._long_opt.get(opt_str)) |
| 1035 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1036 | def has_option(self, opt_str): |
Guido van Rossum | e2b70bc | 2006-08-18 22:13:04 +0000 | [diff] [blame] | 1037 | return (opt_str in self._short_opt or |
Guido van Rossum | 9366241 | 2006-08-19 16:09:41 +0000 | [diff] [blame] | 1038 | opt_str in self._long_opt) |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1039 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1040 | def remove_option(self, opt_str): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1041 | option = self._short_opt.get(opt_str) |
| 1042 | if option is None: |
| 1043 | option = self._long_opt.get(opt_str) |
| 1044 | if option is None: |
| 1045 | raise ValueError("no such option %r" % opt_str) |
| 1046 | |
| 1047 | for opt in option._short_opts: |
| 1048 | del self._short_opt[opt] |
| 1049 | for opt in option._long_opts: |
| 1050 | del self._long_opt[opt] |
| 1051 | option.container.option_list.remove(option) |
| 1052 | |
| 1053 | |
| 1054 | # -- Help-formatting methods --------------------------------------- |
| 1055 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1056 | def format_option_help(self, formatter): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1057 | if not self.option_list: |
| 1058 | return "" |
| 1059 | result = [] |
| 1060 | for option in self.option_list: |
| 1061 | if not option.help is SUPPRESS_HELP: |
| 1062 | result.append(formatter.format_option(option)) |
| 1063 | return "".join(result) |
| 1064 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1065 | def format_description(self, formatter): |
| 1066 | return formatter.format_description(self.get_description()) |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1067 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1068 | def format_help(self, formatter): |
| 1069 | result = [] |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1070 | if self.description: |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1071 | result.append(self.format_description(formatter)) |
| 1072 | if self.option_list: |
| 1073 | result.append(self.format_option_help(formatter)) |
| 1074 | return "\n".join(result) |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1075 | |
| 1076 | |
| 1077 | class OptionGroup (OptionContainer): |
| 1078 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1079 | def __init__(self, parser, title, description=None): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1080 | self.parser = parser |
| 1081 | OptionContainer.__init__( |
| 1082 | self, parser.option_class, parser.conflict_handler, description) |
| 1083 | self.title = title |
| 1084 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1085 | def _create_option_list(self): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1086 | self.option_list = [] |
| 1087 | self._share_option_mappings(self.parser) |
| 1088 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1089 | def set_title(self, title): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1090 | self.title = title |
| 1091 | |
Thomas Wouters | 477c8d5 | 2006-05-27 19:21:47 +0000 | [diff] [blame] | 1092 | def destroy(self): |
| 1093 | """see OptionParser.destroy().""" |
| 1094 | OptionContainer.destroy(self) |
| 1095 | del self.option_list |
| 1096 | |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1097 | # -- Help-formatting methods --------------------------------------- |
| 1098 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1099 | def format_help(self, formatter): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1100 | result = formatter.format_heading(self.title) |
| 1101 | formatter.indent() |
| 1102 | result += OptionContainer.format_help(self, formatter) |
| 1103 | formatter.dedent() |
| 1104 | return result |
| 1105 | |
| 1106 | |
| 1107 | class OptionParser (OptionContainer): |
| 1108 | |
| 1109 | """ |
| 1110 | Class attributes: |
| 1111 | standard_option_list : [Option] |
| 1112 | list of standard options that will be accepted by all instances |
| 1113 | of this parser class (intended to be overridden by subclasses). |
| 1114 | |
| 1115 | Instance attributes: |
| 1116 | usage : string |
| 1117 | a usage string for your program. Before it is displayed |
| 1118 | to the user, "%prog" will be expanded to the name of |
Greg Ward | 2492fcf | 2003-04-21 02:40:34 +0000 | [diff] [blame] | 1119 | your program (self.prog or os.path.basename(sys.argv[0])). |
| 1120 | prog : string |
| 1121 | the name of the current program (to override |
| 1122 | os.path.basename(sys.argv[0])). |
R David Murray | fc5ed80 | 2011-05-04 21:06:57 -0400 | [diff] [blame] | 1123 | description : string |
| 1124 | A paragraph of text giving a brief overview of your program. |
| 1125 | optparse reformats this paragraph to fit the current terminal |
| 1126 | width and prints it when the user requests help (after usage, |
| 1127 | but before the list of options). |
Thomas Wouters | 477c8d5 | 2006-05-27 19:21:47 +0000 | [diff] [blame] | 1128 | epilog : string |
| 1129 | paragraph of help text to print after option help |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1130 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1131 | option_groups : [OptionGroup] |
| 1132 | list of option groups in this parser (option groups are |
| 1133 | irrelevant for parsing the command-line, but very useful |
| 1134 | for generating help) |
| 1135 | |
| 1136 | allow_interspersed_args : bool = true |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1137 | if true, positional arguments may be interspersed with options. |
| 1138 | Assuming -a and -b each take a single argument, the command-line |
| 1139 | -ablah foo bar -bboo baz |
| 1140 | will be interpreted the same as |
| 1141 | -ablah -bboo -- foo bar baz |
| 1142 | If this flag were false, that command line would be interpreted as |
| 1143 | -ablah -- foo bar -bboo baz |
| 1144 | -- ie. we stop processing options as soon as we see the first |
| 1145 | non-option argument. (This is the tradition followed by |
| 1146 | Python's getopt module, Perl's Getopt::Std, and other argument- |
| 1147 | parsing libraries, but it is generally annoying to users.) |
| 1148 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1149 | process_default_values : bool = true |
| 1150 | if true, option default values are processed similarly to option |
| 1151 | values from the command line: that is, they are passed to the |
| 1152 | type-checking function for the option's type (as long as the |
| 1153 | default value is a string). (This really only matters if you |
| 1154 | have defined custom types; see SF bug #955889.) Set it to false |
| 1155 | to restore the behaviour of Optik 1.4.1 and earlier. |
| 1156 | |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1157 | rargs : [string] |
| 1158 | the argument list currently being parsed. Only set when |
| 1159 | parse_args() is active, and continually trimmed down as |
| 1160 | we consume arguments. Mainly there for the benefit of |
| 1161 | callback options. |
| 1162 | largs : [string] |
| 1163 | the list of leftover arguments that we have skipped while |
| 1164 | parsing options. If allow_interspersed_args is false, this |
| 1165 | list is always empty. |
| 1166 | values : Values |
| 1167 | the set of option values currently being accumulated. Only |
| 1168 | set when parse_args() is active. Also mainly for callbacks. |
| 1169 | |
| 1170 | Because of the 'rargs', 'largs', and 'values' attributes, |
| 1171 | OptionParser is not thread-safe. If, for some perverse reason, you |
| 1172 | need to parse command-line arguments simultaneously in different |
| 1173 | threads, use different OptionParser instances. |
| 1174 | |
| 1175 | """ |
| 1176 | |
| 1177 | standard_option_list = [] |
| 1178 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1179 | def __init__(self, |
| 1180 | usage=None, |
| 1181 | option_list=None, |
| 1182 | option_class=Option, |
| 1183 | version=None, |
| 1184 | conflict_handler="error", |
| 1185 | description=None, |
| 1186 | formatter=None, |
| 1187 | add_help_option=True, |
Thomas Wouters | 477c8d5 | 2006-05-27 19:21:47 +0000 | [diff] [blame] | 1188 | prog=None, |
| 1189 | epilog=None): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1190 | OptionContainer.__init__( |
| 1191 | self, option_class, conflict_handler, description) |
| 1192 | self.set_usage(usage) |
Greg Ward | 2492fcf | 2003-04-21 02:40:34 +0000 | [diff] [blame] | 1193 | self.prog = prog |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1194 | self.version = version |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1195 | self.allow_interspersed_args = True |
| 1196 | self.process_default_values = True |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1197 | if formatter is None: |
| 1198 | formatter = IndentedHelpFormatter() |
| 1199 | self.formatter = formatter |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1200 | self.formatter.set_parser(self) |
Thomas Wouters | 477c8d5 | 2006-05-27 19:21:47 +0000 | [diff] [blame] | 1201 | self.epilog = epilog |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1202 | |
| 1203 | # Populate the option list; initial sources are the |
| 1204 | # standard_option_list class attribute, the 'option_list' |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1205 | # argument, and (if applicable) the _add_version_option() and |
| 1206 | # _add_help_option() methods. |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1207 | self._populate_option_list(option_list, |
| 1208 | add_help=add_help_option) |
| 1209 | |
| 1210 | self._init_parsing_state() |
| 1211 | |
Thomas Wouters | 477c8d5 | 2006-05-27 19:21:47 +0000 | [diff] [blame] | 1212 | |
| 1213 | def destroy(self): |
| 1214 | """ |
| 1215 | Declare that you are done with this OptionParser. This cleans up |
| 1216 | reference cycles so the OptionParser (and all objects referenced by |
| 1217 | it) can be garbage-collected promptly. After calling destroy(), the |
| 1218 | OptionParser is unusable. |
| 1219 | """ |
| 1220 | OptionContainer.destroy(self) |
| 1221 | for group in self.option_groups: |
| 1222 | group.destroy() |
| 1223 | del self.option_list |
| 1224 | del self.option_groups |
| 1225 | del self.formatter |
| 1226 | |
| 1227 | |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1228 | # -- Private methods ----------------------------------------------- |
| 1229 | # (used by our or OptionContainer's constructor) |
| 1230 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1231 | def _create_option_list(self): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1232 | self.option_list = [] |
| 1233 | self.option_groups = [] |
| 1234 | self._create_option_mappings() |
| 1235 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1236 | def _add_help_option(self): |
| 1237 | self.add_option("-h", "--help", |
| 1238 | action="help", |
| 1239 | help=_("show this help message and exit")) |
| 1240 | |
| 1241 | def _add_version_option(self): |
| 1242 | self.add_option("--version", |
| 1243 | action="version", |
| 1244 | help=_("show program's version number and exit")) |
| 1245 | |
| 1246 | def _populate_option_list(self, option_list, add_help=True): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1247 | if self.standard_option_list: |
| 1248 | self.add_options(self.standard_option_list) |
| 1249 | if option_list: |
| 1250 | self.add_options(option_list) |
| 1251 | if self.version: |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1252 | self._add_version_option() |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1253 | if add_help: |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1254 | self._add_help_option() |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1255 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1256 | def _init_parsing_state(self): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1257 | # These are set in parse_args() for the convenience of callbacks. |
| 1258 | self.rargs = None |
| 1259 | self.largs = None |
| 1260 | self.values = None |
| 1261 | |
| 1262 | |
| 1263 | # -- Simple modifier methods --------------------------------------- |
| 1264 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1265 | def set_usage(self, usage): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1266 | if usage is None: |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1267 | self.usage = _("%prog [options]") |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1268 | elif usage is SUPPRESS_USAGE: |
| 1269 | self.usage = None |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1270 | # For backwards compatibility with Optik 1.3 and earlier. |
Thomas Wouters | 477c8d5 | 2006-05-27 19:21:47 +0000 | [diff] [blame] | 1271 | elif usage.lower().startswith("usage: "): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1272 | self.usage = usage[7:] |
| 1273 | else: |
| 1274 | self.usage = usage |
| 1275 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1276 | def enable_interspersed_args(self): |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 1277 | """Set parsing to not stop on the first non-option, allowing |
| 1278 | interspersing switches with command arguments. This is the |
| 1279 | default behavior. See also disable_interspersed_args() and the |
| 1280 | class documentation description of the attribute |
| 1281 | allow_interspersed_args.""" |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1282 | self.allow_interspersed_args = True |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1283 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1284 | def disable_interspersed_args(self): |
Benjamin Peterson | f10a79a | 2008-10-11 00:49:57 +0000 | [diff] [blame] | 1285 | """Set parsing to stop on the first non-option. Use this if |
| 1286 | you have a command processor which runs another command that |
| 1287 | has options of its own and you want to make sure these options |
| 1288 | don't get confused. |
| 1289 | """ |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1290 | self.allow_interspersed_args = False |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1291 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1292 | def set_process_default_values(self, process): |
| 1293 | self.process_default_values = process |
| 1294 | |
| 1295 | def set_default(self, dest, value): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1296 | self.defaults[dest] = value |
| 1297 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1298 | def set_defaults(self, **kwargs): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1299 | self.defaults.update(kwargs) |
| 1300 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1301 | def _get_all_options(self): |
| 1302 | options = self.option_list[:] |
| 1303 | for group in self.option_groups: |
| 1304 | options.extend(group.option_list) |
| 1305 | return options |
| 1306 | |
| 1307 | def get_default_values(self): |
| 1308 | if not self.process_default_values: |
| 1309 | # Old, pre-Optik 1.5 behaviour. |
| 1310 | return Values(self.defaults) |
| 1311 | |
| 1312 | defaults = self.defaults.copy() |
| 1313 | for option in self._get_all_options(): |
| 1314 | default = defaults.get(option.dest) |
Guido van Rossum | 3172c5d | 2007-10-16 18:12:55 +0000 | [diff] [blame] | 1315 | if isinstance(default, str): |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1316 | opt_str = option.get_opt_string() |
| 1317 | defaults[option.dest] = option.check_value(opt_str, default) |
| 1318 | |
| 1319 | return Values(defaults) |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1320 | |
| 1321 | |
| 1322 | # -- OptionGroup methods ------------------------------------------- |
| 1323 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1324 | def add_option_group(self, *args, **kwargs): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1325 | # XXX lots of overlap with OptionContainer.add_option() |
Guido van Rossum | 3172c5d | 2007-10-16 18:12:55 +0000 | [diff] [blame] | 1326 | if isinstance(args[0], str): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1327 | group = OptionGroup(self, *args, **kwargs) |
| 1328 | elif len(args) == 1 and not kwargs: |
| 1329 | group = args[0] |
| 1330 | if not isinstance(group, OptionGroup): |
Collin Winter | ce36ad8 | 2007-08-30 01:19:48 +0000 | [diff] [blame] | 1331 | raise TypeError("not an OptionGroup instance: %r" % group) |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1332 | if group.parser is not self: |
Collin Winter | ce36ad8 | 2007-08-30 01:19:48 +0000 | [diff] [blame] | 1333 | raise ValueError("invalid OptionGroup (wrong parser)") |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1334 | else: |
Collin Winter | ce36ad8 | 2007-08-30 01:19:48 +0000 | [diff] [blame] | 1335 | raise TypeError("invalid arguments") |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1336 | |
| 1337 | self.option_groups.append(group) |
| 1338 | return group |
| 1339 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1340 | def get_option_group(self, opt_str): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1341 | option = (self._short_opt.get(opt_str) or |
| 1342 | self._long_opt.get(opt_str)) |
| 1343 | if option and option.container is not self: |
| 1344 | return option.container |
| 1345 | return None |
| 1346 | |
| 1347 | |
| 1348 | # -- Option-parsing methods ---------------------------------------- |
| 1349 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1350 | def _get_args(self, args): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1351 | if args is None: |
| 1352 | return sys.argv[1:] |
| 1353 | else: |
| 1354 | return args[:] # don't modify caller's list |
| 1355 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1356 | def parse_args(self, args=None, values=None): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1357 | """ |
| 1358 | parse_args(args : [string] = sys.argv[1:], |
| 1359 | values : Values = None) |
| 1360 | -> (values : Values, args : [string]) |
| 1361 | |
| 1362 | Parse the command-line options found in 'args' (default: |
| 1363 | sys.argv[1:]). Any errors result in a call to 'error()', which |
| 1364 | by default prints the usage message to stderr and calls |
| 1365 | sys.exit() with an error message. On success returns a pair |
| 1366 | (values, args) where 'values' is an Values instance (with all |
| 1367 | your option values) and 'args' is the list of arguments left |
| 1368 | over after parsing options. |
| 1369 | """ |
| 1370 | rargs = self._get_args(args) |
| 1371 | if values is None: |
| 1372 | values = self.get_default_values() |
| 1373 | |
| 1374 | # Store the halves of the argument list as attributes for the |
| 1375 | # convenience of callbacks: |
| 1376 | # rargs |
| 1377 | # the rest of the command-line (the "r" stands for |
| 1378 | # "remaining" or "right-hand") |
| 1379 | # largs |
| 1380 | # the leftover arguments -- ie. what's left after removing |
| 1381 | # options and their arguments (the "l" stands for "leftover" |
| 1382 | # or "left-hand") |
| 1383 | self.rargs = rargs |
| 1384 | self.largs = largs = [] |
| 1385 | self.values = values |
| 1386 | |
| 1387 | try: |
| 1388 | stop = self._process_args(largs, rargs, values) |
Guido van Rossum | b940e11 | 2007-01-10 16:19:56 +0000 | [diff] [blame] | 1389 | except (BadOptionError, OptionValueError) as err: |
Thomas Wouters | 477c8d5 | 2006-05-27 19:21:47 +0000 | [diff] [blame] | 1390 | self.error(str(err)) |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1391 | |
| 1392 | args = largs + rargs |
| 1393 | return self.check_values(values, args) |
| 1394 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1395 | def check_values(self, values, args): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1396 | """ |
| 1397 | check_values(values : Values, args : [string]) |
| 1398 | -> (values : Values, args : [string]) |
| 1399 | |
| 1400 | Check that the supplied option values and leftover arguments are |
| 1401 | valid. Returns the option values and leftover arguments |
| 1402 | (possibly adjusted, possibly completely new -- whatever you |
| 1403 | like). Default implementation just returns the passed-in |
| 1404 | values; subclasses may override as desired. |
| 1405 | """ |
| 1406 | return (values, args) |
| 1407 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1408 | def _process_args(self, largs, rargs, values): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1409 | """_process_args(largs : [string], |
| 1410 | rargs : [string], |
| 1411 | values : Values) |
| 1412 | |
| 1413 | Process command-line arguments and populate 'values', consuming |
| 1414 | options and arguments from 'rargs'. If 'allow_interspersed_args' is |
| 1415 | false, stop at the first non-option argument. If true, accumulate any |
| 1416 | interspersed non-option arguments in 'largs'. |
| 1417 | """ |
| 1418 | while rargs: |
| 1419 | arg = rargs[0] |
| 1420 | # We handle bare "--" explicitly, and bare "-" is handled by the |
| 1421 | # standard arg handler since the short arg case ensures that the |
| 1422 | # len of the opt string is greater than 1. |
| 1423 | if arg == "--": |
| 1424 | del rargs[0] |
| 1425 | return |
| 1426 | elif arg[0:2] == "--": |
| 1427 | # process a single long option (possibly with value(s)) |
| 1428 | self._process_long_opt(rargs, values) |
| 1429 | elif arg[:1] == "-" and len(arg) > 1: |
| 1430 | # process a cluster of short options (possibly with |
| 1431 | # value(s) for the last one only) |
| 1432 | self._process_short_opts(rargs, values) |
| 1433 | elif self.allow_interspersed_args: |
| 1434 | largs.append(arg) |
| 1435 | del rargs[0] |
| 1436 | else: |
| 1437 | return # stop now, leave this arg in rargs |
| 1438 | |
| 1439 | # Say this is the original argument list: |
| 1440 | # [arg0, arg1, ..., arg(i-1), arg(i), arg(i+1), ..., arg(N-1)] |
| 1441 | # ^ |
| 1442 | # (we are about to process arg(i)). |
| 1443 | # |
| 1444 | # Then rargs is [arg(i), ..., arg(N-1)] and largs is a *subset* of |
| 1445 | # [arg0, ..., arg(i-1)] (any options and their arguments will have |
| 1446 | # been removed from largs). |
| 1447 | # |
| 1448 | # The while loop will usually consume 1 or more arguments per pass. |
| 1449 | # If it consumes 1 (eg. arg is an option that takes no arguments), |
| 1450 | # then after _process_arg() is done the situation is: |
| 1451 | # |
| 1452 | # largs = subset of [arg0, ..., arg(i)] |
| 1453 | # rargs = [arg(i+1), ..., arg(N-1)] |
| 1454 | # |
| 1455 | # If allow_interspersed_args is false, largs will always be |
| 1456 | # *empty* -- still a subset of [arg0, ..., arg(i-1)], but |
| 1457 | # not a very interesting subset! |
| 1458 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1459 | def _match_long_opt(self, opt): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1460 | """_match_long_opt(opt : string) -> string |
| 1461 | |
| 1462 | Determine which long option string 'opt' matches, ie. which one |
| 1463 | it is an unambiguous abbrevation for. Raises BadOptionError if |
| 1464 | 'opt' doesn't unambiguously match any long option string. |
| 1465 | """ |
| 1466 | return _match_abbrev(opt, self._long_opt) |
| 1467 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1468 | def _process_long_opt(self, rargs, values): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1469 | arg = rargs.pop(0) |
| 1470 | |
| 1471 | # Value explicitly attached to arg? Pretend it's the next |
| 1472 | # argument. |
| 1473 | if "=" in arg: |
| 1474 | (opt, next_arg) = arg.split("=", 1) |
| 1475 | rargs.insert(0, next_arg) |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1476 | had_explicit_value = True |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1477 | else: |
| 1478 | opt = arg |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1479 | had_explicit_value = False |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1480 | |
| 1481 | opt = self._match_long_opt(opt) |
| 1482 | option = self._long_opt[opt] |
| 1483 | if option.takes_value(): |
| 1484 | nargs = option.nargs |
| 1485 | if len(rargs) < nargs: |
| 1486 | if nargs == 1: |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1487 | self.error(_("%s option requires an argument") % opt) |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1488 | else: |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1489 | self.error(_("%s option requires %d arguments") |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1490 | % (opt, nargs)) |
| 1491 | elif nargs == 1: |
| 1492 | value = rargs.pop(0) |
| 1493 | else: |
| 1494 | value = tuple(rargs[0:nargs]) |
| 1495 | del rargs[0:nargs] |
| 1496 | |
| 1497 | elif had_explicit_value: |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1498 | self.error(_("%s option does not take a value") % opt) |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1499 | |
| 1500 | else: |
| 1501 | value = None |
| 1502 | |
| 1503 | option.process(opt, value, values, self) |
| 1504 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1505 | def _process_short_opts(self, rargs, values): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1506 | arg = rargs.pop(0) |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1507 | stop = False |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1508 | i = 1 |
| 1509 | for ch in arg[1:]: |
| 1510 | opt = "-" + ch |
| 1511 | option = self._short_opt.get(opt) |
| 1512 | i += 1 # we have consumed a character |
| 1513 | |
| 1514 | if not option: |
Thomas Wouters | 477c8d5 | 2006-05-27 19:21:47 +0000 | [diff] [blame] | 1515 | raise BadOptionError(opt) |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1516 | if option.takes_value(): |
| 1517 | # Any characters left in arg? Pretend they're the |
| 1518 | # next arg, and stop consuming characters of arg. |
| 1519 | if i < len(arg): |
| 1520 | rargs.insert(0, arg[i:]) |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1521 | stop = True |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1522 | |
| 1523 | nargs = option.nargs |
| 1524 | if len(rargs) < nargs: |
| 1525 | if nargs == 1: |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1526 | self.error(_("%s option requires an argument") % opt) |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1527 | else: |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1528 | self.error(_("%s option requires %d arguments") |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1529 | % (opt, nargs)) |
| 1530 | elif nargs == 1: |
| 1531 | value = rargs.pop(0) |
| 1532 | else: |
| 1533 | value = tuple(rargs[0:nargs]) |
| 1534 | del rargs[0:nargs] |
| 1535 | |
| 1536 | else: # option doesn't take a value |
| 1537 | value = None |
| 1538 | |
| 1539 | option.process(opt, value, values, self) |
| 1540 | |
| 1541 | if stop: |
| 1542 | break |
| 1543 | |
| 1544 | |
| 1545 | # -- Feedback methods ---------------------------------------------- |
| 1546 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1547 | def get_prog_name(self): |
| 1548 | if self.prog is None: |
| 1549 | return os.path.basename(sys.argv[0]) |
| 1550 | else: |
| 1551 | return self.prog |
| 1552 | |
| 1553 | def expand_prog_name(self, s): |
| 1554 | return s.replace("%prog", self.get_prog_name()) |
| 1555 | |
| 1556 | def get_description(self): |
| 1557 | return self.expand_prog_name(self.description) |
| 1558 | |
Greg Ward | 48aa84b | 2004-10-27 02:20:04 +0000 | [diff] [blame] | 1559 | def exit(self, status=0, msg=None): |
| 1560 | if msg: |
| 1561 | sys.stderr.write(msg) |
| 1562 | sys.exit(status) |
| 1563 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1564 | def error(self, msg): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1565 | """error(msg : string) |
| 1566 | |
| 1567 | Print a usage message incorporating 'msg' to stderr and exit. |
| 1568 | If you override this in a subclass, it should not return -- it |
| 1569 | should either exit or raise an exception. |
| 1570 | """ |
| 1571 | self.print_usage(sys.stderr) |
Greg Ward | 48aa84b | 2004-10-27 02:20:04 +0000 | [diff] [blame] | 1572 | self.exit(2, "%s: error: %s\n" % (self.get_prog_name(), msg)) |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1573 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1574 | def get_usage(self): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1575 | if self.usage: |
| 1576 | return self.formatter.format_usage( |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1577 | self.expand_prog_name(self.usage)) |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1578 | else: |
| 1579 | return "" |
| 1580 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1581 | def print_usage(self, file=None): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1582 | """print_usage(file : file = stdout) |
| 1583 | |
| 1584 | Print the usage message for the current program (self.usage) to |
Mark Dickinson | 934896d | 2009-02-21 20:59:32 +0000 | [diff] [blame] | 1585 | 'file' (default stdout). Any occurrence of the string "%prog" in |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1586 | self.usage is replaced with the name of the current program |
| 1587 | (basename of sys.argv[0]). Does nothing if self.usage is empty |
| 1588 | or not defined. |
| 1589 | """ |
| 1590 | if self.usage: |
Guido van Rossum | be19ed7 | 2007-02-09 05:37:30 +0000 | [diff] [blame] | 1591 | print(self.get_usage(), file=file) |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1592 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1593 | def get_version(self): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1594 | if self.version: |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1595 | return self.expand_prog_name(self.version) |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1596 | else: |
| 1597 | return "" |
| 1598 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1599 | def print_version(self, file=None): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1600 | """print_version(file : file = stdout) |
| 1601 | |
| 1602 | Print the version message for this program (self.version) to |
Mark Dickinson | 934896d | 2009-02-21 20:59:32 +0000 | [diff] [blame] | 1603 | 'file' (default stdout). As with print_usage(), any occurrence |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1604 | of "%prog" in self.version is replaced by the current program's |
| 1605 | name. Does nothing if self.version is empty or undefined. |
| 1606 | """ |
| 1607 | if self.version: |
Guido van Rossum | be19ed7 | 2007-02-09 05:37:30 +0000 | [diff] [blame] | 1608 | print(self.get_version(), file=file) |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1609 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1610 | def format_option_help(self, formatter=None): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1611 | if formatter is None: |
| 1612 | formatter = self.formatter |
| 1613 | formatter.store_option_strings(self) |
| 1614 | result = [] |
Thomas Wouters | 477c8d5 | 2006-05-27 19:21:47 +0000 | [diff] [blame] | 1615 | result.append(formatter.format_heading(_("Options"))) |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1616 | formatter.indent() |
| 1617 | if self.option_list: |
| 1618 | result.append(OptionContainer.format_option_help(self, formatter)) |
| 1619 | result.append("\n") |
| 1620 | for group in self.option_groups: |
| 1621 | result.append(group.format_help(formatter)) |
| 1622 | result.append("\n") |
| 1623 | formatter.dedent() |
| 1624 | # Drop the last "\n", or the header if no options or option groups: |
| 1625 | return "".join(result[:-1]) |
| 1626 | |
Thomas Wouters | 477c8d5 | 2006-05-27 19:21:47 +0000 | [diff] [blame] | 1627 | def format_epilog(self, formatter): |
| 1628 | return formatter.format_epilog(self.epilog) |
| 1629 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1630 | def format_help(self, formatter=None): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1631 | if formatter is None: |
| 1632 | formatter = self.formatter |
| 1633 | result = [] |
| 1634 | if self.usage: |
| 1635 | result.append(self.get_usage() + "\n") |
| 1636 | if self.description: |
| 1637 | result.append(self.format_description(formatter) + "\n") |
| 1638 | result.append(self.format_option_help(formatter)) |
Thomas Wouters | 477c8d5 | 2006-05-27 19:21:47 +0000 | [diff] [blame] | 1639 | result.append(self.format_epilog(formatter)) |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1640 | return "".join(result) |
| 1641 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1642 | def print_help(self, file=None): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1643 | """print_help(file : file = stdout) |
| 1644 | |
| 1645 | Print an extended help message, listing all options and any |
| 1646 | help text provided with them, to 'file' (default stdout). |
| 1647 | """ |
| 1648 | if file is None: |
| 1649 | file = sys.stdout |
Guido van Rossum | 34d1928 | 2007-08-09 01:03:29 +0000 | [diff] [blame] | 1650 | file.write(self.format_help()) |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1651 | |
| 1652 | # class OptionParser |
| 1653 | |
| 1654 | |
Greg Ward | eba20e6 | 2004-07-31 16:15:44 +0000 | [diff] [blame] | 1655 | def _match_abbrev(s, wordmap): |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1656 | """_match_abbrev(s : string, wordmap : {string : Option}) -> string |
| 1657 | |
| 1658 | Return the string key in 'wordmap' for which 's' is an unambiguous |
| 1659 | abbreviation. If 's' is found to be ambiguous or doesn't match any of |
| 1660 | 'words', raise BadOptionError. |
| 1661 | """ |
| 1662 | # Is there an exact match? |
Guido van Rossum | e2b70bc | 2006-08-18 22:13:04 +0000 | [diff] [blame] | 1663 | if s in wordmap: |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1664 | return s |
| 1665 | else: |
| 1666 | # Isolate all words with s as a prefix. |
| 1667 | possibilities = [word for word in wordmap.keys() |
| 1668 | if word.startswith(s)] |
| 1669 | # No exact match, so there had better be just one possibility. |
| 1670 | if len(possibilities) == 1: |
| 1671 | return possibilities[0] |
| 1672 | elif not possibilities: |
Thomas Wouters | 477c8d5 | 2006-05-27 19:21:47 +0000 | [diff] [blame] | 1673 | raise BadOptionError(s) |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1674 | else: |
| 1675 | # More than one possible completion: ambiguous prefix. |
Thomas Wouters | 4d70c3d | 2006-06-08 14:42:34 +0000 | [diff] [blame] | 1676 | possibilities.sort() |
Thomas Wouters | 477c8d5 | 2006-05-27 19:21:47 +0000 | [diff] [blame] | 1677 | raise AmbiguousOptionError(s, possibilities) |
Guido van Rossum | b9ba458 | 2002-11-14 22:00:19 +0000 | [diff] [blame] | 1678 | |
| 1679 | |
| 1680 | # Some day, there might be many Option classes. As of Optik 1.3, the |
| 1681 | # preferred way to instantiate Options is indirectly, via make_option(), |
| 1682 | # which will become a factory function when there are many Option |
| 1683 | # classes. |
| 1684 | make_option = Option |