1 """A powerful, extensible, and easy-to-use option parser.
3 By Greg Ward <gward@python.net>
5 Originally distributed as Optik.
7 For support, use the optik-users@lists.sourceforge.net mailing list
8 (http://lists.sourceforge.net/lists/listinfo/optik-users).
22 'IndentedHelpFormatter',
23 'TitledHelpFormatter',
26 'OptionConflictError',
31 Copyright (c) 2001-2006 Gregory P. Ward. All rights reserved.
32 Copyright (c) 2002-2006 Python Software Foundation. All rights reserved.
34 Redistribution and use in source and binary forms, with or without
35 modification, are permitted provided that the following conditions are
38 * Redistributions of source code must retain the above copyright
39 notice, this list of conditions and the following disclaimer.
41 * Redistributions in binary form must reproduce the above copyright
42 notice, this list of conditions and the following disclaimer in the
43 documentation and/or other materials provided with the distribution.
45 * Neither the name of the author nor the names of its
46 contributors may be used to endorse or promote products derived from
47 this software without specific prior written permission.
49 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
50 IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
51 TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
52 PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR
53 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
54 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
55 PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
56 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
57 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
58 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
59 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
67 return "<%s at 0x%x: %s>" % (self
.__class
__.__name
__, id(self
), self
)
70 # This file was generated from:
71 # Id: option_parser.py 527 2006-07-23 15:21:30Z greg
72 # Id: option.py 522 2006-06-11 16:22:03Z gward
73 # Id: help.py 527 2006-07-23 15:21:30Z greg
74 # Id: errors.py 509 2006-04-20 00:58:24Z gward
77 from gettext
import gettext
84 class OptParseError (Exception):
85 def __init__(self
, msg
):
92 class OptionError (OptParseError
):
94 Raised if an Option instance is created with invalid or
95 inconsistent arguments.
98 def __init__(self
, msg
, option
):
100 self
.option_id
= str(option
)
104 return "option %s: %s" % (self
.option_id
, self
.msg
)
108 class OptionConflictError (OptionError
):
110 Raised if conflicting options are added to an OptionParser.
113 class OptionValueError (OptParseError
):
115 Raised if an invalid option value is encountered on the command
119 class BadOptionError (OptParseError
):
121 Raised if an invalid option is seen on the command line.
123 def __init__(self
, opt_str
):
124 self
.opt_str
= opt_str
127 return _("no such option: %s") % self
.opt_str
129 class AmbiguousOptionError (BadOptionError
):
131 Raised if an ambiguous option is seen on the command line.
133 def __init__(self
, opt_str
, possibilities
):
134 BadOptionError
.__init
__(self
, opt_str
)
135 self
.possibilities
= possibilities
138 return (_("ambiguous option: %s (%s?)")
139 % (self
.opt_str
, ", ".join(self
.possibilities
)))
145 Abstract base class for formatting option help. OptionParser
146 instances should use one of the HelpFormatter subclasses for
147 formatting help; by default IndentedHelpFormatter is used.
150 parser : OptionParser
151 the controlling OptionParser instance
152 indent_increment : int
153 the number of columns to indent per nesting level
154 max_help_position : int
155 the maximum starting column for option help text
157 the calculated starting column for option help text;
158 initially the same as the maximum
160 total number of columns for output (pass None to constructor for
161 this value to be taken from the $COLUMNS environment variable)
163 current indentation level
165 current indentation level (in columns)
167 number of columns available for option help text (calculated)
169 text to replace with each option's default value, "%default"
170 by default. Set to false value to disable default value expansion.
171 option_strings : { Option : str }
172 maps Option instances to the snippet of help text explaining
173 the syntax of that option, e.g. "-h, --help" or
174 "-fFILE, --file=FILE"
176 format string controlling how short options with values are
177 printed in help text. Must be either "%s%s" ("-fFILE") or
178 "%s %s" ("-f FILE"), because those are the two syntaxes that
181 similar but for long options; must be either "%s %s" ("--file FILE")
182 or "%s=%s" ("--file=FILE").
185 NO_DEFAULT_VALUE
= "none"
193 self
.indent_increment
= indent_increment
194 self
.help_position
= self
.max_help_position
= max_help_position
197 width
= int(os
.environ
['COLUMNS'])
198 except (KeyError, ValueError):
202 self
.current_indent
= 0
204 self
.help_width
= None # computed later
205 self
.short_first
= short_first
206 self
.default_tag
= "%default"
207 self
.option_strings
= {}
208 self
._short
_opt
_fmt
= "%s %s"
209 self
._long
_opt
_fmt
= "%s=%s"
211 def set_parser(self
, parser
):
214 def set_short_opt_delimiter(self
, delim
):
215 if delim
not in ("", " "):
217 "invalid metavar delimiter for short options: %r" % delim
)
218 self
._short
_opt
_fmt
= "%s" + delim
+ "%s"
220 def set_long_opt_delimiter(self
, delim
):
221 if delim
not in ("=", " "):
223 "invalid metavar delimiter for long options: %r" % delim
)
224 self
._long
_opt
_fmt
= "%s" + delim
+ "%s"
227 self
.current_indent
+= self
.indent_increment
231 self
.current_indent
-= self
.indent_increment
232 assert self
.current_indent
>= 0, "Indent decreased below 0."
235 def format_usage(self
, usage
):
236 raise NotImplementedError, "subclasses must implement"
238 def format_heading(self
, heading
):
239 raise NotImplementedError, "subclasses must implement"
241 def _format_text(self
, text
):
243 Format a paragraph of free-form text for inclusion in the
244 help output at the current indentation level.
246 text_width
= self
.width
- self
.current_indent
247 indent
= " "*self
.current_indent
248 return textwrap
.fill(text
,
250 initial_indent
=indent
,
251 subsequent_indent
=indent
)
253 def format_description(self
, description
):
255 return self
._format
_text
(description
) + "\n"
259 def format_epilog(self
, epilog
):
261 return "\n" + self
._format
_text
(epilog
) + "\n"
266 def expand_default(self
, option
):
267 if self
.parser
is None or not self
.default_tag
:
270 default_value
= self
.parser
.defaults
.get(option
.dest
)
271 if default_value
is NO_DEFAULT
or default_value
is None:
272 default_value
= self
.NO_DEFAULT_VALUE
274 return option
.help.replace(self
.default_tag
, str(default_value
))
276 def format_option(self
, option
):
277 # The help for each option consists of two parts:
278 # * the opt strings and metavars
279 # eg. ("-x", or "-fFILENAME, --file=FILENAME")
280 # * the user-supplied help string
281 # eg. ("turn on expert mode", "read data from FILENAME")
283 # If possible, we write both of these on the same line:
284 # -x turn on expert mode
286 # But if the opt string list is too long, we put the help
287 # string on a second line, indented to the same column it would
288 # start in if it fit on the first line.
289 # -fFILENAME, --file=FILENAME
290 # read data from FILENAME
292 opts
= self
.option_strings
[option
]
293 opt_width
= self
.help_position
- self
.current_indent
- 2
294 if len(opts
) > opt_width
:
295 opts
= "%*s%s\n" % (self
.current_indent
, "", opts
)
296 indent_first
= self
.help_position
297 else: # start help on same line as opts
298 opts
= "%*s%-*s " % (self
.current_indent
, "", opt_width
, opts
)
302 help_text
= self
.expand_default(option
)
303 help_lines
= textwrap
.wrap(help_text
, self
.help_width
)
304 result
.append("%*s%s\n" % (indent_first
, "", help_lines
[0]))
305 result
.extend(["%*s%s\n" % (self
.help_position
, "", line
)
306 for line
in help_lines
[1:]])
307 elif opts
[-1] != "\n":
309 return "".join(result
)
311 def store_option_strings(self
, parser
):
314 for opt
in parser
.option_list
:
315 strings
= self
.format_option_strings(opt
)
316 self
.option_strings
[opt
] = strings
317 max_len
= max(max_len
, len(strings
) + self
.current_indent
)
319 for group
in parser
.option_groups
:
320 for opt
in group
.option_list
:
321 strings
= self
.format_option_strings(opt
)
322 self
.option_strings
[opt
] = strings
323 max_len
= max(max_len
, len(strings
) + self
.current_indent
)
326 self
.help_position
= min(max_len
+ 2, self
.max_help_position
)
327 self
.help_width
= self
.width
- self
.help_position
329 def format_option_strings(self
, option
):
330 """Return a comma-separated list of option strings & metavariables."""
331 if option
.takes_value():
332 metavar
= option
.metavar
or option
.dest
.upper()
333 short_opts
= [self
._short
_opt
_fmt
% (sopt
, metavar
)
334 for sopt
in option
._short
_opts
]
335 long_opts
= [self
._long
_opt
_fmt
% (lopt
, metavar
)
336 for lopt
in option
._long
_opts
]
338 short_opts
= option
._short
_opts
339 long_opts
= option
._long
_opts
342 opts
= short_opts
+ long_opts
344 opts
= long_opts
+ short_opts
346 return ", ".join(opts
)
348 class IndentedHelpFormatter (HelpFormatter
):
349 """Format help with indented section bodies.
354 max_help_position
=24,
357 HelpFormatter
.__init
__(
358 self
, indent_increment
, max_help_position
, width
, short_first
)
360 def format_usage(self
, usage
):
361 return _("Usage: %s\n") % usage
363 def format_heading(self
, heading
):
364 return "%*s%s:\n" % (self
.current_indent
, "", heading
)
367 class TitledHelpFormatter (HelpFormatter
):
368 """Format help with underlined section headers.
373 max_help_position
=24,
376 HelpFormatter
.__init
__ (
377 self
, indent_increment
, max_help_position
, width
, short_first
)
379 def format_usage(self
, usage
):
380 return "%s %s\n" % (self
.format_heading(_("Usage")), usage
)
382 def format_heading(self
, heading
):
383 return "%s\n%s\n" % (heading
, "=-"[self
.level
] * len(heading
))
386 def _parse_num(val
, type):
387 if val
[:2].lower() == "0x": # hexadecimal
389 elif val
[:2].lower() == "0b": # binary
391 val
= val
[2:] or "0" # have to remove "0b" prefix
392 elif val
[:1] == "0": # octal
397 return type(val
, radix
)
400 return _parse_num(val
, int)
402 def _parse_long(val
):
403 return _parse_num(val
, long)
405 _builtin_cvt
= { "int" : (_parse_int
, _("integer")),
406 "long" : (_parse_long
, _("long integer")),
407 "float" : (float, _("floating-point")),
408 "complex" : (complex, _("complex")) }
410 def check_builtin(option
, opt
, value
):
411 (cvt
, what
) = _builtin_cvt
[option
.type]
415 raise OptionValueError(
416 _("option %s: invalid %s value: %r") % (opt
, what
, value
))
418 def check_choice(option
, opt
, value
):
419 if value
in option
.choices
:
422 choices
= ", ".join(map(repr, option
.choices
))
423 raise OptionValueError(
424 _("option %s: invalid choice: %r (choose from %s)")
425 % (opt
, value
, choices
))
427 # Not supplying a default is different from a default of None,
428 # so we need an explicit "not supplied" value.
429 NO_DEFAULT
= ("NO", "DEFAULT")
435 _short_opts : [string]
436 _long_opts : [string]
446 callback_args : (any*)
447 callback_kwargs : { string : any }
452 # The list of instance attributes that may be set through
453 # keyword args to the constructor.
467 # The set of actions allowed by option parsers. Explicitly listed
468 # here so the constructor can validate its arguments.
480 # The set of actions that involve storing a value somewhere;
481 # also listed just for constructor argument validation. (If
482 # the action is one of these, there must be a destination.)
483 STORE_ACTIONS
= ("store",
491 # The set of actions for which it makes sense to supply a value
492 # type, ie. which may consume an argument from the command line.
493 TYPED_ACTIONS
= ("store",
497 # The set of actions which *require* a value type, ie. that
498 # always consume an argument from the command line.
499 ALWAYS_TYPED_ACTIONS
= ("store",
502 # The set of actions which take a 'const' attribute.
503 CONST_ACTIONS
= ("store_const",
506 # The set of known types for option parsers. Again, listed here for
507 # constructor argument validation.
508 TYPES
= ("string", "int", "long", "float", "complex", "choice")
510 # Dictionary of argument checking functions, which convert and
511 # validate option arguments according to the option type.
513 # Signature of checking functions is:
514 # check(option : Option, opt : string, value : string) -> any
516 # option is the Option instance calling the checker
517 # opt is the actual option seen on the command-line
518 # (eg. "-a", "--file")
519 # value is the option argument seen on the command-line
521 # The return value should be in the appropriate Python type
522 # for option.type -- eg. an integer if option.type == "int".
524 # If no checker is defined for a type, arguments will be
525 # unchecked and remain strings.
526 TYPE_CHECKER
= { "int" : check_builtin
,
527 "long" : check_builtin
,
528 "float" : check_builtin
,
529 "complex": check_builtin
,
530 "choice" : check_choice
,
534 # CHECK_METHODS is a list of unbound method objects; they are called
535 # by the constructor, in order, after all attributes are
536 # initialized. The list is created and filled in later, after all
537 # the methods are actually defined. (I just put it here because I
538 # like to define and document all class attributes in the same
539 # place.) Subclasses that add another _check_*() method should
540 # define their own CHECK_METHODS list that adds their check method
541 # to those from this class.
545 # -- Constructor/initialization methods ----------------------------
547 def __init__(self
, *opts
, **attrs
):
548 # Set _short_opts, _long_opts attrs from 'opts' tuple.
549 # Have to be set now, in case no option strings are supplied.
550 self
._short
_opts
= []
552 opts
= self
._check
_opt
_strings
(opts
)
553 self
._set
_opt
_strings
(opts
)
555 # Set all other attrs (action, type, etc.) from 'attrs' dict
556 self
._set
_attrs
(attrs
)
558 # Check all the attributes we just set. There are lots of
559 # complicated interdependencies, but luckily they can be farmed
560 # out to the _check_*() methods listed in CHECK_METHODS -- which
561 # could be handy for subclasses! The one thing these all share
562 # is that they raise OptionError if they discover a problem.
563 for checker
in self
.CHECK_METHODS
:
566 def _check_opt_strings(self
, opts
):
567 # Filter out None because early versions of Optik had exactly
568 # one short option and one long option, either of which
570 opts
= filter(None, opts
)
572 raise TypeError("at least one option string must be supplied")
575 def _set_opt_strings(self
, opts
):
579 "invalid option string %r: "
580 "must be at least two characters long" % opt
, self
)
582 if not (opt
[0] == "-" and opt
[1] != "-"):
584 "invalid short option string %r: "
585 "must be of the form -x, (x any non-dash char)" % opt
,
587 self
._short
_opts
.append(opt
)
589 if not (opt
[0:2] == "--" and opt
[2] != "-"):
591 "invalid long option string %r: "
592 "must start with --, followed by non-dash" % opt
,
594 self
._long
_opts
.append(opt
)
596 def _set_attrs(self
, attrs
):
597 for attr
in self
.ATTRS
:
599 setattr(self
, attr
, attrs
[attr
])
602 if attr
== 'default':
603 setattr(self
, attr
, NO_DEFAULT
)
605 setattr(self
, attr
, None)
610 "invalid keyword arguments: %s" % ", ".join(attrs
),
614 # -- Constructor validation methods --------------------------------
616 def _check_action(self
):
617 if self
.action
is None:
618 self
.action
= "store"
619 elif self
.action
not in self
.ACTIONS
:
620 raise OptionError("invalid action: %r" % self
.action
, self
)
622 def _check_type(self
):
623 if self
.type is None:
624 if self
.action
in self
.ALWAYS_TYPED_ACTIONS
:
625 if self
.choices
is not None:
626 # The "choices" attribute implies "choice" type.
629 # No type given? "string" is the most sensible default.
632 # Allow type objects or builtin type conversion functions
633 # (int, str, etc.) as an alternative to their names. (The
634 # complicated check of __builtin__ is only necessary for
635 # Python 2.1 and earlier, and is short-circuited by the
636 # first check on modern Pythons.)
638 if ( type(self
.type) is types
.TypeType
or
639 (hasattr(self
.type, "__name__") and
640 getattr(__builtin__
, self
.type.__name
__, None) is self
.type) ):
641 self
.type = self
.type.__name
__
643 if self
.type == "str":
646 if self
.type not in self
.TYPES
:
647 raise OptionError("invalid option type: %r" % self
.type, self
)
648 if self
.action
not in self
.TYPED_ACTIONS
:
650 "must not supply a type for action %r" % self
.action
, self
)
652 def _check_choice(self
):
653 if self
.type == "choice":
654 if self
.choices
is None:
656 "must supply a list of choices for type 'choice'", self
)
657 elif type(self
.choices
) not in (types
.TupleType
, types
.ListType
):
659 "choices must be a list of strings ('%s' supplied)"
660 % str(type(self
.choices
)).split("'")[1], self
)
661 elif self
.choices
is not None:
663 "must not supply choices for type %r" % self
.type, self
)
665 def _check_dest(self
):
666 # No destination given, and we need one for this action. The
667 # self.type check is for callbacks that take a value.
668 takes_value
= (self
.action
in self
.STORE_ACTIONS
or
669 self
.type is not None)
670 if self
.dest
is None and takes_value
:
672 # Glean a destination from the first long option string,
673 # or from the first short option string if no long options.
675 # eg. "--foo-bar" -> "foo_bar"
676 self
.dest
= self
._long
_opts
[0][2:].replace('-', '_')
678 self
.dest
= self
._short
_opts
[0][1]
680 def _check_const(self
):
681 if self
.action
not in self
.CONST_ACTIONS
and self
.const
is not None:
683 "'const' must not be supplied for action %r" % self
.action
,
686 def _check_nargs(self
):
687 if self
.action
in self
.TYPED_ACTIONS
:
688 if self
.nargs
is None:
690 elif self
.nargs
is not None:
692 "'nargs' must not be supplied for action %r" % self
.action
,
695 def _check_callback(self
):
696 if self
.action
== "callback":
697 if not hasattr(self
.callback
, '__call__'):
699 "callback not callable: %r" % self
.callback
, self
)
700 if (self
.callback_args
is not None and
701 type(self
.callback_args
) is not types
.TupleType
):
703 "callback_args, if supplied, must be a tuple: not %r"
704 % self
.callback_args
, self
)
705 if (self
.callback_kwargs
is not None and
706 type(self
.callback_kwargs
) is not types
.DictType
):
708 "callback_kwargs, if supplied, must be a dict: not %r"
709 % self
.callback_kwargs
, self
)
711 if self
.callback
is not None:
713 "callback supplied (%r) for non-callback option"
714 % self
.callback
, self
)
715 if self
.callback_args
is not None:
717 "callback_args supplied for non-callback option", self
)
718 if self
.callback_kwargs
is not None:
720 "callback_kwargs supplied for non-callback option", self
)
723 CHECK_METHODS
= [_check_action
,
732 # -- Miscellaneous methods -----------------------------------------
735 return "/".join(self
._short
_opts
+ self
._long
_opts
)
739 def takes_value(self
):
740 return self
.type is not None
742 def get_opt_string(self
):
744 return self
._long
_opts
[0]
746 return self
._short
_opts
[0]
749 # -- Processing methods --------------------------------------------
751 def check_value(self
, opt
, value
):
752 checker
= self
.TYPE_CHECKER
.get(self
.type)
756 return checker(self
, opt
, value
)
758 def convert_value(self
, opt
, value
):
759 if value
is not None:
761 return self
.check_value(opt
, value
)
763 return tuple([self
.check_value(opt
, v
) for v
in value
])
765 def process(self
, opt
, value
, values
, parser
):
767 # First, convert the value(s) to the right type. Howl if any
768 # value(s) are bogus.
769 value
= self
.convert_value(opt
, value
)
771 # And then take whatever action is expected of us.
772 # This is a separate method to make life easier for
773 # subclasses to add new actions.
774 return self
.take_action(
775 self
.action
, self
.dest
, opt
, value
, values
, parser
)
777 def take_action(self
, action
, dest
, opt
, value
, values
, parser
):
778 if action
== "store":
779 setattr(values
, dest
, value
)
780 elif action
== "store_const":
781 setattr(values
, dest
, self
.const
)
782 elif action
== "store_true":
783 setattr(values
, dest
, True)
784 elif action
== "store_false":
785 setattr(values
, dest
, False)
786 elif action
== "append":
787 values
.ensure_value(dest
, []).append(value
)
788 elif action
== "append_const":
789 values
.ensure_value(dest
, []).append(self
.const
)
790 elif action
== "count":
791 setattr(values
, dest
, values
.ensure_value(dest
, 0) + 1)
792 elif action
== "callback":
793 args
= self
.callback_args
or ()
794 kwargs
= self
.callback_kwargs
or {}
795 self
.callback(self
, opt
, value
, parser
, *args
, **kwargs
)
796 elif action
== "help":
799 elif action
== "version":
800 parser
.print_version()
803 raise ValueError("unknown action %r" % self
.action
)
810 SUPPRESS_HELP
= "SUPPRESS"+"HELP"
811 SUPPRESS_USAGE
= "SUPPRESS"+"USAGE"
817 return isinstance(x
, (types
.StringType
, types
.UnicodeType
))
820 return isinstance(x
, basestring
)
824 def __init__(self
, defaults
=None):
826 for (attr
, val
) in defaults
.items():
827 setattr(self
, attr
, val
)
830 return str(self
.__dict
__)
834 def __cmp__(self
, other
):
835 if isinstance(other
, Values
):
836 return cmp(self
.__dict
__, other
.__dict
__)
837 elif isinstance(other
, types
.DictType
):
838 return cmp(self
.__dict
__, other
)
842 def _update_careful(self
, dict):
844 Update the option values from an arbitrary dictionary, but only
845 use keys from dict that already have a corresponding attribute
846 in self. Any keys in dict without a corresponding attribute
847 are silently ignored.
849 for attr
in dir(self
):
853 setattr(self
, attr
, dval
)
855 def _update_loose(self
, dict):
857 Update the option values from an arbitrary dictionary,
858 using all keys from the dictionary regardless of whether
859 they have a corresponding attribute in self or not.
861 self
.__dict
__.update(dict)
863 def _update(self
, dict, mode
):
864 if mode
== "careful":
865 self
._update
_careful
(dict)
866 elif mode
== "loose":
867 self
._update
_loose
(dict)
869 raise ValueError, "invalid update mode: %r" % mode
871 def read_module(self
, modname
, mode
="careful"):
873 mod
= sys
.modules
[modname
]
874 self
._update
(vars(mod
), mode
)
876 def read_file(self
, filename
, mode
="careful"):
878 execfile(filename
, vars)
879 self
._update
(vars, mode
)
881 def ensure_value(self
, attr
, value
):
882 if not hasattr(self
, attr
) or getattr(self
, attr
) is None:
883 setattr(self
, attr
, value
)
884 return getattr(self
, attr
)
887 class OptionContainer
:
893 standard_option_list : [Option]
894 list of standard options that will be accepted by all instances
895 of this parser class (intended to be overridden by subclasses).
898 option_list : [Option]
899 the list of Option objects contained by this OptionContainer
900 _short_opt : { string : Option }
901 dictionary mapping short option strings, eg. "-f" or "-X",
902 to the Option instances that implement them. If an Option
903 has multiple short option strings, it will appears in this
904 dictionary multiple times. [1]
905 _long_opt : { string : Option }
906 dictionary mapping long option strings, eg. "--file" or
907 "--exclude", to the Option instances that implement them.
908 Again, a given Option can occur multiple times in this
910 defaults : { string : any }
911 dictionary mapping option destination names to default
912 values for each destination [1]
914 [1] These mappings are common to (shared by) all components of the
915 controlling OptionParser, where they are initially created.
919 def __init__(self
, option_class
, conflict_handler
, description
):
920 # Initialize the option list and related data structures.
921 # This method must be provided by subclasses, and it must
922 # initialize at least the following instance attributes:
923 # option_list, _short_opt, _long_opt, defaults.
924 self
._create
_option
_list
()
926 self
.option_class
= option_class
927 self
.set_conflict_handler(conflict_handler
)
928 self
.set_description(description
)
930 def _create_option_mappings(self
):
931 # For use by OptionParser constructor -- create the master
932 # option mappings used by this OptionParser and all
933 # OptionGroups that it owns.
934 self
._short
_opt
= {} # single letter -> Option instance
935 self
._long
_opt
= {} # long option -> Option instance
936 self
.defaults
= {} # maps option dest -> default value
939 def _share_option_mappings(self
, parser
):
940 # For use by OptionGroup constructor -- use shared option
941 # mappings from the OptionParser that owns this OptionGroup.
942 self
._short
_opt
= parser
._short
_opt
943 self
._long
_opt
= parser
._long
_opt
944 self
.defaults
= parser
.defaults
946 def set_conflict_handler(self
, handler
):
947 if handler
not in ("error", "resolve"):
948 raise ValueError, "invalid conflict_resolution value %r" % handler
949 self
.conflict_handler
= handler
951 def set_description(self
, description
):
952 self
.description
= description
954 def get_description(self
):
955 return self
.description
959 """see OptionParser.destroy()."""
965 # -- Option-adding methods -----------------------------------------
967 def _check_conflict(self
, option
):
969 for opt
in option
._short
_opts
:
970 if opt
in self
._short
_opt
:
971 conflict_opts
.append((opt
, self
._short
_opt
[opt
]))
972 for opt
in option
._long
_opts
:
973 if opt
in self
._long
_opt
:
974 conflict_opts
.append((opt
, self
._long
_opt
[opt
]))
977 handler
= self
.conflict_handler
978 if handler
== "error":
979 raise OptionConflictError(
980 "conflicting option string(s): %s"
981 % ", ".join([co
[0] for co
in conflict_opts
]),
983 elif handler
== "resolve":
984 for (opt
, c_option
) in conflict_opts
:
985 if opt
.startswith("--"):
986 c_option
._long
_opts
.remove(opt
)
987 del self
._long
_opt
[opt
]
989 c_option
._short
_opts
.remove(opt
)
990 del self
._short
_opt
[opt
]
991 if not (c_option
._short
_opts
or c_option
._long
_opts
):
992 c_option
.container
.option_list
.remove(c_option
)
994 def add_option(self
, *args
, **kwargs
):
995 """add_option(Option)
996 add_option(opt_str, ..., kwarg=val, ...)
998 if type(args
[0]) is types
.StringType
:
999 option
= self
.option_class(*args
, **kwargs
)
1000 elif len(args
) == 1 and not kwargs
:
1002 if not isinstance(option
, Option
):
1003 raise TypeError, "not an Option instance: %r" % option
1005 raise TypeError, "invalid arguments"
1007 self
._check
_conflict
(option
)
1009 self
.option_list
.append(option
)
1010 option
.container
= self
1011 for opt
in option
._short
_opts
:
1012 self
._short
_opt
[opt
] = option
1013 for opt
in option
._long
_opts
:
1014 self
._long
_opt
[opt
] = option
1016 if option
.dest
is not None: # option has a dest, we need a default
1017 if option
.default
is not NO_DEFAULT
:
1018 self
.defaults
[option
.dest
] = option
.default
1019 elif option
.dest
not in self
.defaults
:
1020 self
.defaults
[option
.dest
] = None
1024 def add_options(self
, option_list
):
1025 for option
in option_list
:
1026 self
.add_option(option
)
1028 # -- Option query/removal methods ----------------------------------
1030 def get_option(self
, opt_str
):
1031 return (self
._short
_opt
.get(opt_str
) or
1032 self
._long
_opt
.get(opt_str
))
1034 def has_option(self
, opt_str
):
1035 return (opt_str
in self
._short
_opt
or
1036 opt_str
in self
._long
_opt
)
1038 def remove_option(self
, opt_str
):
1039 option
= self
._short
_opt
.get(opt_str
)
1041 option
= self
._long
_opt
.get(opt_str
)
1043 raise ValueError("no such option %r" % opt_str
)
1045 for opt
in option
._short
_opts
:
1046 del self
._short
_opt
[opt
]
1047 for opt
in option
._long
_opts
:
1048 del self
._long
_opt
[opt
]
1049 option
.container
.option_list
.remove(option
)
1052 # -- Help-formatting methods ---------------------------------------
1054 def format_option_help(self
, formatter
):
1055 if not self
.option_list
:
1058 for option
in self
.option_list
:
1059 if not option
.help is SUPPRESS_HELP
:
1060 result
.append(formatter
.format_option(option
))
1061 return "".join(result
)
1063 def format_description(self
, formatter
):
1064 return formatter
.format_description(self
.get_description())
1066 def format_help(self
, formatter
):
1068 if self
.description
:
1069 result
.append(self
.format_description(formatter
))
1070 if self
.option_list
:
1071 result
.append(self
.format_option_help(formatter
))
1072 return "\n".join(result
)
1075 class OptionGroup (OptionContainer
):
1077 def __init__(self
, parser
, title
, description
=None):
1078 self
.parser
= parser
1079 OptionContainer
.__init
__(
1080 self
, parser
.option_class
, parser
.conflict_handler
, description
)
1083 def _create_option_list(self
):
1084 self
.option_list
= []
1085 self
._share
_option
_mappings
(self
.parser
)
1087 def set_title(self
, title
):
1091 """see OptionParser.destroy()."""
1092 OptionContainer
.destroy(self
)
1093 del self
.option_list
1095 # -- Help-formatting methods ---------------------------------------
1097 def format_help(self
, formatter
):
1098 result
= formatter
.format_heading(self
.title
)
1100 result
+= OptionContainer
.format_help(self
, formatter
)
1105 class OptionParser (OptionContainer
):
1109 standard_option_list : [Option]
1110 list of standard options that will be accepted by all instances
1111 of this parser class (intended to be overridden by subclasses).
1113 Instance attributes:
1115 a usage string for your program. Before it is displayed
1116 to the user, "%prog" will be expanded to the name of
1117 your program (self.prog or os.path.basename(sys.argv[0])).
1119 the name of the current program (to override
1120 os.path.basename(sys.argv[0])).
1122 paragraph of help text to print after option help
1124 option_groups : [OptionGroup]
1125 list of option groups in this parser (option groups are
1126 irrelevant for parsing the command-line, but very useful
1127 for generating help)
1129 allow_interspersed_args : bool = true
1130 if true, positional arguments may be interspersed with options.
1131 Assuming -a and -b each take a single argument, the command-line
1132 -ablah foo bar -bboo baz
1133 will be interpreted the same as
1134 -ablah -bboo -- foo bar baz
1135 If this flag were false, that command line would be interpreted as
1136 -ablah -- foo bar -bboo baz
1137 -- ie. we stop processing options as soon as we see the first
1138 non-option argument. (This is the tradition followed by
1139 Python's getopt module, Perl's Getopt::Std, and other argument-
1140 parsing libraries, but it is generally annoying to users.)
1142 process_default_values : bool = true
1143 if true, option default values are processed similarly to option
1144 values from the command line: that is, they are passed to the
1145 type-checking function for the option's type (as long as the
1146 default value is a string). (This really only matters if you
1147 have defined custom types; see SF bug #955889.) Set it to false
1148 to restore the behaviour of Optik 1.4.1 and earlier.
1151 the argument list currently being parsed. Only set when
1152 parse_args() is active, and continually trimmed down as
1153 we consume arguments. Mainly there for the benefit of
1156 the list of leftover arguments that we have skipped while
1157 parsing options. If allow_interspersed_args is false, this
1158 list is always empty.
1160 the set of option values currently being accumulated. Only
1161 set when parse_args() is active. Also mainly for callbacks.
1163 Because of the 'rargs', 'largs', and 'values' attributes,
1164 OptionParser is not thread-safe. If, for some perverse reason, you
1165 need to parse command-line arguments simultaneously in different
1166 threads, use different OptionParser instances.
1170 standard_option_list
= []
1175 option_class
=Option
,
1177 conflict_handler
="error",
1180 add_help_option
=True,
1183 OptionContainer
.__init
__(
1184 self
, option_class
, conflict_handler
, description
)
1185 self
.set_usage(usage
)
1187 self
.version
= version
1188 self
.allow_interspersed_args
= True
1189 self
.process_default_values
= True
1190 if formatter
is None:
1191 formatter
= IndentedHelpFormatter()
1192 self
.formatter
= formatter
1193 self
.formatter
.set_parser(self
)
1194 self
.epilog
= epilog
1196 # Populate the option list; initial sources are the
1197 # standard_option_list class attribute, the 'option_list'
1198 # argument, and (if applicable) the _add_version_option() and
1199 # _add_help_option() methods.
1200 self
._populate
_option
_list
(option_list
,
1201 add_help
=add_help_option
)
1203 self
._init
_parsing
_state
()
1208 Declare that you are done with this OptionParser. This cleans up
1209 reference cycles so the OptionParser (and all objects referenced by
1210 it) can be garbage-collected promptly. After calling destroy(), the
1211 OptionParser is unusable.
1213 OptionContainer
.destroy(self
)
1214 for group
in self
.option_groups
:
1216 del self
.option_list
1217 del self
.option_groups
1221 # -- Private methods -----------------------------------------------
1222 # (used by our or OptionContainer's constructor)
1224 def _create_option_list(self
):
1225 self
.option_list
= []
1226 self
.option_groups
= []
1227 self
._create
_option
_mappings
()
1229 def _add_help_option(self
):
1230 self
.add_option("-h", "--help",
1232 help=_("show this help message and exit"))
1234 def _add_version_option(self
):
1235 self
.add_option("--version",
1237 help=_("show program's version number and exit"))
1239 def _populate_option_list(self
, option_list
, add_help
=True):
1240 if self
.standard_option_list
:
1241 self
.add_options(self
.standard_option_list
)
1243 self
.add_options(option_list
)
1245 self
._add
_version
_option
()
1247 self
._add
_help
_option
()
1249 def _init_parsing_state(self
):
1250 # These are set in parse_args() for the convenience of callbacks.
1256 # -- Simple modifier methods ---------------------------------------
1258 def set_usage(self
, usage
):
1260 self
.usage
= _("%prog [options]")
1261 elif usage
is SUPPRESS_USAGE
:
1263 # For backwards compatibility with Optik 1.3 and earlier.
1264 elif usage
.lower().startswith("usage: "):
1265 self
.usage
= usage
[7:]
1269 def enable_interspersed_args(self
):
1270 """Set parsing to not stop on the first non-option, allowing
1271 interspersing switches with command arguments. This is the
1272 default behavior. See also disable_interspersed_args() and the
1273 class documentation description of the attribute
1274 allow_interspersed_args."""
1275 self
.allow_interspersed_args
= True
1277 def disable_interspersed_args(self
):
1278 """Set parsing to stop on the first non-option. Use this if
1279 you have a command processor which runs another command that
1280 has options of its own and you want to make sure these options
1283 self
.allow_interspersed_args
= False
1285 def set_process_default_values(self
, process
):
1286 self
.process_default_values
= process
1288 def set_default(self
, dest
, value
):
1289 self
.defaults
[dest
] = value
1291 def set_defaults(self
, **kwargs
):
1292 self
.defaults
.update(kwargs
)
1294 def _get_all_options(self
):
1295 options
= self
.option_list
[:]
1296 for group
in self
.option_groups
:
1297 options
.extend(group
.option_list
)
1300 def get_default_values(self
):
1301 if not self
.process_default_values
:
1302 # Old, pre-Optik 1.5 behaviour.
1303 return Values(self
.defaults
)
1305 defaults
= self
.defaults
.copy()
1306 for option
in self
._get
_all
_options
():
1307 default
= defaults
.get(option
.dest
)
1308 if isbasestring(default
):
1309 opt_str
= option
.get_opt_string()
1310 defaults
[option
.dest
] = option
.check_value(opt_str
, default
)
1312 return Values(defaults
)
1315 # -- OptionGroup methods -------------------------------------------
1317 def add_option_group(self
, *args
, **kwargs
):
1318 # XXX lots of overlap with OptionContainer.add_option()
1319 if type(args
[0]) is types
.StringType
:
1320 group
= OptionGroup(self
, *args
, **kwargs
)
1321 elif len(args
) == 1 and not kwargs
:
1323 if not isinstance(group
, OptionGroup
):
1324 raise TypeError, "not an OptionGroup instance: %r" % group
1325 if group
.parser
is not self
:
1326 raise ValueError, "invalid OptionGroup (wrong parser)"
1328 raise TypeError, "invalid arguments"
1330 self
.option_groups
.append(group
)
1333 def get_option_group(self
, opt_str
):
1334 option
= (self
._short
_opt
.get(opt_str
) or
1335 self
._long
_opt
.get(opt_str
))
1336 if option
and option
.container
is not self
:
1337 return option
.container
1341 # -- Option-parsing methods ----------------------------------------
1343 def _get_args(self
, args
):
1347 return args
[:] # don't modify caller's list
1349 def parse_args(self
, args
=None, values
=None):
1351 parse_args(args : [string] = sys.argv[1:],
1352 values : Values = None)
1353 -> (values : Values, args : [string])
1355 Parse the command-line options found in 'args' (default:
1356 sys.argv[1:]). Any errors result in a call to 'error()', which
1357 by default prints the usage message to stderr and calls
1358 sys.exit() with an error message. On success returns a pair
1359 (values, args) where 'values' is an Values instance (with all
1360 your option values) and 'args' is the list of arguments left
1361 over after parsing options.
1363 rargs
= self
._get
_args
(args
)
1365 values
= self
.get_default_values()
1367 # Store the halves of the argument list as attributes for the
1368 # convenience of callbacks:
1370 # the rest of the command-line (the "r" stands for
1371 # "remaining" or "right-hand")
1373 # the leftover arguments -- ie. what's left after removing
1374 # options and their arguments (the "l" stands for "leftover"
1377 self
.largs
= largs
= []
1378 self
.values
= values
1381 stop
= self
._process
_args
(largs
, rargs
, values
)
1382 except (BadOptionError
, OptionValueError
), err
:
1383 self
.error(str(err
))
1385 args
= largs
+ rargs
1386 return self
.check_values(values
, args
)
1388 def check_values(self
, values
, args
):
1390 check_values(values : Values, args : [string])
1391 -> (values : Values, args : [string])
1393 Check that the supplied option values and leftover arguments are
1394 valid. Returns the option values and leftover arguments
1395 (possibly adjusted, possibly completely new -- whatever you
1396 like). Default implementation just returns the passed-in
1397 values; subclasses may override as desired.
1399 return (values
, args
)
1401 def _process_args(self
, largs
, rargs
, values
):
1402 """_process_args(largs : [string],
1406 Process command-line arguments and populate 'values', consuming
1407 options and arguments from 'rargs'. If 'allow_interspersed_args' is
1408 false, stop at the first non-option argument. If true, accumulate any
1409 interspersed non-option arguments in 'largs'.
1413 # We handle bare "--" explicitly, and bare "-" is handled by the
1414 # standard arg handler since the short arg case ensures that the
1415 # len of the opt string is greater than 1.
1419 elif arg
[0:2] == "--":
1420 # process a single long option (possibly with value(s))
1421 self
._process
_long
_opt
(rargs
, values
)
1422 elif arg
[:1] == "-" and len(arg
) > 1:
1423 # process a cluster of short options (possibly with
1424 # value(s) for the last one only)
1425 self
._process
_short
_opts
(rargs
, values
)
1426 elif self
.allow_interspersed_args
:
1430 return # stop now, leave this arg in rargs
1432 # Say this is the original argument list:
1433 # [arg0, arg1, ..., arg(i-1), arg(i), arg(i+1), ..., arg(N-1)]
1435 # (we are about to process arg(i)).
1437 # Then rargs is [arg(i), ..., arg(N-1)] and largs is a *subset* of
1438 # [arg0, ..., arg(i-1)] (any options and their arguments will have
1439 # been removed from largs).
1441 # The while loop will usually consume 1 or more arguments per pass.
1442 # If it consumes 1 (eg. arg is an option that takes no arguments),
1443 # then after _process_arg() is done the situation is:
1445 # largs = subset of [arg0, ..., arg(i)]
1446 # rargs = [arg(i+1), ..., arg(N-1)]
1448 # If allow_interspersed_args is false, largs will always be
1449 # *empty* -- still a subset of [arg0, ..., arg(i-1)], but
1450 # not a very interesting subset!
1452 def _match_long_opt(self
, opt
):
1453 """_match_long_opt(opt : string) -> string
1455 Determine which long option string 'opt' matches, ie. which one
1456 it is an unambiguous abbrevation for. Raises BadOptionError if
1457 'opt' doesn't unambiguously match any long option string.
1459 return _match_abbrev(opt
, self
._long
_opt
)
1461 def _process_long_opt(self
, rargs
, values
):
1464 # Value explicitly attached to arg? Pretend it's the next
1467 (opt
, next_arg
) = arg
.split("=", 1)
1468 rargs
.insert(0, next_arg
)
1469 had_explicit_value
= True
1472 had_explicit_value
= False
1474 opt
= self
._match
_long
_opt
(opt
)
1475 option
= self
._long
_opt
[opt
]
1476 if option
.takes_value():
1477 nargs
= option
.nargs
1478 if len(rargs
) < nargs
:
1480 self
.error(_("%s option requires an argument") % opt
)
1482 self
.error(_("%s option requires %d arguments")
1485 value
= rargs
.pop(0)
1487 value
= tuple(rargs
[0:nargs
])
1490 elif had_explicit_value
:
1491 self
.error(_("%s option does not take a value") % opt
)
1496 option
.process(opt
, value
, values
, self
)
1498 def _process_short_opts(self
, rargs
, values
):
1504 option
= self
._short
_opt
.get(opt
)
1505 i
+= 1 # we have consumed a character
1508 raise BadOptionError(opt
)
1509 if option
.takes_value():
1510 # Any characters left in arg? Pretend they're the
1511 # next arg, and stop consuming characters of arg.
1513 rargs
.insert(0, arg
[i
:])
1516 nargs
= option
.nargs
1517 if len(rargs
) < nargs
:
1519 self
.error(_("%s option requires an argument") % opt
)
1521 self
.error(_("%s option requires %d arguments")
1524 value
= rargs
.pop(0)
1526 value
= tuple(rargs
[0:nargs
])
1529 else: # option doesn't take a value
1532 option
.process(opt
, value
, values
, self
)
1538 # -- Feedback methods ----------------------------------------------
1540 def get_prog_name(self
):
1541 if self
.prog
is None:
1542 return os
.path
.basename(sys
.argv
[0])
1546 def expand_prog_name(self
, s
):
1547 return s
.replace("%prog", self
.get_prog_name())
1549 def get_description(self
):
1550 return self
.expand_prog_name(self
.description
)
1552 def exit(self
, status
=0, msg
=None):
1554 sys
.stderr
.write(msg
)
1557 def error(self
, msg
):
1558 """error(msg : string)
1560 Print a usage message incorporating 'msg' to stderr and exit.
1561 If you override this in a subclass, it should not return -- it
1562 should either exit or raise an exception.
1564 self
.print_usage(sys
.stderr
)
1565 self
.exit(2, "%s: error: %s\n" % (self
.get_prog_name(), msg
))
1567 def get_usage(self
):
1569 return self
.formatter
.format_usage(
1570 self
.expand_prog_name(self
.usage
))
1574 def print_usage(self
, file=None):
1575 """print_usage(file : file = stdout)
1577 Print the usage message for the current program (self.usage) to
1578 'file' (default stdout). Any occurrence of the string "%prog" in
1579 self.usage is replaced with the name of the current program
1580 (basename of sys.argv[0]). Does nothing if self.usage is empty
1584 print >>file, self
.get_usage()
1586 def get_version(self
):
1588 return self
.expand_prog_name(self
.version
)
1592 def print_version(self
, file=None):
1593 """print_version(file : file = stdout)
1595 Print the version message for this program (self.version) to
1596 'file' (default stdout). As with print_usage(), any occurrence
1597 of "%prog" in self.version is replaced by the current program's
1598 name. Does nothing if self.version is empty or undefined.
1601 print >>file, self
.get_version()
1603 def format_option_help(self
, formatter
=None):
1604 if formatter
is None:
1605 formatter
= self
.formatter
1606 formatter
.store_option_strings(self
)
1608 result
.append(formatter
.format_heading(_("Options")))
1610 if self
.option_list
:
1611 result
.append(OptionContainer
.format_option_help(self
, formatter
))
1613 for group
in self
.option_groups
:
1614 result
.append(group
.format_help(formatter
))
1617 # Drop the last "\n", or the header if no options or option groups:
1618 return "".join(result
[:-1])
1620 def format_epilog(self
, formatter
):
1621 return formatter
.format_epilog(self
.epilog
)
1623 def format_help(self
, formatter
=None):
1624 if formatter
is None:
1625 formatter
= self
.formatter
1628 result
.append(self
.get_usage() + "\n")
1629 if self
.description
:
1630 result
.append(self
.format_description(formatter
) + "\n")
1631 result
.append(self
.format_option_help(formatter
))
1632 result
.append(self
.format_epilog(formatter
))
1633 return "".join(result
)
1635 # used by test suite
1636 def _get_encoding(self
, file):
1637 encoding
= getattr(file, "encoding", None)
1639 encoding
= sys
.getdefaultencoding()
1642 def print_help(self
, file=None):
1643 """print_help(file : file = stdout)
1645 Print an extended help message, listing all options and any
1646 help text provided with them, to 'file' (default stdout).
1650 encoding
= self
._get
_encoding
(file)
1651 file.write(self
.format_help().encode(encoding
, "replace"))
1653 # class OptionParser
1656 def _match_abbrev(s
, wordmap
):
1657 """_match_abbrev(s : string, wordmap : {string : Option}) -> string
1659 Return the string key in 'wordmap' for which 's' is an unambiguous
1660 abbreviation. If 's' is found to be ambiguous or doesn't match any of
1661 'words', raise BadOptionError.
1663 # Is there an exact match?
1667 # Isolate all words with s as a prefix.
1668 possibilities
= [word
for word
in wordmap
.keys()
1669 if word
.startswith(s
)]
1670 # No exact match, so there had better be just one possibility.
1671 if len(possibilities
) == 1:
1672 return possibilities
[0]
1673 elif not possibilities
:
1674 raise BadOptionError(s
)
1676 # More than one possible completion: ambiguous prefix.
1677 possibilities
.sort()
1678 raise AmbiguousOptionError(s
, possibilities
)
1681 # Some day, there might be many Option classes. As of Optik 1.3, the
1682 # preferred way to instantiate Options is indirectly, via make_option(),
1683 # which will become a factory function when there are many Option
1685 make_option
= Option