def parse_args(self, args_list):
"""Parse given arguments and return options and positional arguments.
Arguments must be given as a list and are typically sys.argv[1:].
Options are retuned as a dictionary where long options are keys. Value
is a string for those options that can be given only one time (if they
are given multiple times the last value is used) or None if the option
is not used at all. Value for options that can be given multiple times
(denoted with '*' in the usage) is a list which contains all the given
values and is empty if options are not used. Options not taken
arguments have value False when they are not set and True otherwise.
Positional arguments are returned as a list in the order they are given.
If 'check_args' is True, this method will automatically check that
correct number of arguments, as parsed from the usage line, are given.
If the last argument in the usage line ends with the character 's',
the maximum number of arguments is infinite.
Possible errors in processing arguments are reported using DataError.
Some options have a special meaning and are handled automatically
if defined in the usage and given from the command line:
--escape option can be used to automatically unescape problematic
characters given in an escaped format.
--argumentfile can be used to automatically read arguments from
a specified file. When --argumentfile is used, the parser always
allows using it multiple times. Adding '*' to denote that is thus
recommend. A special value 'stdin' can be used to read arguments from
stdin instead of a file.
--pythonpath can be used to add extra path(s) to sys.path.
--help and --version automatically generate help and version messages.
Version is generated based on the tool name and version -- see __init__
for information how to set them. Help contains the whole usage given to
__init__. Possible <VERSION> text in the usage is replaced with the
given version. Possible <--ESCAPES--> is replaced with available
escapes so that they are wrapped to multiple lines but take the same
amount of horizontal space as <---ESCAPES--->. Both help and version
are wrapped to Information exception.
"""
args_list = [decode_from_file_system(a) for a in args_list]
args_list = self._process_possible_argfile(args_list)
opts, args = self._parse_args(args_list)
opts, args = self._handle_special_options(opts, args)
self._arg_limit_validator(args)
if self._validator:
opts, args = self._validator(opts, args)
return opts, args
def abspath(path):
"""Replacement for os.path.abspath with some bug fixes and enhancements.
1) Converts non-Unicode paths to Unicode using file system encoding
2) At least Jython 2.5.1 on Windows returns wrong path with 'c:'.
3) Python until 2.6.5 and at least Jython 2.5.1 don't handle non-ASCII
characters in the working directory: http://bugs.python.org/issue3426
"""
if not isinstance(path, unicode):
path = decode_from_file_system(path)
if os.sep == '\\' and len(path) == 2 and path[1] == ':':
return path + '\\'
return os.path.normpath(os.path.join(os.getcwdu(), path))
def parse_args(
self, args_list, unescape=None, argfile=None, pythonpath=None, help=None, version=None, check_args=False
):
"""Parse given arguments and return options and positional arguments.
Arguments must be given as a list and are typically sys.argv[1:].
Options are retuned as a dictionary where long options are keys. Value
is a string for those options that can be given only one time (if they
are given multiple times the last value is used) or None if the option
is not used at all. Value for options that can be given multiple times
(denoted with '*' in the usage) is a list which contains all the given
values and is empty if options are not used. Options not taken
arguments have value False when they are not set and True otherwise.
Positional arguments are returned as a list in the order they are given.
'unescape' option can be used to automatically unescape problematic
characters given in an escaped format. Given value must be the name of
the long option used for escaping. Typically usage is having
'--escape name:value *' in usage doc and specifying 'enescape="escape"'
when calling this method.
'argfile' can be used to automatically read arguments from specified
file. Given value must be the name of the long option used for giving
the argument file. Typical usage is '--argumentfile path *' in usage doc
and calling this method with 'argfile="argumentfile"'. If 'argfile' is
used, it can always be given multiple times and thus it is recommended
to use '*' to denote that. Special value 'stdin' can be used to read
arguments from stdin instead of a file.
'pythonpath' can be used to specify option(s) containing extra paths to
be added into 'sys.path'. Value can be either a string containing the
name of the long option used for this purpose or a list containing
all such long options (i.e. the latter format allows aliases).
'help' and 'version' make it possible to automatically generate help
and version messages. Version is generated based on the tool name
and version -- see __init__ for information how to set them. Help
contains the whole usage given to __init__. Possible <VERSION> text
in the usage is replaced with the given version. Possible <--ESCAPES-->
is replaced with available escapes so that they are wrapped to multiple
lines but take the same amount of horizontal space as <---ESCAPES--->.
The numer of hyphens can be used to contrl the horizontal space. Both
help and version are wrapped to Information exception.
If 'check_args' is True, this method will automatically check that
correct number of arguments, as parsed from the usage line, are given.
If the last argument in the usage line ends with the character 's',
the maximum number of arguments is infinite.
Possible errors in processing arguments are reported using DataError.
"""
args_list = [decode_from_file_system(a) for a in args_list]
if argfile:
args_list = self._add_args_from_file(args_list, argfile)
opts, args = self._parse_args(args_list)
if unescape:
opts, args = self._unescape_opts_and_args(opts, args, unescape)
if help and opts[help]:
self._raise_help()
if version and opts[version]:
self._raise_version()
if pythonpath:
sys.path = self._get_pythonpath(opts[pythonpath]) + sys.path
if check_args:
self._check_args(args)
return opts, args
