# The software in this package is distributed under the GNU General
# Public License version 2 (with a special exception described below).
#
# A copy of GNU General Public License (GPL) is included in this distribution,
# in the file COPYING.GPL.
#
# As a special exception, if other files instantiate templates or use macros
# or inline functions from this file, or you compile this file and link it
# with other works to produce a work based on this file, this file
# does not by itself cause the resulting work to be covered
# by the GNU General Public License.
#
# However the source code for this file must still be made available
# in accordance with section (3) of the GNU General Public License.
#
# This exception does not invalidate any other reasons why a work based
# on this file might be covered by the GNU General Public License.
#
# Copyright (c) 2016-2018 Intra2net AG <info@intra2net.com>

"""
Helpers for calling commands, capture their output, return result code.

Subprocess library did not provide all the simplicity we would have liked.
However, this has since changed, so consider using the easy-to-use builtin
functions :py:func:`subprocess.run` or :py:func:`subprocess.call` instead.
"""

from subprocess import Popen, PIPE


def call_and_capture(command, stdin_data=None, split_lines=True,
                     *args, **kwargs):
    """ call command, captures stdout, stderr and return code, return when done

    Use only for commands with little output since all output has to be
    buffered!
    Quoting :py:mod:`subprocess`:

    ..note:: The data read is buffered in memory, so do not use this method if
             the data size is large or unlimited.

    Forwards all args to Popen constructor, except:
    stdout=PIPE (forced, ignored if in kwargs)
    stderr=PIPE (forced, ignored if in kwargs)
    shell=False (except if set in kwargs)
    universal_newlines=True (except if set in kwargs)

    :param command: forwarded as first arg to Popen constructor
    :param str stdin_data: forwarded to stdin of process through communicate
    :param bool split_lines: True (default) to split output line-wise and
                             return list of strings; False --> return single
                             string for out and one for err
    :param args: forwarded to Popen constructor
    :param kwargs: forwarded to Popen constructor
    :returns: (return_code, stdout, stderr); stdout and stderr are lists of
        text lines (without terminating newlines); if universal_newlines is
        True (default), the lines are of type str, otherwise they are non-
        unicode text (type bytes). If split_lines is False (not default),
        then stdout and stderr are single multi-line strings

    :raise: OSError (e.g., if command does not exist), ValueError if args are
            invalid; no :py:class:`subprocess.CalledProcessError` nor
            :py:class:`subprocess.TimeoutExpired`
    """

    # construct args
    enforced_params = ('stdout', 'stderr')
    my_kwargs = dict(stdout=PIPE, stderr=PIPE,
                     shell=False, universal_newlines=True)
    for key, value in kwargs.items():
        if key not in enforced_params:
            my_kwargs[key] = value

    # run command
    proc = Popen(command, *args, **my_kwargs)
    stdout_data, stderr_data = proc.communicate(stdin_data)

    # return
    if split_lines:
        return proc.returncode, stdout_data.splitlines(), \
            stderr_data.splitlines()
    else:
        return proc.returncode, stdout_data, stderr_data