Skip to content
Back to top
View this page
Edit this page

# 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.'
  name = ''

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

  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.'
  name = ''

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:
    cmd list of str

      Command to be run.

    cls Popen-like

      Class to run the subprocess with.

    stdin file-like

      Popen file descriptor or flag for stdin.

    stdout file-like

      Popen file descriptor or flag for stdout.

    stderr file-like

      Popen file descriptor or flag for stderr.

    universal_newlines bool

      Whether or not to use universal newlines.

    close_fds bool

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

    captured bool or str, optional

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

    env dict

      Replacement environment to run the subporcess in.

  Attributes:
    args list of str

      Arguments as originally supplied.

    alias list of str, callable, or None

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

    binary_loc str or None

      Path to binary to execute.

    is_proxy bool

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

    background bool

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

    threadable bool

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

    pipeline_index int or None

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

    last_in_pipeline bool

      Whether the subprocess is the last in the execution pipeline.

    captured_stdout file-like

      Handle to captured stdin

    captured_stderr file-like

      Handle to captured stderr

    stack list 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.