def _encode(line, output_file, encoding=None):
"""Converts given string to given encoding. If no encoding is specified, it
is determined from terminal settings or, if none, from system settings.
"""
# Convert string to Unicode
if not isinstance(line, text_type):
try:
line = text_type(line)
except UnicodeDecodeError:
line = b(line).decode('utf-8')
# Choose output encoding
if not encoding:
# choose between terminal's and system's preferred encodings
if output_file.isatty():
encoding = getattr(output_file, 'encoding', None)
encoding = encoding or locale.getpreferredencoding()
# Convert string from Unicode to the output encoding
return line.encode(encoding)
def dispatch(parser, argv=None, add_help_command=True, encoding=None,
completion=True, pre_call=None, output_file=sys.stdout,
raw_output=False, namespace=None):
"""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:`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 encoding:
Encoding for results. If `None`, it is determined automatically.
Default is `None`.
: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 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.)
By default the exceptions are not wrapped and will propagate. The only
exception that is always wrapped is :class:`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:`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')
# this will raise SystemExit if parsing fails
args = parser.parse_args(argv, namespace=namespace)
if hasattr(args, 'function'):
if pre_call: # XXX undocumented because I'm unsure if it's OK
pre_call(args)
lines = _execute_command(args)
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
f = BytesIO()
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
output = _encode(line, f, encoding)
output = '' if output is None else output
f.write(output)
if not raw_output:
# in most cases user wants on message per line
f.write(b('\n'))
if output_file is None:
# user wanted a string; return contents of our temporary file-like obj
f.seek(0)
return f.read()
