xpybuild.utils.process

Support functions for invoking processes from targets.

Build file authors should use xpybuild.targets.custom.CustomCommand instead of this module.

defaultProcessOutputEncodingDecider

xpybuild.utils.process.defaultProcessOutputEncodingDecider(context, executable, **forfutureuse)[source]

Function providing the default implementation of the common.processOutputEncodingDecider option, which determines what encoding to use for parsing output from subprocesses.

The default implementation ignores the executable argument and returns the same encoding used by the xpybuild process itself (typically the sys.stdout or system default locale).

A custom function can be provided for this option, using the same signature.

Parameters

  • context – The current BuildContext, which can be used to expand properties. For some targets this may not be set (i.e. None).

  • executable – The full absolute path of the executable producing the output.

  • forfutureuse – Pass through any additional keyword arguments using **forfutureuse.

call

xpybuild.utils.process.call(args, env=None, cwd=None, outputHandler=None, outputEncoding=None, timeout=None, displayName=None, options=None)[source]

Call a process with the specified args, logging stderr and stdout to the specified output handler which will throw an exception if the exit code or output of the process indicates an error.

NB: Consider using the CustomCommand target instead of invoking this directly whenever possible.

Parameters

  • args – The command and arguments to invoke (a list, the first element of which is the executable). None items in this list will be ignored.

  • outputHandler – a ProcessOutputHandler instance, perhaps constructed using the ProcessOutputHandler.create method. If not specified, a default is created based on the supplied options.

  • env – Override the environment the process is started in (defaults to the parent environment)

  • cwd – Change the working directory the process is started in (defaults to the parent cwd)

  • outputEncoding – name of the character encoding the process generates. If specified, this overrides the common.processOutputEncodingDecider option value (see defaultProcessOutputEncodingDecider).

  • timeout – maximum time a process is allowed to run. If an options dictionary is not present, this should ALWAYS be set to a value e.g. options[‘process.timeout’].

  • displayName – human-friendly description of the process for use in error messages, including the target name if possible=

  • options – where possible, always pass in a dictionary of resolved options, which may be used to customize how this function operates.