xonsh.procs.specs

Subprocess specification and related utilities.

class xonsh.procs.specs.DecoratorAlias

Decorator alias base class.

decorate_spec(spec)

Modify spec immediately after modifier added.

decorate_spec_pre_run(pipeline, spec, spec_num)

Modify spec before run.

descr = 'DecoratorAlias base.'

class xonsh.procs.specs.SpecAttrDecoratorAlias(set_attributes: dict, descr='')

Decorator Alias for spec attributes.

decorate_spec(spec)

Modify spec immediately after modifier added.

decorate_spec_pre_run(pipeline, spec, spec_num)

Modify spec before run.

descr = 'DecoratorAlias base.'

class xonsh.procs.specs.SubprocSpec(cmd, cls=<class 'subprocess.Popen'>, stdin=None, stdout=None, stderr=None, universal_newlines=False, close_fds=False, captured=False, env=None)

A container for specifying how a subprocess command should be executed.

Parameters:

cmdlist of str

Command to be run.

clsPopen-like

Class to run the subprocess with.

stdinfile-like

Popen file descriptor or flag for stdin.

stdoutfile-like

Popen file descriptor or flag for stdout.

stderrfile-like

Popen file descriptor or flag for stderr.

universal_newlinesbool

Whether or not to use universal newlines.

close_fdsbool

Whether or not to close the file descriptors when the process exits.

capturedbool or str, optional

The flag for if the subprocess is captured, may be one of: False for $[], ‘stdout’ for $(), ‘hiddenobject’ for ![], or ‘object’ for !().

envdict

Replacement environment to run the subporcess in.

Attributes:

argslist of str

Arguments as originally supplied.

aliaslist of str, callable, or None

The alias that was resolved for this command, if any.

binary_locstr or None

Path to binary to execute.

is_proxybool

Whether or not the subprocess is or should be run as a proxy.

backgroundbool

Whether or not the subprocess should be started in the background.

threadablebool

Whether or not the subprocess is able to be run in a background thread, rather than the main thread.

pipeline_indexint or None

The index number of this sepc into the pipeline that is being setup.

last_in_pipelinebool

Whether the subprocess is the last in the execution pipeline.

captured_stdoutfile-like

Handle to captured stdin

captured_stderrfile-like

Handle to captured stderr

stacklist of FrameInfo namedtuples or None

The stack of the call-site of alias, if the alias requires it. None otherwise.

classmethod build(cmd, *, cls=<class 'subprocess.Popen'>, **kwargs)

Creates an instance of the subprocess command, with any modifications and adjustments based on the actual cmd that was received.

add_decorator(mod: DecoratorAlias)

Add spec modifier to the specification.

close()

Release any pipe wrappers and channels held by this spec.

Required when a spec is created via cmds_to_specs but never executed (no CommandPipeline._close_proc is invoked). The wrappers from PipeChannel.open_writer/open_reader use closefd=False, so leaving them for GC produces a ResourceWarning: unclosed file on Python 3.12+. Idempotent.

get_command_str()

prep_env_subproc(kwargs)

Prepares the environment to use in the subprocess.

prep_preexec_fn(kwargs, pipeline_group=None)

Prepares the ‘preexec_fn’ keyword argument

resolve_alias()

Resolving alias and setting up command.

resolve_alias_cls()

Determine which proxy class to run an alias with.

resolve_args_list()

Weave a list of arguments into a command.

resolve_auto_cd()

Implements AUTO_CD functionality.

resolve_binary_loc()

Sets the binary location

resolve_decorators()

Apply decorators.

resolve_executable_commands()

Resolve command executables, if applicable.

resolve_redirects()

Manages redirects.

resolve_stack()

Computes the stack for a callable alias’s call-site, if needed.

run(*, pipeline_group=None)

Launches the subprocess and returns the object.

kwnames = ('stdin', 'stdout', 'stderr', 'universal_newlines', 'close_fds')

property stderr

property stdin

property stdout

xonsh.procs.specs.cmds_to_specs(cmds, captured=False, envs=None, in_boolop=False)

Converts a list of cmds to a list of SubprocSpec objects that are ready to be executed.

in_boolop is propagated from the parser; it is True when the whole pipeline is a direct operand of a &&/|| chain. Each spec gets the flag stored on it so downstream code (e.g. CommandPipeline, _raise_subproc_error) can decide whether to short-circuit on returncode or raise.

xonsh.procs.specs.default_signal_pauser(n, f)

Pauses a signal, as needed.

xonsh.procs.specs.get_script_subproc_command(fname, args)

Given the name of a script outside the path, returns a list representing an appropriate subprocess command to execute the script or None if the argument is not readable or not a script. Raises PermissionError if the script is not executable.

xonsh.procs.specs.is_app_execution_alias(fname)

App execution aliases behave strangly on Windows and Python. Here we try to detect if a file is an app execution alias.

xonsh.procs.specs.no_pg_xonsh_preexec_fn()

Default subprocess preexec function for when there is no existing pipeline group.

xonsh.procs.specs.parse_shebang_from_file(filepath)

Returns shebang for a file or None. Doc: https://www.gnu.org/software/guile/manual/html_node/The-Meta-Switch.html

xonsh.procs.specs.run_subproc(cmds, captured=False, envs=None, in_boolop=False)

Runs a subprocess, in its many forms. This takes a list of ‘commands,’ which may be a list of command line arguments or a string, representing a special connecting character. For example:

$ ls | grep wakka

is represented by the following cmds:

[['ls'], '|', ['grep', 'wakka']]

Lastly, the captured argument affects only the last real command.

in_boolop is forwarded from the parser; True when this whole pipeline is a direct operand of a &&/|| chain. Each spec receives spec.in_boolop so downstream consumers can act on it (e.g. let a non-zero return short-circuit instead of raising).

xonsh.procs.specs.safe_close(x)

Safely attempts to close an object.

xonsh.procs.specs.safe_open(fname, mode, buffering=-1)

Safely attempts to open a file in for xonsh subprocs.