def dispatch(parser, argv=None, add_help_command=True,
completion=True, pre_call=None,
output_file=sys.stdout, errors_file=sys.stderr,
raw_output=False, namespace=None,
skip_unknown_args=False):
"""
Parses given list of arguments using given parser, calls the relevant
function and prints the result.
The target function should expect one positional argument: the
:class:`argparse.Namespace` object. However, if the function is decorated with
:func:`~argh.decorators.plain_signature`, the positional and named
arguments from the namespace object are passed to the function instead
of the object itself.
:param parser:
the ArgumentParser instance.
:param argv:
a list of strings representing the arguments. If `None`, ``sys.argv``
is used instead. Default is `None`.
:param add_help_command:
if `True`, converts first positional argument "help" to a keyword
argument so that ``help foo`` becomes ``foo --help`` and displays usage
information for "foo". Default is `True`.
:param output_file:
A file-like object for output. If `None`, the resulting lines are
collected and returned as a string. Default is ``sys.stdout``.
:param errors_file:
Same as `output_file` but for ``sys.stderr``.
:param raw_output:
If `True`, results are written to the output file raw, without adding
whitespaces or newlines between yielded strings. Default is `False`.
:param completion:
If `True`, shell tab completion is enabled. Default is `True`. (You
will also need to install it.) See :mod:`argh.completion`.
:param skip_unknown_args:
If `True`, unknown arguments do not cause an error
(`ArgumentParser.parse_known_args` is used).
:param namespace:
An `argparse.Namespace`-like object. By default an
:class:`ArghNamespace` object is used. Please note that support for
combined default and nested functions may be broken if a different
type of object is forced.
By default the exceptions are not wrapped and will propagate. The only
exception that is always wrapped is :class:`~argh.exceptions.CommandError`
which is interpreted as an expected event so the traceback is hidden.
You can also mark arbitrary exceptions as "wrappable" by using the
:func:`~argh.decorators.wrap_errors` decorator.
"""
if completion:
autocomplete(parser)
if argv is None:
argv = sys.argv[1:]
if add_help_command:
if argv and argv[0] == 'help':
argv.pop(0)
argv.append('--help')
if skip_unknown_args:
parse_args = parser.parse_known_args
else:
parse_args = parser.parse_args
if not namespace:
namespace = ArghNamespace()
# this will raise SystemExit if parsing fails
namespace_obj = parse_args(argv, namespace=namespace)
function = _get_function_from_namespace_obj(namespace_obj)
if function:
lines = _execute_command(function, namespace_obj, errors_file,
pre_call=pre_call)
else:
# no commands declared, can't dispatch; display help message
lines = [parser.format_usage()]
if output_file is None:
# user wants a string; we create an internal temporary file-like object
# and will return its contents as a string
if sys.version_info < (3,0):
f = compat.BytesIO()
else:
f = compat.StringIO()
else:
# normally this is stdout; can be any file
f = output_file
for line in lines:
# print the line as soon as it is generated to ensure that it is
# displayed to the user before anything else happens, e.g.
# raw_input() is called
io.dump(line, f)
if not raw_output:
# in most cases user wants one message per line
io.dump('\n', f)
if output_file is None:
# user wanted a string; return contents of our temporary file-like obj
f.seek(0)
return f.read()
def autocomplete(self):
"Wrapper for :func:`~argh.completion.autocomplete`."
return autocomplete(self)
def dispatch(parser,
argv=None,
add_help_command=True,
completion=True,
pre_call=None,
output_file=sys.stdout,
errors_file=sys.stderr,
raw_output=False,
namespace=None,
skip_unknown_args=False):
"""
Parses given list of arguments using given parser, calls the relevant
function and prints the result.
The target function should expect one positional argument: the
:class:`argparse.Namespace` object. However, if the function is decorated with
:func:`~argh.decorators.plain_signature`, the positional and named
arguments from the namespace object are passed to the function instead
of the object itself.
:param parser:
the ArgumentParser instance.
:param argv:
a list of strings representing the arguments. If `None`, ``sys.argv``
is used instead. Default is `None`.
:param add_help_command:
if `True`, converts first positional argument "help" to a keyword
argument so that ``help foo`` becomes ``foo --help`` and displays usage
information for "foo". Default is `True`.
:param output_file:
A file-like object for output. If `None`, the resulting lines are
collected and returned as a string. Default is ``sys.stdout``.
:param errors_file:
Same as `output_file` but for ``sys.stderr``.
:param raw_output:
If `True`, results are written to the output file raw, without adding
whitespaces or newlines between yielded strings. Default is `False`.
:param completion:
If `True`, shell tab completion is enabled. Default is `True`. (You
will also need to install it.) See :mod:`argh.completion`.
:param skip_unknown_args:
If `True`, unknown arguments do not cause an error
(`ArgumentParser.parse_known_args` is used).
:param namespace:
An `argparse.Namespace`-like object. By default an
:class:`ArghNamespace` object is used. Please note that support for
combined default and nested functions may be broken if a different
type of object is forced.
By default the exceptions are not wrapped and will propagate. The only
exception that is always wrapped is :class:`~argh.exceptions.CommandError`
which is interpreted as an expected event so the traceback is hidden.
You can also mark arbitrary exceptions as "wrappable" by using the
:func:`~argh.decorators.wrap_errors` decorator.
"""
if completion:
autocomplete(parser)
if argv is None:
argv = sys.argv[1:]
if add_help_command:
if argv and argv[0] == 'help':
argv.pop(0)
argv.append('--help')
if skip_unknown_args:
parse_args = parser.parse_known_args
else:
parse_args = parser.parse_args
if not namespace:
namespace = ArghNamespace()
# this will raise SystemExit if parsing fails
namespace_obj = parse_args(argv, namespace=namespace)
function = _get_function_from_namespace_obj(namespace_obj)
if function:
lines = _execute_command(function,
namespace_obj,
errors_file,
pre_call=pre_call)
else:
# no commands declared, can't dispatch; display help message
lines = [parser.format_usage()]
if output_file is None:
# user wants a string; we create an internal temporary file-like object
# and will return its contents as a string
if sys.version_info < (3, 0):
f = compat.BytesIO()
else:
f = compat.StringIO()
else:
# normally this is stdout; can be any file
f = output_file
for line in lines:
# print the line as soon as it is generated to ensure that it is
# displayed to the user before anything else happens, e.g.
# raw_input() is called
io.dump(line, f)
if not raw_output:
# in most cases user wants one message per line
io.dump('\n', f)
if output_file is None:
# user wanted a string; return contents of our temporary file-like obj
f.seek(0)
return f.read()
