Built-Ins (xonsh.built_ins)

The xonsh built-ins.

Note that this module is named ‘built_ins’ so as not to be confused with the special Python builtins module.

class xonsh.built_ins.DeprecationWarningProxy(oldname, newname)[source]

Proxies access, but warns in the process.

warn()[source]

Issues deprecation warning.

obj

Dynamically grabs object

class xonsh.built_ins.DynamicAccessProxy(refname, objname)[source]

Proxies access dynamically.

Parameters:
refname : str

‘.’-separated string that represents the new, reference name that the user will access.

objname : str

‘.’-separated string that represents the name where the target object actually lives that refname points to.

obj

Dynamically grabs object

class xonsh.built_ins.SubprocSpec(cmd, *, cls=<class 'subprocess.Popen'>, stdin=None, stdout=None, stderr=None, universal_newlines=False, captured=False)[source]

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.

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 !().

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)[source]

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

prep_env(kwargs)[source]

Prepares the environment to use in the subprocess.

prep_preexec_fn(kwargs, pipeline_group=None)[source]

Prepares the ‘preexec_fn’ keyword argument

redirect_leading()[source]

Manage leading redirects such as with ‘< input.txt COMMAND’.

redirect_trailing()[source]

Manages trailing redirects.

resolve_alias()[source]

Sets alias in command, if applicable.

resolve_alias_cls()[source]

Determine which proxy class to run an alias with.

resolve_auto_cd()[source]

Implements AUTO_CD functionality.

resolve_binary_loc()[source]

Sets the binary location

resolve_executable_commands()[source]

Resolve command executables, if applicable.

resolve_stack()[source]

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

run(*, pipeline_group=None)[source]

Launches the subprocess and returns the object.

kwnames = ('stdin', 'stdout', 'stderr', 'universal_newlines')
stderr
stdin
stdout
class xonsh.built_ins.XonshSession(execer=None, ctx=None)[source]

All components defining a xonsh session.

execer : Execer, optional
Xonsh execution object, may be None to start
ctx : Mapping, optional
Context to start xonsh session with.
load(execer=None, ctx=None)[source]

Loads the session with default values.

execer : Execer, optional
Xonsh execution object, may be None to start
ctx : Mapping, optional
Context to start xonsh session with.
xonsh.built_ins.call_macro(f, raw_args, glbs, locs)[source]

Calls a function as a macro, returning its result.

Parameters:
f : callable object

The function that is called as f(*args).

raw_args : tuple of str

The str representation of arguments of that were passed into the macro. These strings will be parsed, compiled, evaled, or left as a string depending on the annotations of f.

glbs : Mapping

The globals from the call site.

locs : Mapping or None

The locals from the call site.

xonsh.built_ins.cmds_to_specs(cmds, captured=False)[source]

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

xonsh.built_ins.convert_macro_arg(raw_arg, kind, glbs, locs, *, name='<arg>', macroname='<macro>')[source]

Converts a string macro argument based on the requested kind.

Parameters:
raw_arg : str

The str representation of the macro argument.

kind : object

A flag or type representing how to convert the argument.

glbs : Mapping

The globals from the call site.

locs : Mapping or None

The locals from the call site.

name : str, optional

The macro argument name.

macroname : str, optional

The name of the macro itself.

Returns:
The converted argument.
xonsh.built_ins.default_signal_pauser(n, f)[source]

Pauses a signal, as needed.

xonsh.built_ins.ensure_list_of_strs(x)[source]

Ensures that x is a list of strings.

xonsh.built_ins.enter_macro(obj, raw_block, glbs, locs)[source]

Prepares to enter a context manager macro by attaching the contents of the macro block, globals, and locals to the object. These modifications are made in-place and the original object is returned.

Parameters:
obj : context manager

The object that is about to be entered via a with-statement.

raw_block : str

The str of the block that is the context body. This string will be parsed, compiled, evaled, or left as a string depending on the return annotation of obj.__enter__.

glbs : Mapping

The globals from the context site.

locs : Mapping or None

The locals from the context site.

Returns:
obj : context manager

The same context manager but with the new macro information applied.

xonsh.built_ins.get_script_subproc_command(fname, args)[source]

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

xonsh.built_ins.globsearch(s)[source]
xonsh.built_ins.helper(x, name='')[source]

Prints help about, and then returns that variable.

xonsh.built_ins.in_macro_call(f, glbs, locs)[source]

Attaches macro globals and locals temporarily to function as a context manager.

Parameters:
f : callable object

The function that is called as f(*args).

glbs : Mapping

The globals from the call site.

locs : Mapping or None

The locals from the call site.

xonsh.built_ins.list_of_list_of_strs_outer_product(x)[source]

Takes an outer product of a list of strings

xonsh.built_ins.list_of_strs_or_callables(x)[source]

Ensures that x is a list of strings or functions

xonsh.built_ins.load_builtins(execer=None, ctx=None)[source]

Loads the xonsh builtins into the Python builtins. Sets the BUILTINS_LOADED variable to True.

xonsh.built_ins.load_proxies()[source]

Loads builtin dynamic access proxies. Also puts temporary shims in place for __xonsh_*__ builtins.

xonsh.built_ins.no_pg_xonsh_preexec_fn()[source]

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

xonsh.built_ins.path_literal(s)[source]
xonsh.built_ins.pathsearch(func, s, pymode=False, pathobj=False)[source]

Takes a string and returns a list of file paths that match (regex, glob, or arbitrary search function). If pathobj=True, the return is a list of pathlib.Path objects instead of strings.

xonsh.built_ins.regexsearch(s)[source]
xonsh.built_ins.reglob(path, parts=None, i=None)[source]

Regular expression-based globbing.

xonsh.built_ins.resetting_signal_handle(sig, f)[source]

Sets a new signal handle that will automatically restore the old value once the new handle is finished.

xonsh.built_ins.run_subproc(cmds, captured=False)[source]

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.

xonsh.built_ins.safe_close(x)[source]

Safely attempts to close an object.

xonsh.built_ins.safe_open(fname, mode, buffering=-1)[source]

Safely attempts to open a file in for xonsh subprocs.

xonsh.built_ins.subproc_captured_hiddenobject(*cmds)[source]

Runs a subprocess, capturing the output. Returns an instance of HiddenCommandPipeline representing the completed command.

xonsh.built_ins.subproc_captured_inject(*cmds)[source]

Runs a subprocess, capturing the output. Returns a list of whitespace-separated strings of the stdout that was produced. The string is split using xonsh’s lexer, rather than Python’s str.split() or shlex.split().

xonsh.built_ins.subproc_captured_object(*cmds)[source]

Runs a subprocess, capturing the output. Returns an instance of CommandPipeline representing the completed command.

xonsh.built_ins.subproc_captured_stdout(*cmds)[source]

Runs a subprocess, capturing the output. Returns the stdout that was produced as a str.

xonsh.built_ins.subproc_uncaptured(*cmds)[source]

Runs a subprocess, without capturing the output. Returns the stdout that was produced as a str.

xonsh.built_ins.superhelper(x, name='')[source]

Prints help about, and then returns that variable.

xonsh.built_ins.unload_builtins()[source]

Removes the xonsh builtins from the Python builtins, if the BUILTINS_LOADED is True, sets BUILTINS_LOADED to False, and returns.

xonsh.built_ins.unload_proxies()[source]

Removes the xonsh builtins (proxies) from the Python builtins.

xonsh.built_ins.xonsh_builtins(execer=None)[source]

A context manager for using the xonsh builtins only in a limited scope. Likely useful in testing.