From 8a09594f57b03fa145267e17761940257554ab29 Mon Sep 17 00:00:00 2001 From: "steven.bethard" Date: Mon, 13 Jul 2009 12:29:35 +0000 Subject: Docstring fixes and additions for better epydoc output. --- argparse.py | 193 +++++++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 125 insertions(+), 68 deletions(-) diff --git a/argparse.py b/argparse.py index fab54e3..9b99712 100644 --- a/argparse.py +++ b/argparse.py @@ -18,12 +18,12 @@ This module is an optparse-inspired command-line parsing library that: -* handles both optional and positional arguments -* produces highly informative usage messages -* supports parsers that dispatch to sub-parsers + - handles both optional and positional arguments + - produces highly informative usage messages + - supports parsers that dispatch to sub-parsers The following is a simple usage example that sums integers from the -command-line and writes the result to a file: +command-line and writes the result to a file:: parser = argparse.ArgumentParser( description='sum the integers at the command line') @@ -39,32 +39,35 @@ command-line and writes the result to a file: The module contains the following public classes: - ArgumentParser -- The main entry point for command-line parsing. As the + - ArgumentParser -- The main entry point for command-line parsing. As the example above shows, the add_argument() method is used to populate the parser with actions for optional and positional arguments. Then the parse_args() method is invoked to convert the args at the command-line into an object with attributes. - ArgumentError -- The exception raised by ArgumentParser objects when + - ArgumentError -- The exception raised by ArgumentParser objects when there are errors with the parser's actions. Errors raised while parsing the command-line are caught by ArgumentParser and emitted as command-line messages. - FileType -- A factory for defining types of files to be created. As the + - FileType -- A factory for defining types of files to be created. As the example above shows, instances of FileType are typically passed as the type= argument of add_argument() calls. - Action -- The base class for parser actions. Typically actions are + - Action -- The base class for parser actions. Typically actions are selected by passing strings like 'store_true' or 'append_const' to the action= argument of add_argument(). However, for greater customization of ArgumentParser actions, subclasses of Action may be defined and passed as the action= argument. - HelpFormatter, RawDescriptionHelpFormatter -- Formatter classes which + - HelpFormatter, RawDescriptionHelpFormatter, RawTextHelpFormatter, + ArgumentDefaultsHelpFormatter -- Formatter classes which may be passed as the formatter_class= argument to the - ArgumentParser constructor. HelpFormatter is the default, while - RawDescriptionHelpFormatter tells the parser not to perform any - line-wrapping on description text. + ArgumentParser constructor. HelpFormatter is the default, + RawDescriptionHelpFormatter and RawTextHelpFormatter tell the parser + not to change the formatting for help text, and + ArgumentDefaultsHelpFormatter adds information about argument defaults + to the help. All other classes in this module are considered implementation details. (Also note that HelpFormatter and RawDescriptionHelpFormatter are only @@ -73,6 +76,18 @@ still considered an implementation detail.) """ __version__ = '0.9.2' +__all__ = [ + 'ArgumentParser', + 'ArgumentError', + 'Namespace', + 'Action', + 'FileType', + 'HelpFormatter', + 'RawDescriptionHelpFormatter', + 'RawTextHelpFormatter' + 'ArgumentDefaultsHelpFormatter', +] + import copy as _copy import os as _os @@ -83,20 +98,20 @@ import textwrap as _textwrap from gettext import gettext as _ try: - set + _set = set except NameError: - from sets import Set as set + from sets import Set as _set try: - basestring + _basestring = basestring except NameError: - basestring = str + _basestring = str try: - sorted + _sorted = sorted except NameError: - def sorted(iterable, reverse=False): + def _sorted(iterable, reverse=False): result = list(iterable) result.sort() if reverse: @@ -118,7 +133,7 @@ PARSER = '==PARSER==' class _AttributeHolder(object): """Abstract base class that provides __repr__. - The __repr__ method returns a string in the format: + The __repr__ method returns a string in the format:: ClassName(attr=name, attr=name, ...) The attributes are determined either by a class-level attribute, '_kwarg_names', or by inspecting the instance __dict__. @@ -134,7 +149,7 @@ class _AttributeHolder(object): return '%s(%s)' % (type_name, ', '.join(arg_strings)) def _get_kwargs(self): - return sorted(self.__dict__.items()) + return _sorted(self.__dict__.items()) def _get_args(self): return [] @@ -151,6 +166,11 @@ def _ensure_value(namespace, name, value): # =============== class HelpFormatter(object): + """Formatter for generating usage messages and argument help strings. + + Only the name of this class is considered a public API. All the methods + provided by the class are considered an implementation detail. + """ def __init__(self, prog, @@ -353,7 +373,7 @@ class HelpFormatter(object): def _format_actions_usage(self, actions, groups): # find group indices and identify actions in groups - group_actions = set() + group_actions = _set() inserts = {} for group in groups: try: @@ -423,7 +443,7 @@ class HelpFormatter(object): parts.append(part) # insert things at the necessary indices - for i in sorted(inserts, reverse=True): + for i in _sorted(inserts, reverse=True): parts[i:i] = [inserts[i]] # join all the action items with spaces @@ -524,6 +544,7 @@ class HelpFormatter(object): result = '{%s}' % ','.join(choice_strs) else: result = default_metavar + def format(tuple_size): if isinstance(result, tuple): return result @@ -583,18 +604,33 @@ class HelpFormatter(object): class RawDescriptionHelpFormatter(HelpFormatter): + """Help message formatter which retains any formatting in descriptions. + + Only the name of this class is considered a public API. All the methods + provided by the class are considered an implementation detail. + """ def _fill_text(self, text, width, indent): return ''.join([indent + line for line in text.splitlines(True)]) class RawTextHelpFormatter(RawDescriptionHelpFormatter): + """Help message formatter which retains formatting of all help text. + + Only the name of this class is considered a public API. All the methods + provided by the class are considered an implementation detail. + """ def _split_lines(self, text, width): return text.splitlines() class ArgumentDefaultsHelpFormatter(HelpFormatter): + """Help message formatter which adds default values to argument help. + + Only the name of this class is considered a public API. All the methods + provided by the class are considered an implementation detail. + """ def _get_help_string(self, action): help = action.help @@ -624,10 +660,7 @@ def _get_action_name(argument): class ArgumentError(Exception): - """ArgumentError(message, argument) - - Raised whenever there was an error creating or using an argument - (optional or positional). + """An error from creating or using an argument (optional or positional). The string value of this exception is the message, augmented with information about the argument that caused it. @@ -650,52 +683,54 @@ class ArgumentError(Exception): # ============== class Action(_AttributeHolder): - """Action(*strings, **options) + """Information about how to convert command line strings to Python objects. - Action objects hold the information necessary to convert a - set of command-line arguments (possibly including an initial option - string) into the desired Python object(s). + Action objects are used by an ArgumentParser to represent the information + needed to parse a single argument from one or more strings from the + command line. The keyword arguments to the Action constructor are also + all attributes of Action instances. Keyword Arguments: - option_strings -- A list of command-line option strings which - should be associated with this action. + - option_strings -- A list of command-line option strings which + should be associated with this action. - dest -- The name of the attribute to hold the created object(s) + - dest -- The name of the attribute to hold the created object(s) - nargs -- The number of command-line arguments that should be consumed. - By default, one argument will be consumed and a single value will - be produced. Other values include: - * N (an integer) consumes N arguments (and produces a list) - * '?' consumes zero or one arguments - * '*' consumes zero or more arguments (and produces a list) - * '+' consumes one or more arguments (and produces a list) - Note that the difference between the default and nargs=1 is that - with the default, a single value will be produced, while with - nargs=1, a list containing a single value will be produced. + - nargs -- The number of command-line arguments that should be + consumed. By default, one argument will be consumed and a single + value will be produced. Other values include: + - N (an integer) consumes N arguments (and produces a list) + - '?' consumes zero or one arguments + - '*' consumes zero or more arguments (and produces a list) + - '+' consumes one or more arguments (and produces a list) + Note that the difference between the default and nargs=1 is that + with the default, a single value will be produced, while with + nargs=1, a list containing a single value will be produced. - const -- The value to be produced if the option is specified and the - option uses an action that takes no values. + - const -- The value to be produced if the option is specified and the + option uses an action that takes no values. - default -- The value to be produced if the option is not specified. + - default -- The value to be produced if the option is not specified. - type -- The type which the command-line arguments should be converted - to, should be one of 'string', 'int', 'float', 'complex' or a - callable object that accepts a single string argument. If None, - 'string' is assumed. + - type -- The type which the command-line arguments should be converted + to, should be one of 'string', 'int', 'float', 'complex' or a + callable object that accepts a single string argument. If None, + 'string' is assumed. - choices -- A container of values that should be allowed. If not None, - after a command-line argument has been converted to the appropriate - type, an exception will be raised if it is not a member of this - collection. + - choices -- A container of values that should be allowed. If not None, + after a command-line argument has been converted to the appropriate + type, an exception will be raised if it is not a member of this + collection. - required -- True if the action must always be specified at the command - line. This is only meaningful for optional command-line arguments. + - required -- True if the action must always be specified at the + command line. This is only meaningful for optional command-line + arguments. - help -- The help string describing the argument. + - help -- The help string describing the argument. - metavar -- The name to be used for the option's argument with the help - string. If None, the 'dest' value will be used as the name. + - metavar -- The name to be used for the option's argument with the + help string. If None, the 'dest' value will be used as the name. """ def __init__(self, @@ -1027,10 +1062,10 @@ class FileType(object): ArgumentParser add_argument() method. Keyword Arguments: - mode -- A string indicating how the file is to be opened. Accepts the - same values as the builtin open() function. - bufsize -- The file's desired buffer size. Accepts the same values as - the builtin open() function. + - mode -- A string indicating how the file is to be opened. Accepts the + same values as the builtin open() function. + - bufsize -- The file's desired buffer size. Accepts the same values as + the builtin open() function. """ def __init__(self, mode='r', bufsize=None): @@ -1064,6 +1099,11 @@ class FileType(object): # =========================== class Namespace(_AttributeHolder): + """Simple object for storing attributes. + + Implements equality by attribute names and values, and provides a simple + string representation. + """ def __init__(self, **kwargs): for name in kwargs: @@ -1280,7 +1320,7 @@ class _ActionsContainer(object): raise ValueError(msg % tup) # error on strings that are all prefix characters - if not (set(option_string) - set(self.prefix_chars)): + if not (_set(option_string) - _set(self.prefix_chars)): msg = _('invalid option string %r: ' 'must contain characters other than %r') tup = option_string, self.prefix_chars @@ -1408,6 +1448,23 @@ class _MutuallyExclusiveGroup(_ArgumentGroup): class ArgumentParser(_AttributeHolder, _ActionsContainer): + """Object for parsing command line strings into Python objects. + + Keyword Arguments: + - prog -- The name of the program (default: sys.argv[0]) + - usage -- A usage message (default: auto-generated from arguments) + - description -- A description of what the program does + - epilog -- Text following the argument descriptions + - version -- Add a -v/--version option with the given version string + - parents -- Parsers whose arguments should be copied into this one + - formatter_class -- HelpFormatter class for printing help messages + - prefix_chars -- Characters that prefix optional arguments + - fromfile_prefix_chars -- Characters that prefix files containing + additional arguments + - argument_default -- The default value for all arguments + - conflict_handler -- String indicating how to handle conflicts + - add_help -- Add a -h/-help option + """ def __init__(self, prog=None, @@ -1558,7 +1615,7 @@ class ArgumentParser(_AttributeHolder, _ActionsContainer): if not hasattr(namespace, action.dest): if action.default is not SUPPRESS: default = action.default - if isinstance(action.default, basestring): + if isinstance(action.default, _basestring): default = self._get_value(action, default) setattr(namespace, action.dest, default) @@ -1618,8 +1675,8 @@ class ArgumentParser(_AttributeHolder, _ActionsContainer): arg_strings_pattern = ''.join(arg_string_pattern_parts) # converts arg strings to the appropriate and then takes the action - seen_actions = set() - seen_non_default_actions = set() + seen_actions = _set() + seen_non_default_actions = _set() def take_action(action, argument_strings, option_string=None): seen_actions.add(action) @@ -2015,7 +2072,7 @@ class ArgumentParser(_AttributeHolder, _ActionsContainer): value = action.const else: value = action.default - if isinstance(value, basestring): + if isinstance(value, _basestring): value = self._get_value(action, value) self._check_value(action, value) -- cgit v1.2.1