stdaux.py

##############################################################################
# @file  stdaux.py
# @brief Standard auxiliary functions.
#
# @note The stdaux.py module is automatically created by BASIS from the
#       template file stdaux.py.in which is part of the BASIS installation.
#
# Copyright (c) 2011 University of Pennsylvania. All rights reserved.<br />
# See https://www.cbica.upenn.edu/sbia/software/license.html or COPYING file.
#
# Contact: SBIA Group <sbia-software at uphs.upenn.edu>
#
# @ingroup BasisPythonUtilities
##############################################################################

"""
Standard utility functions.

Copyright (c) 2011 University of Pennsylvania. All rights reserved.
See COPYING file or https://www.rad.upenn.edu/sbia/software/license.html.

Contact: SBIA Group <sbia-software at uphs.upenn.edu>

"""

# ============================================================================
# imports
# ============================================================================

import sys        # system-specific functionality
import subprocess # execution of external command
import shlex      # used to split() quoted command-line
import re         # to see if string contains whitespaces

from sbia.basis.executabletargetinfo import get_executable_path


## @addtogroup BasisPythonUtilities
# @{


# ============================================================================
# version / contact
# ============================================================================

# ----------------------------------------------------------------------------
def print_version(name, copyright=None, license=None):
    """
    Print version information including copyright and license notices.
     
    @param [in] name      Name of executable. Should not be set programmatically
                          to the first argument to the __main__ module.
    @param [in] copyright The copyright notice. If None, the official default
                          copyright is used without year, which is not desired.
                          If an empty string is given, no copyright notice is
                          printed.
    @param [in] license   Information regarding licensing. If None, the official
                          software license of SBIA is used. If an empty string
                          is given, no license information is printed.
    
    """
    # version
    sys.stdout.write(name + " (BASIS) version 1.2.3 (revision 2104)\n")
    # copyright notice
    if not copyright:
        sys.stdout.write("Copyright (c) University of Pennsylvania. All rights reserved.\n")
    elif copyright != "":
        sys.stdout.write(copyright)
        sys.stdout.write('\n')
    # license information
    if not license:
        sys.stdout.write("See https://www.cbica.upenn.edu/sbia/software/license.html or COPYING file.\n")
    elif license != "":
        sys.stdout.write(license)
        sys.stdout.write('\n')

# ----------------------------------------------------------------------------
def print_contact(contact=None):
    """
    Print contact information.
    
    @param [in] contact Name of contact. If None, the default contact of SBIA
                        is used, which is recommended.
    
    """
    sys.stdout.write("Contact:\n  ")
    if not contact:
        sys.stdout.write("SBIA Group <sbia-software at uphs.upenn.edu>")
    else:
        sys.stdout.write(contact)
    sys.stdout.write('\n')

# ============================================================================
# command execution
# ============================================================================

# ----------------------------------------------------------------------------
class SubprocessError(Exception):
    """Exception thrown when command execution failed."""

    def __init__(self, msg):
        """Initialize exception, i.e., set message describing failure."""
        self._message = msg

    def __str__(self):
        """Return string representation of exception message."""
        return self._message

# ----------------------------------------------------------------------------
def execute_process(args, quiet=False, stdout=False, allow_fail=False, verbose=0, simulate=False):
    """
    Execute command as subprocess.
    
    @param [in] args       Command with arguments given either as single quoted
                           string or array of command name and arguments.
                           In the latter case, the array elements are converted
                           to strings using the built-in str() function.
                           Hence, any type which can be converted to a string
                           can be used. The first argument must be the name
                           or path of the executable of the command or the
                           name of the corresponding build target.
    @param [in] quiet      Turns off output of stdout of child process to
                           stdout of parent process.
    @param [in] stdout     Whether to return the command output.
    @param [in] allow_fail If true, does not raise an exception if return
                           value is non-zero. Otherwise, a SubprocessError is
                           raised by this function.
    @param [in] verbose    Verbosity of output messages.
                           Does not affect verbosity of executed command.
    @param [in] simulate   Whether to simulate command execution only.
    
    @return Exit code of executed command. If @p stdout is True, a tuple
            consisting of the exit code and command output is returned.
    
    @throws SubprocessError If command execution failed. This exception is not
                            raised if the command executed with non-zero exit
                            code but @p allow_fail set to True.
    
    """
    # convert args to list of strings
    if type(args) is list:
        args = [str(i) for i in args]
    elif type(args) is str:
        args = shlex.split(args)
    else:
        raise SubprocessError("execute_process(): Argument args must be either list or string")
    if len(args) == 0:
        raise SubprocessError("execute_process(): No command specified")
    # map build target name to executable file path
    path = get_executable_path(args[0])
    if not path:
        raise SubprocessError(args[0] + ': Either unknown build target or command not found')
    args[0] = path
    # some verbose output
    if verbose > 0:
        sys.stdout.write('$')
        re_whitespace = re.compile('\s');
        for arg in args:
            sys.stdout.write(' ')
            if re_whitespace.search(arg):
                sys.stdout.write('"' + arg + '"')
            else:
                sys.stdout.write(arg)
        if simulate:
            sys.stdout.write(" (simulated)")
        sys.stdout.write('\n')
    # execute command
    status = 0
    output = ''
    if not simulate:
        try:
            # open subprocess
            process = subprocess.Popen(args, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
            # read stdout until EOF
            for line in process.stdout:
                if stdout:
                    output = output + line
                if not quiet:
                    print line.rstrip()
                    sys.stdout.flush()
            # wait until subprocess terminated and set exit code
            (out, err) = process.communicate()
            # print error messages of subprocess
            for line in err: sys.stderr.write(line);
            # get exit code
            status = process.returncode
        except OSError, e:
            raise SubprocessError(args[0] + ': ' + str(e))
        except Exception, e:
            msg  = "Exception while executing \"" + args[0] + "\"!\n"
            msg += "\tArguments: " + ' '.join(['"' + i + '"' for i in args[1:]]) + '\n'
            msg += '\t' + str(e)
            raise SubprocessError(msg)
    # if command failed, throw an exception
    if status != 0 and not allow_fail:
        raise SubprocessError("Command " + ' '.join(['"' + i + '"' for i in args[0:]]) + " failed")
    # return
    if stdout:
        return (status, output)
    else:
        return status


## @}
# end of Doxygen group