1 """optparse - a powerful, extensible, and easy-to-use option parser.
3 By Greg Ward <gward@python.net>
5 Originally distributed as Optik; see http://optik.sourceforge.net/ .
7 If you have problems with this module, please do not file bugs,
8 patches, or feature requests with Python; instead, use Optik's
9 SourceForge project page:
10 http://sourceforge.net/projects/optik
12 For support, use the optik-users@lists.sourceforge.net mailing list
13 (http://lists.sourceforge.net/lists/listinfo/optik-users).
16 # Python developers: please do not make changes to this file, since
17 # it is automatically generated from the Optik source code.
29 'IndentedHelpFormatter',
30 'TitledHelpFormatter',
33 'OptionConflictError',
38 Copyright (c) 2001-2006 Gregory P. Ward. All rights reserved.
39 Copyright (c) 2002-2006 Python Software Foundation. All rights reserved.
41 Redistribution and use in source and binary forms, with or without
42 modification, are permitted provided that the following conditions are
45 * Redistributions of source code must retain the above copyright
46 notice, this list of conditions and the following disclaimer.
48 * Redistributions in binary form must reproduce the above copyright
49 notice, this list of conditions and the following disclaimer in the
50 documentation and/or other materials provided with the distribution.
52 * Neither the name of the author nor the names of its
53 contributors may be used to endorse or promote products derived from
54 this software without specific prior written permission.
56 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
57 IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
58 TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
59 PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR
60 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
61 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
62 PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
63 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
64 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
65 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
66 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
75 return "<%s at 0x%x: %s>" % (self.__class__.__name__, id(self), self)
79 sys.getdefaultencoding
80 except AttributeError:
81 def fake_getdefaultencoding():
83 sys.getdefaultencoding = fake_getdefaultencoding
87 except AttributeError:
88 def encode_wrapper(s, encoding, replacement):
91 def encode_wrapper(s, encoding, replacement):
92 return s.encode(encoding, replacement)
95 # This file was generated from:
96 # Id: option_parser.py 527 2006-07-23 15:21:30Z greg
97 # Id: option.py 522 2006-06-11 16:22:03Z gward
98 # Id: help.py 527 2006-07-23 15:21:30Z greg
99 # Id: errors.py 509 2006-04-20 00:58:24Z gward
102 from gettext import gettext
104 def gettext(message):
109 class OptParseError (Exception):
110 def __init__(self, msg):
117 class OptionError (OptParseError):
119 Raised if an Option instance is created with invalid or
120 inconsistent arguments.
123 def __init__(self, msg, option):
125 self.option_id = str(option)
129 return "option %s: %s" % (self.option_id, self.msg)
133 class OptionConflictError (OptionError):
135 Raised if conflicting options are added to an OptionParser.
138 class OptionValueError (OptParseError):
140 Raised if an invalid option value is encountered on the command
144 class BadOptionError (OptParseError):
146 Raised if an invalid option is seen on the command line.
148 def __init__(self, opt_str):
149 self.opt_str = opt_str
152 return _("no such option: %s") % self.opt_str
154 class AmbiguousOptionError (BadOptionError):
156 Raised if an ambiguous option is seen on the command line.
158 def __init__(self, opt_str, possibilities):
159 BadOptionError.__init__(self, opt_str)
160 self.possibilities = possibilities
163 return (_("ambiguous option: %s (%s?)")
164 % (self.opt_str, string.join(self.possibilities, ", ")))
170 Abstract base class for formatting option help. OptionParser
171 instances should use one of the HelpFormatter subclasses for
172 formatting help; by default IndentedHelpFormatter is used.
175 parser : OptionParser
176 the controlling OptionParser instance
177 indent_increment : int
178 the number of columns to indent per nesting level
179 max_help_position : int
180 the maximum starting column for option help text
182 the calculated starting column for option help text;
183 initially the same as the maximum
185 total number of columns for output (pass None to constructor for
186 this value to be taken from the $COLUMNS environment variable)
188 current indentation level
190 current indentation level (in columns)
192 number of columns available for option help text (calculated)
194 text to replace with each option's default value, "%default"
195 by default. Set to false value to disable default value expansion.
196 option_strings : { Option : str }
197 maps Option instances to the snippet of help text explaining
198 the syntax of that option, e.g. "-h, --help" or
199 "-fFILE, --file=FILE"
201 format string controlling how short options with values are
202 printed in help text. Must be either "%s%s" ("-fFILE") or
203 "%s %s" ("-f FILE"), because those are the two syntaxes that
206 similar but for long options; must be either "%s %s" ("--file FILE")
207 or "%s=%s" ("--file=FILE").
210 NO_DEFAULT_VALUE = "none"
218 self.indent_increment = indent_increment
219 self.help_position = self.max_help_position = max_help_position
222 width = int(os.environ['COLUMNS'])
223 except (KeyError, ValueError):
227 self.current_indent = 0
229 self.help_width = None # computed later
230 self.short_first = short_first
231 self.default_tag = "%default"
232 self.option_strings = {}
233 self._short_opt_fmt = "%s %s"
234 self._long_opt_fmt = "%s=%s"
236 def set_parser(self, parser):
239 def set_short_opt_delimiter(self, delim):
240 if delim not in ("", " "):
242 "invalid metavar delimiter for short options: %r" % delim)
243 self._short_opt_fmt = "%s" + delim + "%s"
245 def set_long_opt_delimiter(self, delim):
246 if delim not in ("=", " "):
248 "invalid metavar delimiter for long options: %r" % delim)
249 self._long_opt_fmt = "%s" + delim + "%s"
252 self.current_indent = self.current_indent + self.indent_increment
253 self.level = self.level + 1
256 self.current_indent = self.current_indent - self.indent_increment
257 assert self.current_indent >= 0, "Indent decreased below 0."
258 self.level = self.level - 1
260 def format_usage(self, usage):
261 raise NotImplementedError, "subclasses must implement"
263 def format_heading(self, heading):
264 raise NotImplementedError, "subclasses must implement"
266 def _format_text(self, text):
268 Format a paragraph of free-form text for inclusion in the
269 help output at the current indentation level.
271 text_width = self.width - self.current_indent
272 indent = " "*self.current_indent
273 return textwrap.fill(text,
275 initial_indent=indent,
276 subsequent_indent=indent)
278 def format_description(self, description):
280 return self._format_text(description) + "\n"
284 def format_epilog(self, epilog):
286 return "\n" + self._format_text(epilog) + "\n"
291 def expand_default(self, option):
292 if self.parser is None or not self.default_tag:
295 default_value = self.parser.defaults.get(option.dest)
296 if default_value is NO_DEFAULT or default_value is None:
297 default_value = self.NO_DEFAULT_VALUE
299 return string.replace(option.help, self.default_tag, str(default_value))
301 def format_option(self, option):
302 # The help for each option consists of two parts:
303 # * the opt strings and metavars
304 # eg. ("-x", or "-fFILENAME, --file=FILENAME")
305 # * the user-supplied help string
306 # eg. ("turn on expert mode", "read data from FILENAME")
308 # If possible, we write both of these on the same line:
309 # -x turn on expert mode
311 # But if the opt string list is too long, we put the help
312 # string on a second line, indented to the same column it would
313 # start in if it fit on the first line.
314 # -fFILENAME, --file=FILENAME
315 # read data from FILENAME
317 opts = self.option_strings[option]
318 opt_width = self.help_position - self.current_indent - 2
319 if len(opts) > opt_width:
320 opts = "%*s%s\n" % (self.current_indent, "", opts)
321 indent_first = self.help_position
322 else: # start help on same line as opts
323 opts = "%*s%-*s " % (self.current_indent, "", opt_width, opts)
327 help_text = self.expand_default(option)
328 help_lines = textwrap.wrap(help_text, self.help_width)
329 result.append("%*s%s\n" % (indent_first, "", help_lines[0]))
330 for line in help_lines[1:]:
331 result.append("%*s%s\n" % (self.help_position, "", line))
332 elif opts[-1] != "\n":
334 return string.join(result, "")
336 def store_option_strings(self, parser):
339 for opt in parser.option_list:
340 strings = self.format_option_strings(opt)
341 self.option_strings[opt] = strings
342 max_len = max(max_len, len(strings) + self.current_indent)
344 for group in parser.option_groups:
345 for opt in group.option_list:
346 strings = self.format_option_strings(opt)
347 self.option_strings[opt] = strings
348 max_len = max(max_len, len(strings) + self.current_indent)
351 self.help_position = min(max_len + 2, self.max_help_position)
352 self.help_width = self.width - self.help_position
354 def format_option_strings(self, option):
355 """Return a comma-separated list of option strings & metavariables."""
356 if option.takes_value():
357 metavar = option.metavar or string.upper(option.dest)
359 for sopt in option._short_opts:
360 short_opts.append(self._short_opt_fmt % (sopt, metavar))
362 for lopt in option._long_opts:
363 long_opts.append(self._long_opt_fmt % (lopt, metavar))
365 short_opts = option._short_opts
366 long_opts = option._long_opts
369 opts = short_opts + long_opts
371 opts = long_opts + short_opts
373 return string.join(opts, ", ")
375 class IndentedHelpFormatter (HelpFormatter):
376 """Format help with indented section bodies.
381 max_help_position=24,
384 HelpFormatter.__init__(
385 self, indent_increment, max_help_position, width, short_first)
387 def format_usage(self, usage):
388 return _("Usage: %s\n") % usage
390 def format_heading(self, heading):
391 return "%*s%s:\n" % (self.current_indent, "", heading)
394 class TitledHelpFormatter (HelpFormatter):
395 """Format help with underlined section headers.
400 max_help_position=24,
403 HelpFormatter.__init__ (
404 self, indent_increment, max_help_position, width, short_first)
406 def format_usage(self, usage):
407 return "%s %s\n" % (self.format_heading(_("Usage")), usage)
409 def format_heading(self, heading):
410 return "%s\n%s\n" % (heading, "=-"[self.level] * len(heading))
413 def _parse_num(val, type):
414 if string.lower(val[:2]) == "0x": # hexadecimal
416 elif string.lower(val[:2]) == "0b": # binary
418 val = val[2:] or "0" # have to remove "0b" prefix
419 elif val[:1] == "0": # octal
424 return type(val, radix)
427 return _parse_num(val, int)
429 def _parse_long(val):
430 return _parse_num(val, long)
435 # Python 1.5.2 doesn't allow a radix value to be passed to int().
441 # Python 1.5.2 doesn't allow a radix value to be passed to long().
444 _builtin_cvt = { "int" : (_parse_int, _("integer")),
445 "long" : (_parse_long, _("long integer")),
446 "float" : (float, _("floating-point")),
447 "complex" : (complex, _("complex")) }
449 def check_builtin(option, opt, value):
450 (cvt, what) = _builtin_cvt[option.type]
454 raise OptionValueError(
455 _("option %s: invalid %s value: %r") % (opt, what, value))
457 def check_choice(option, opt, value):
458 if value in option.choices:
461 choices = string.join(map(repr, option.choices), ", ")
462 raise OptionValueError(
463 _("option %s: invalid choice: %r (choose from %s)")
464 % (opt, value, choices))
466 # Not supplying a default is different from a default of None,
467 # so we need an explicit "not supplied" value.
468 NO_DEFAULT = ("NO", "DEFAULT")
474 _short_opts : [string]
475 _long_opts : [string]
485 callback_args : (any*)
486 callback_kwargs : { string : any }
491 # The list of instance attributes that may be set through
492 # keyword args to the constructor.
506 # The set of actions allowed by option parsers. Explicitly listed
507 # here so the constructor can validate its arguments.
519 # The set of actions that involve storing a value somewhere;
520 # also listed just for constructor argument validation. (If
521 # the action is one of these, there must be a destination.)
522 STORE_ACTIONS = ("store",
530 # The set of actions for which it makes sense to supply a value
531 # type, ie. which may consume an argument from the command line.
532 TYPED_ACTIONS = ("store",
536 # The set of actions which *require* a value type, ie. that
537 # always consume an argument from the command line.
538 ALWAYS_TYPED_ACTIONS = ("store",
541 # The set of actions which take a 'const' attribute.
542 CONST_ACTIONS = ("store_const",
545 # The set of known types for option parsers. Again, listed here for
546 # constructor argument validation.
547 TYPES = ("string", "int", "long", "float", "complex", "choice")
549 # Dictionary of argument checking functions, which convert and
550 # validate option arguments according to the option type.
552 # Signature of checking functions is:
553 # check(option : Option, opt : string, value : string) -> any
555 # option is the Option instance calling the checker
556 # opt is the actual option seen on the command-line
557 # (eg. "-a", "--file")
558 # value is the option argument seen on the command-line
560 # The return value should be in the appropriate Python type
561 # for option.type -- eg. an integer if option.type == "int".
563 # If no checker is defined for a type, arguments will be
564 # unchecked and remain strings.
565 TYPE_CHECKER = { "int" : check_builtin,
566 "long" : check_builtin,
567 "float" : check_builtin,
568 "complex": check_builtin,
569 "choice" : check_choice,
573 # CHECK_METHODS is a list of unbound method objects; they are called
574 # by the constructor, in order, after all attributes are
575 # initialized. The list is created and filled in later, after all
576 # the methods are actually defined. (I just put it here because I
577 # like to define and document all class attributes in the same
578 # place.) Subclasses that add another _check_*() method should
579 # define their own CHECK_METHODS list that adds their check method
580 # to those from this class.
584 # -- Constructor/initialization methods ----------------------------
586 def __init__(self, *opts, **attrs):
587 # Set _short_opts, _long_opts attrs from 'opts' tuple.
588 # Have to be set now, in case no option strings are supplied.
589 self._short_opts = []
591 opts = self._check_opt_strings(opts)
592 self._set_opt_strings(opts)
594 # Set all other attrs (action, type, etc.) from 'attrs' dict
595 self._set_attrs(attrs)
597 # Check all the attributes we just set. There are lots of
598 # complicated interdependencies, but luckily they can be farmed
599 # out to the _check_*() methods listed in CHECK_METHODS -- which
600 # could be handy for subclasses! The one thing these all share
601 # is that they raise OptionError if they discover a problem.
602 for checker in self.CHECK_METHODS:
605 def _check_opt_strings(self, opts):
606 # Filter out None because early versions of Optik had exactly
607 # one short option and one long option, either of which
609 opts = filter(None, opts)
611 raise TypeError("at least one option string must be supplied")
614 def _set_opt_strings(self, opts):
618 "invalid option string %r: "
619 "must be at least two characters long" % opt, self)
621 if not (opt[0] == "-" and opt[1] != "-"):
623 "invalid short option string %r: "
624 "must be of the form -x, (x any non-dash char)" % opt,
626 self._short_opts.append(opt)
628 if not (opt[0:2] == "--" and opt[2] != "-"):
630 "invalid long option string %r: "
631 "must start with --, followed by non-dash" % opt,
633 self._long_opts.append(opt)
635 def _set_attrs(self, attrs):
636 for attr in self.ATTRS:
637 if attrs.has_key(attr):
638 setattr(self, attr, attrs[attr])
641 if attr == 'default':
642 setattr(self, attr, NO_DEFAULT)
644 setattr(self, attr, None)
649 "invalid keyword arguments: %s" % string.join(attrs, ", "),
653 # -- Constructor validation methods --------------------------------
655 def _check_action(self):
656 if self.action is None:
657 self.action = "store"
658 elif self.action not in self.ACTIONS:
659 raise OptionError("invalid action: %r" % self.action, self)
661 def _check_type(self):
662 if self.type is None:
663 if self.action in self.ALWAYS_TYPED_ACTIONS:
664 if self.choices is not None:
665 # The "choices" attribute implies "choice" type.
668 # No type given? "string" is the most sensible default.
671 # Allow type objects or builtin type conversion functions
672 # (int, str, etc.) as an alternative to their names. (The
673 # complicated check of __builtin__ is only necessary for
674 # Python 2.1 and earlier, and is short-circuited by the
675 # first check on modern Pythons.)
677 if ( type(self.type) is types.TypeType or
678 (hasattr(self.type, "__name__") and
679 getattr(__builtin__, self.type.__name__, None) is self.type) ):
680 self.type = self.type.__name__
682 if self.type == "str":
685 if self.type not in self.TYPES:
686 raise OptionError("invalid option type: %r" % self.type, self)
687 if self.action not in self.TYPED_ACTIONS:
689 "must not supply a type for action %r" % self.action, self)
691 def _check_choice(self):
692 if self.type == "choice":
693 if self.choices is None:
695 "must supply a list of choices for type 'choice'", self)
696 elif type(self.choices) not in (types.TupleType, types.ListType):
698 "choices must be a list of strings ('%s' supplied)"
699 % string.split(str(type(self.choices)), "'")[1], self)
700 elif self.choices is not None:
702 "must not supply choices for type %r" % self.type, self)
704 def _check_dest(self):
705 # No destination given, and we need one for this action. The
706 # self.type check is for callbacks that take a value.
707 takes_value = (self.action in self.STORE_ACTIONS or
708 self.type is not None)
709 if self.dest is None and takes_value:
711 # Glean a destination from the first long option string,
712 # or from the first short option string if no long options.
714 # eg. "--foo-bar" -> "foo_bar"
715 self.dest = string.replace(self._long_opts[0][2:], '-', '_')
717 self.dest = self._short_opts[0][1]
719 def _check_const(self):
720 if self.action not in self.CONST_ACTIONS and self.const is not None:
722 "'const' must not be supplied for action %r" % self.action,
725 def _check_nargs(self):
726 if self.action in self.TYPED_ACTIONS:
727 if self.nargs is None:
729 elif self.nargs is not None:
731 "'nargs' must not be supplied for action %r" % self.action,
734 def _check_callback(self):
735 if self.action == "callback":
736 if not callable(self.callback):
738 "callback not callable: %r" % self.callback, self)
739 if (self.callback_args is not None and
740 type(self.callback_args) is not types.TupleType):
742 "callback_args, if supplied, must be a tuple: not %r"
743 % self.callback_args, self)
744 if (self.callback_kwargs is not None and
745 type(self.callback_kwargs) is not types.DictType):
747 "callback_kwargs, if supplied, must be a dict: not %r"
748 % self.callback_kwargs, self)
750 if self.callback is not None:
752 "callback supplied (%r) for non-callback option"
753 % self.callback, self)
754 if self.callback_args is not None:
756 "callback_args supplied for non-callback option", self)
757 if self.callback_kwargs is not None:
759 "callback_kwargs supplied for non-callback option", self)
762 CHECK_METHODS = [_check_action,
771 # -- Miscellaneous methods -----------------------------------------
774 return string.join(self._short_opts + self._long_opts, "/")
778 def takes_value(self):
779 return self.type is not None
781 def get_opt_string(self):
783 return self._long_opts[0]
785 return self._short_opts[0]
788 # -- Processing methods --------------------------------------------
790 def check_value(self, opt, value):
791 checker = self.TYPE_CHECKER.get(self.type)
795 return checker(self, opt, value)
797 def convert_value(self, opt, value):
798 if value is not None:
800 return self.check_value(opt, value)
802 return tuple(map(lambda v, o=opt, s=self: s.check_value(o, v), value))
804 def process(self, opt, value, values, parser):
806 # First, convert the value(s) to the right type. Howl if any
807 # value(s) are bogus.
808 value = self.convert_value(opt, value)
810 # And then take whatever action is expected of us.
811 # This is a separate method to make life easier for
812 # subclasses to add new actions.
813 return self.take_action(
814 self.action, self.dest, opt, value, values, parser)
816 def take_action(self, action, dest, opt, value, values, parser):
817 if action == "store":
818 setattr(values, dest, value)
819 elif action == "store_const":
820 setattr(values, dest, self.const)
821 elif action == "store_true":
822 setattr(values, dest, True)
823 elif action == "store_false":
824 setattr(values, dest, False)
825 elif action == "append":
826 values.ensure_value(dest, []).append(value)
827 elif action == "append_const":
828 values.ensure_value(dest, []).append(self.const)
829 elif action == "count":
830 setattr(values, dest, values.ensure_value(dest, 0) + 1)
831 elif action == "callback":
832 args = self.callback_args or ()
833 kwargs = self.callback_kwargs or {}
834 apply(self.callback, (self, opt, value, parser,) + args, kwargs)
835 elif action == "help":
838 elif action == "version":
839 parser.print_version()
842 raise RuntimeError, "unknown action %r" % self.action
849 SUPPRESS_HELP = "SUPPRESS"+"HELP"
850 SUPPRESS_USAGE = "SUPPRESS"+"USAGE"
852 # For compatibility with Python 2.2
856 (True, False) = (1, 0)
860 except AttributeError:
862 return isinstance(x, types.StringType)
865 return isinstance(x, types.StringType) or isinstance(x, types.UnicodeType)
869 def __init__(self, defaults=None):
871 for (attr, val) in defaults.items():
872 setattr(self, attr, val)
875 return str(self.__dict__)
879 def __cmp__(self, other):
880 if isinstance(other, Values):
881 return cmp(self.__dict__, other.__dict__)
882 elif isinstance(other, types.DictType):
883 return cmp(self.__dict__, other)
887 def _update_careful(self, dict):
889 Update the option values from an arbitrary dictionary, but only
890 use keys from dict that already have a corresponding attribute
891 in self. Any keys in dict without a corresponding attribute
892 are silently ignored.
894 for attr in dir(self):
895 if dict.has_key(attr):
898 setattr(self, attr, dval)
900 def _update_loose(self, dict):
902 Update the option values from an arbitrary dictionary,
903 using all keys from the dictionary regardless of whether
904 they have a corresponding attribute in self or not.
906 self.__dict__.update(dict)
908 def _update(self, dict, mode):
909 if mode == "careful":
910 self._update_careful(dict)
911 elif mode == "loose":
912 self._update_loose(dict)
914 raise ValueError, "invalid update mode: %r" % mode
916 def read_module(self, modname, mode="careful"):
918 mod = sys.modules[modname]
919 self._update(vars(mod), mode)
921 def read_file(self, filename, mode="careful"):
923 execfile(filename, vars)
924 self._update(vars, mode)
926 def ensure_value(self, attr, value):
927 if not hasattr(self, attr) or getattr(self, attr) is None:
928 setattr(self, attr, value)
929 return getattr(self, attr)
932 class OptionContainer:
938 standard_option_list : [Option]
939 list of standard options that will be accepted by all instances
940 of this parser class (intended to be overridden by subclasses).
943 option_list : [Option]
944 the list of Option objects contained by this OptionContainer
945 _short_opt : { string : Option }
946 dictionary mapping short option strings, eg. "-f" or "-X",
947 to the Option instances that implement them. If an Option
948 has multiple short option strings, it will appears in this
949 dictionary multiple times. [1]
950 _long_opt : { string : Option }
951 dictionary mapping long option strings, eg. "--file" or
952 "--exclude", to the Option instances that implement them.
953 Again, a given Option can occur multiple times in this
955 defaults : { string : any }
956 dictionary mapping option destination names to default
957 values for each destination [1]
959 [1] These mappings are common to (shared by) all components of the
960 controlling OptionParser, where they are initially created.
964 def __init__(self, option_class, conflict_handler, description):
965 # Initialize the option list and related data structures.
966 # This method must be provided by subclasses, and it must
967 # initialize at least the following instance attributes:
968 # option_list, _short_opt, _long_opt, defaults.
969 self._create_option_list()
971 self.option_class = option_class
972 self.set_conflict_handler(conflict_handler)
973 self.set_description(description)
975 def _create_option_mappings(self):
976 # For use by OptionParser constructor -- create the master
977 # option mappings used by this OptionParser and all
978 # OptionGroups that it owns.
979 self._short_opt = {} # single letter -> Option instance
980 self._long_opt = {} # long option -> Option instance
981 self.defaults = {} # maps option dest -> default value
984 def _share_option_mappings(self, parser):
985 # For use by OptionGroup constructor -- use shared option
986 # mappings from the OptionParser that owns this OptionGroup.
987 self._short_opt = parser._short_opt
988 self._long_opt = parser._long_opt
989 self.defaults = parser.defaults
991 def set_conflict_handler(self, handler):
992 if handler not in ("error", "resolve"):
993 raise ValueError, "invalid conflict_resolution value %r" % handler
994 self.conflict_handler = handler
996 def set_description(self, description):
997 self.description = description
999 def get_description(self):
1000 return self.description
1004 """see OptionParser.destroy()."""
1010 # -- Option-adding methods -----------------------------------------
1012 def _check_conflict(self, option):
1014 for opt in option._short_opts:
1015 if self._short_opt.has_key(opt):
1016 conflict_opts.append((opt, self._short_opt[opt]))
1017 for opt in option._long_opts:
1018 if self._long_opt.has_key(opt):
1019 conflict_opts.append((opt, self._long_opt[opt]))
1022 handler = self.conflict_handler
1023 if handler == "error":
1024 raise OptionConflictError(
1025 "conflicting option string(s): %s"
1026 % string.join(map(lambda co: co[0], conflict_opts), ", "),
1028 elif handler == "resolve":
1029 for (opt, c_option) in conflict_opts:
1031 c_option._long_opts.remove(opt)
1032 del self._long_opt[opt]
1034 c_option._short_opts.remove(opt)
1035 del self._short_opt[opt]
1036 if not (c_option._short_opts or c_option._long_opts):
1037 c_option.container.option_list.remove(c_option)
1039 def add_option(self, *args, **kwargs):
1040 """add_option(Option)
1041 add_option(opt_str, ..., kwarg=val, ...)
1043 if type(args[0]) is types.StringType:
1044 option = apply(self.option_class, args, kwargs)
1045 elif len(args) == 1 and not kwargs:
1047 if not isinstance(option, Option):
1048 raise TypeError, "not an Option instance: %r" % option
1050 raise TypeError, "invalid arguments"
1052 self._check_conflict(option)
1054 self.option_list.append(option)
1055 option.container = self
1056 for opt in option._short_opts:
1057 self._short_opt[opt] = option
1058 for opt in option._long_opts:
1059 self._long_opt[opt] = option
1061 if option.dest is not None: # option has a dest, we need a default
1062 if option.default is not NO_DEFAULT:
1063 self.defaults[option.dest] = option.default
1064 elif not self.defaults.has_key(option.dest):
1065 self.defaults[option.dest] = None
1069 def add_options(self, option_list):
1070 for option in option_list:
1071 self.add_option(option)
1073 # -- Option query/removal methods ----------------------------------
1075 def get_option(self, opt_str):
1076 return (self._short_opt.get(opt_str) or
1077 self._long_opt.get(opt_str))
1079 def has_option(self, opt_str):
1080 return (self._short_opt.has_key(opt_str) or
1081 self._long_opt.has_key(opt_str))
1083 def remove_option(self, opt_str):
1084 option = self._short_opt.get(opt_str)
1086 option = self._long_opt.get(opt_str)
1088 raise ValueError("no such option %r" % opt_str)
1090 for opt in option._short_opts:
1091 del self._short_opt[opt]
1092 for opt in option._long_opts:
1093 del self._long_opt[opt]
1094 option.container.option_list.remove(option)
1097 # -- Help-formatting methods ---------------------------------------
1099 def format_option_help(self, formatter):
1100 if not self.option_list:
1103 for option in self.option_list:
1104 if not option.help is SUPPRESS_HELP:
1105 result.append(formatter.format_option(option))
1106 return string.join(result, "")
1108 def format_description(self, formatter):
1109 return formatter.format_description(self.get_description())
1111 def format_help(self, formatter):
1113 if self.description:
1114 result.append(self.format_description(formatter))
1115 if self.option_list:
1116 result.append(self.format_option_help(formatter))
1117 return string.join(result, "\n")
1120 class OptionGroup (OptionContainer):
1122 def __init__(self, parser, title, description=None):
1123 self.parser = parser
1124 OptionContainer.__init__(
1125 self, parser.option_class, parser.conflict_handler, description)
1128 def _create_option_list(self):
1129 self.option_list = []
1130 self._share_option_mappings(self.parser)
1132 def set_title(self, title):
1136 """see OptionParser.destroy()."""
1137 OptionContainer.destroy(self)
1138 del self.option_list
1140 # -- Help-formatting methods ---------------------------------------
1142 def format_help(self, formatter):
1143 result = formatter.format_heading(self.title)
1145 result = result + OptionContainer.format_help(self, formatter)
1150 class OptionParser (OptionContainer):
1154 standard_option_list : [Option]
1155 list of standard options that will be accepted by all instances
1156 of this parser class (intended to be overridden by subclasses).
1158 Instance attributes:
1160 a usage string for your program. Before it is displayed
1161 to the user, "%prog" will be expanded to the name of
1162 your program (self.prog or os.path.basename(sys.argv[0])).
1164 the name of the current program (to override
1165 os.path.basename(sys.argv[0])).
1167 paragraph of help text to print after option help
1169 option_groups : [OptionGroup]
1170 list of option groups in this parser (option groups are
1171 irrelevant for parsing the command-line, but very useful
1172 for generating help)
1174 allow_interspersed_args : bool = true
1175 if true, positional arguments may be interspersed with options.
1176 Assuming -a and -b each take a single argument, the command-line
1177 -ablah foo bar -bboo baz
1178 will be interpreted the same as
1179 -ablah -bboo -- foo bar baz
1180 If this flag were false, that command line would be interpreted as
1181 -ablah -- foo bar -bboo baz
1182 -- ie. we stop processing options as soon as we see the first
1183 non-option argument. (This is the tradition followed by
1184 Python's getopt module, Perl's Getopt::Std, and other argument-
1185 parsing libraries, but it is generally annoying to users.)
1187 process_default_values : bool = true
1188 if true, option default values are processed similarly to option
1189 values from the command line: that is, they are passed to the
1190 type-checking function for the option's type (as long as the
1191 default value is a string). (This really only matters if you
1192 have defined custom types; see SF bug #955889.) Set it to false
1193 to restore the behaviour of Optik 1.4.1 and earlier.
1196 the argument list currently being parsed. Only set when
1197 parse_args() is active, and continually trimmed down as
1198 we consume arguments. Mainly there for the benefit of
1201 the list of leftover arguments that we have skipped while
1202 parsing options. If allow_interspersed_args is false, this
1203 list is always empty.
1205 the set of option values currently being accumulated. Only
1206 set when parse_args() is active. Also mainly for callbacks.
1208 Because of the 'rargs', 'largs', and 'values' attributes,
1209 OptionParser is not thread-safe. If, for some perverse reason, you
1210 need to parse command-line arguments simultaneously in different
1211 threads, use different OptionParser instances.
1215 standard_option_list = []
1220 option_class=Option,
1222 conflict_handler="error",
1225 add_help_option=True,
1228 OptionContainer.__init__(
1229 self, option_class, conflict_handler, description)
1230 self.set_usage(usage)
1232 self.version = version
1233 self.allow_interspersed_args = True
1234 self.process_default_values = True
1235 if formatter is None:
1236 formatter = IndentedHelpFormatter()
1237 self.formatter = formatter
1238 self.formatter.set_parser(self)
1239 self.epilog = epilog
1241 # Populate the option list; initial sources are the
1242 # standard_option_list class attribute, the 'option_list'
1243 # argument, and (if applicable) the _add_version_option() and
1244 # _add_help_option() methods.
1245 self._populate_option_list(option_list,
1246 add_help=add_help_option)
1248 self._init_parsing_state()
1253 Declare that you are done with this OptionParser. This cleans up
1254 reference cycles so the OptionParser (and all objects referenced by
1255 it) can be garbage-collected promptly. After calling destroy(), the
1256 OptionParser is unusable.
1258 OptionContainer.destroy(self)
1259 for group in self.option_groups:
1261 del self.option_list
1262 del self.option_groups
1266 # -- Private methods -----------------------------------------------
1267 # (used by our or OptionContainer's constructor)
1269 def _create_option_list(self):
1270 self.option_list = []
1271 self.option_groups = []
1272 self._create_option_mappings()
1274 def _add_help_option(self):
1275 self.add_option("-h", "--help",
1277 help=_("show this help message and exit"))
1279 def _add_version_option(self):
1280 self.add_option("--version",
1282 help=_("show program's version number and exit"))
1284 def _populate_option_list(self, option_list, add_help=True):
1285 if self.standard_option_list:
1286 self.add_options(self.standard_option_list)
1288 self.add_options(option_list)
1290 self._add_version_option()
1292 self._add_help_option()
1294 def _init_parsing_state(self):
1295 # These are set in parse_args() for the convenience of callbacks.
1301 # -- Simple modifier methods ---------------------------------------
1303 def set_usage(self, usage):
1305 self.usage = _("%prog [options]")
1306 elif usage is SUPPRESS_USAGE:
1308 # For backwards compatibility with Optik 1.3 and earlier.
1309 elif string.lower(usage)[:7] == "usage: ":
1310 self.usage = usage[7:]
1314 def enable_interspersed_args(self):
1315 self.allow_interspersed_args = True
1317 def disable_interspersed_args(self):
1318 self.allow_interspersed_args = False
1320 def set_process_default_values(self, process):
1321 self.process_default_values = process
1323 def set_default(self, dest, value):
1324 self.defaults[dest] = value
1326 def set_defaults(self, **kwargs):
1327 self.defaults.update(kwargs)
1329 def _get_all_options(self):
1330 options = self.option_list[:]
1331 for group in self.option_groups:
1332 options.extend(group.option_list)
1335 def get_default_values(self):
1336 if not self.process_default_values:
1337 # Old, pre-Optik 1.5 behaviour.
1338 return Values(self.defaults)
1340 defaults = self.defaults.copy()
1341 for option in self._get_all_options():
1342 default = defaults.get(option.dest)
1343 if isbasestring(default):
1344 opt_str = option.get_opt_string()
1345 defaults[option.dest] = option.check_value(opt_str, default)
1347 return Values(defaults)
1350 # -- OptionGroup methods -------------------------------------------
1352 def add_option_group(self, *args, **kwargs):
1353 # XXX lots of overlap with OptionContainer.add_option()
1354 if type(args[0]) is types.StringType:
1355 group = apply(OptionGroup, (self,) + args, kwargs)
1356 elif len(args) == 1 and not kwargs:
1358 if not isinstance(group, OptionGroup):
1359 raise TypeError, "not an OptionGroup instance: %r" % group
1360 if group.parser is not self:
1361 raise ValueError, "invalid OptionGroup (wrong parser)"
1363 raise TypeError, "invalid arguments"
1365 self.option_groups.append(group)
1368 def get_option_group(self, opt_str):
1369 option = (self._short_opt.get(opt_str) or
1370 self._long_opt.get(opt_str))
1371 if option and option.container is not self:
1372 return option.container
1376 # -- Option-parsing methods ----------------------------------------
1378 def _get_args(self, args):
1382 return args[:] # don't modify caller's list
1384 def parse_args(self, args=None, values=None):
1386 parse_args(args : [string] = sys.argv[1:],
1387 values : Values = None)
1388 -> (values : Values, args : [string])
1390 Parse the command-line options found in 'args' (default:
1391 sys.argv[1:]). Any errors result in a call to 'error()', which
1392 by default prints the usage message to stderr and calls
1393 sys.exit() with an error message. On success returns a pair
1394 (values, args) where 'values' is an Values instance (with all
1395 your option values) and 'args' is the list of arguments left
1396 over after parsing options.
1398 rargs = self._get_args(args)
1400 values = self.get_default_values()
1402 # Store the halves of the argument list as attributes for the
1403 # convenience of callbacks:
1405 # the rest of the command-line (the "r" stands for
1406 # "remaining" or "right-hand")
1408 # the leftover arguments -- ie. what's left after removing
1409 # options and their arguments (the "l" stands for "leftover"
1412 self.largs = largs = []
1413 self.values = values
1416 stop = self._process_args(largs, rargs, values)
1417 except (BadOptionError, OptionValueError), err:
1418 self.error(str(err))
1420 args = largs + rargs
1421 return self.check_values(values, args)
1423 def check_values(self, values, args):
1425 check_values(values : Values, args : [string])
1426 -> (values : Values, args : [string])
1428 Check that the supplied option values and leftover arguments are
1429 valid. Returns the option values and leftover arguments
1430 (possibly adjusted, possibly completely new -- whatever you
1431 like). Default implementation just returns the passed-in
1432 values; subclasses may override as desired.
1434 return (values, args)
1436 def _process_args(self, largs, rargs, values):
1437 """_process_args(largs : [string],
1441 Process command-line arguments and populate 'values', consuming
1442 options and arguments from 'rargs'. If 'allow_interspersed_args' is
1443 false, stop at the first non-option argument. If true, accumulate any
1444 interspersed non-option arguments in 'largs'.
1448 # We handle bare "--" explicitly, and bare "-" is handled by the
1449 # standard arg handler since the short arg case ensures that the
1450 # len of the opt string is greater than 1.
1454 elif arg[0:2] == "--":
1455 # process a single long option (possibly with value(s))
1456 self._process_long_opt(rargs, values)
1457 elif arg[:1] == "-" and len(arg) > 1:
1458 # process a cluster of short options (possibly with
1459 # value(s) for the last one only)
1460 self._process_short_opts(rargs, values)
1461 elif self.allow_interspersed_args:
1465 return # stop now, leave this arg in rargs
1467 # Say this is the original argument list:
1468 # [arg0, arg1, ..., arg(i-1), arg(i), arg(i+1), ..., arg(N-1)]
1470 # (we are about to process arg(i)).
1472 # Then rargs is [arg(i), ..., arg(N-1)] and largs is a *subset* of
1473 # [arg0, ..., arg(i-1)] (any options and their arguments will have
1474 # been removed from largs).
1476 # The while loop will usually consume 1 or more arguments per pass.
1477 # If it consumes 1 (eg. arg is an option that takes no arguments),
1478 # then after _process_arg() is done the situation is:
1480 # largs = subset of [arg0, ..., arg(i)]
1481 # rargs = [arg(i+1), ..., arg(N-1)]
1483 # If allow_interspersed_args is false, largs will always be
1484 # *empty* -- still a subset of [arg0, ..., arg(i-1)], but
1485 # not a very interesting subset!
1487 def _match_long_opt(self, opt):
1488 """_match_long_opt(opt : string) -> string
1490 Determine which long option string 'opt' matches, ie. which one
1491 it is an unambiguous abbrevation for. Raises BadOptionError if
1492 'opt' doesn't unambiguously match any long option string.
1494 return _match_abbrev(opt, self._long_opt)
1496 def _process_long_opt(self, rargs, values):
1499 # Value explicitly attached to arg? Pretend it's the next
1502 (opt, next_arg) = string.split(arg, "=", 1)
1503 rargs.insert(0, next_arg)
1504 had_explicit_value = True
1507 had_explicit_value = False
1509 opt = self._match_long_opt(opt)
1510 option = self._long_opt[opt]
1511 if option.takes_value():
1512 nargs = option.nargs
1513 if len(rargs) < nargs:
1515 self.error(_("%s option requires an argument") % opt)
1517 self.error(_("%s option requires %d arguments")
1520 value = rargs.pop(0)
1522 value = tuple(rargs[0:nargs])
1525 elif had_explicit_value:
1526 self.error(_("%s option does not take a value") % opt)
1531 option.process(opt, value, values, self)
1533 def _process_short_opts(self, rargs, values):
1539 option = self._short_opt.get(opt)
1540 i = i + 1 # we have consumed a character
1543 raise BadOptionError(opt)
1544 if option.takes_value():
1545 # Any characters left in arg? Pretend they're the
1546 # next arg, and stop consuming characters of arg.
1548 rargs.insert(0, arg[i:])
1551 nargs = option.nargs
1552 if len(rargs) < nargs:
1554 self.error(_("%s option requires an argument") % opt)
1556 self.error(_("%s option requires %d arguments")
1559 value = rargs.pop(0)
1561 value = tuple(rargs[0:nargs])
1564 else: # option doesn't take a value
1567 option.process(opt, value, values, self)
1573 # -- Feedback methods ----------------------------------------------
1575 def get_prog_name(self):
1576 if self.prog is None:
1577 return os.path.basename(sys.argv[0])
1581 def expand_prog_name(self, s):
1582 return string.replace(s, "%prog", self.get_prog_name())
1584 def get_description(self):
1585 return self.expand_prog_name(self.description)
1587 def exit(self, status=0, msg=None):
1589 sys.stderr.write(msg)
1592 def error(self, msg):
1593 """error(msg : string)
1595 Print a usage message incorporating 'msg' to stderr and exit.
1596 If you override this in a subclass, it should not return -- it
1597 should either exit or raise an exception.
1599 self.print_usage(sys.stderr)
1600 self.exit(2, "%s: error: %s\n" % (self.get_prog_name(), msg))
1602 def get_usage(self):
1604 return self.formatter.format_usage(
1605 self.expand_prog_name(self.usage))
1609 def print_usage(self, file=None):
1610 """print_usage(file : file = stdout)
1612 Print the usage message for the current program (self.usage) to
1613 'file' (default stdout). Any occurence of the string "%prog" in
1614 self.usage is replaced with the name of the current program
1615 (basename of sys.argv[0]). Does nothing if self.usage is empty
1619 file.write(self.get_usage() + '\n')
1621 def get_version(self):
1623 return self.expand_prog_name(self.version)
1627 def print_version(self, file=None):
1628 """print_version(file : file = stdout)
1630 Print the version message for this program (self.version) to
1631 'file' (default stdout). As with print_usage(), any occurence
1632 of "%prog" in self.version is replaced by the current program's
1633 name. Does nothing if self.version is empty or undefined.
1636 file.write(self.get_version() + '\n')
1638 def format_option_help(self, formatter=None):
1639 if formatter is None:
1640 formatter = self.formatter
1641 formatter.store_option_strings(self)
1643 result.append(formatter.format_heading(_("Options")))
1645 if self.option_list:
1646 result.append(OptionContainer.format_option_help(self, formatter))
1648 for group in self.option_groups:
1649 result.append(group.format_help(formatter))
1652 # Drop the last "\n", or the header if no options or option groups:
1653 return string.join(result[:-1], "")
1655 def format_epilog(self, formatter):
1656 return formatter.format_epilog(self.epilog)
1658 def format_help(self, formatter=None):
1659 if formatter is None:
1660 formatter = self.formatter
1663 result.append(self.get_usage() + "\n")
1664 if self.description:
1665 result.append(self.format_description(formatter) + "\n")
1666 result.append(self.format_option_help(formatter))
1667 result.append(self.format_epilog(formatter))
1668 return string.join(result, "")
1670 # used by test suite
1671 def _get_encoding(self, file):
1672 encoding = getattr(file, "encoding", None)
1674 encoding = sys.getdefaultencoding()
1677 def print_help(self, file=None):
1678 """print_help(file : file = stdout)
1680 Print an extended help message, listing all options and any
1681 help text provided with them, to 'file' (default stdout).
1685 encoding = self._get_encoding(file)
1686 file.write(encode_wrapper(self.format_help(), encoding, "replace"))
1688 # class OptionParser
1691 def _match_abbrev(s, wordmap):
1692 """_match_abbrev(s : string, wordmap : {string : Option}) -> string
1694 Return the string key in 'wordmap' for which 's' is an unambiguous
1695 abbreviation. If 's' is found to be ambiguous or doesn't match any of
1696 'words', raise BadOptionError.
1698 # Is there an exact match?
1699 if wordmap.has_key(s):
1702 # Isolate all words with s as a prefix.
1703 possibilities = filter(lambda w, s=s: w[:len(s)] == s, wordmap.keys())
1704 # No exact match, so there had better be just one possibility.
1705 if len(possibilities) == 1:
1706 return possibilities[0]
1707 elif not possibilities:
1708 raise BadOptionError(s)
1710 # More than one possible completion: ambiguous prefix.
1711 possibilities.sort()
1712 raise AmbiguousOptionError(s, possibilities)
1715 # Some day, there might be many Option classes. As of Optik 1.3, the
1716 # preferred way to instantiate Options is indirectly, via make_option(),
1717 # which will become a factory function when there are many Option
1719 make_option = Option