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.DynamicAccessProxy(refname, objname)

Proxies access dynamically.

Parameters

refnamestr

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

objnamestr

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

property obj

Dynamically grabs object

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

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

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.

prep_env(self, kwargs)

Prepares the environment to use in the subprocess.

prep_preexec_fn(self, kwargs, pipeline_group=None)

Prepares the ‘preexec_fn’ keyword argument

redirect_leading(self)

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

redirect_trailing(self)

Manages trailing redirects.

resolve_alias(self)

Sets alias in command, if applicable.

resolve_alias_cls(self)

Determine which proxy class to run an alias with.

resolve_auto_cd(self)

Implements AUTO_CD functionality.

resolve_binary_loc(self)

Sets the binary location

resolve_executable_commands(self)

Resolve command executables, if applicable.

resolve_stack(self)

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

run(self, *, pipeline_group=None)

Launches the subprocess and returns the object.

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

property stderr

property stdin

property stdout

class xonsh.built_ins.XonshSession(execer=None, ctx=None)

All components defining a xonsh session.

Parameters

execerExecer, optional

Xonsh execution object, may be None to start

ctxMapping, optional

Context to start xonsh session with.

link_builtins(self, execer=None)

load(self, execer=None, ctx=None)

Loads the session with default values.

Parameters

execerExecer, optional

Xonsh execution object, may be None to start

ctxMapping, optional

Context to start xonsh session with.

unlink_builtins(self)

xonsh.built_ins.call_macro(f, raw_args, glbs, locs)

Calls a function as a macro, returning its result.

Parameters

fcallable object

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

raw_argstuple 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.

glbsMapping

The globals from the call site.

locsMapping or None

The locals from the call site.

xonsh.built_ins.cmds_to_specs(cmds, captured=False)

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>')

Converts a string macro argument based on the requested kind.

Parameters

raw_argstr

The str representation of the macro argument.

kindobject

A flag or type representing how to convert the argument.

glbsMapping

The globals from the call site.

locsMapping or None

The locals from the call site.

namestr, optional

The macro argument name.

macronamestr, optional

The name of the macro itself.

Returns

The converted argument.

xonsh.built_ins.default_signal_pauser(n, f)

Pauses a signal, as needed.

xonsh.built_ins.ensure_list_of_strs(x)

Ensures that x is a list of strings.

xonsh.built_ins.enter_macro(obj, raw_block, glbs, locs)

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

objcontext manager

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

raw_blockstr

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__.

glbsMapping

The globals from the context site.

locsMapping or None

The locals from the context site.

Returns

objcontext manager

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

xonsh.built_ins.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. Raises PermissionError if the script is not executable.

xonsh.built_ins.globsearch(s)

xonsh.built_ins.helper(x, name='')

Prints help about, and then returns that variable.

xonsh.built_ins.in_macro_call(f, glbs, locs)

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

Parameters

fcallable object

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

glbsMapping

The globals from the call site.

locsMapping or None

The locals from the call site.

xonsh.built_ins.list_of_list_of_strs_outer_product(x)

Takes an outer product of a list of strings

xonsh.built_ins.list_of_strs_or_callables(x)

Ensures that x is a list of strings or functions

xonsh.built_ins.load_builtins(execer=None, ctx=None)

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

xonsh.built_ins.no_pg_xonsh_preexec_fn()

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

xonsh.built_ins.path_literal(s)

xonsh.built_ins.pathsearch(func, s, pymode=False, pathobj=False)

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)

xonsh.built_ins.reglob(path, parts=None, i=None)

Regular expression-based globbing.

xonsh.built_ins.resetting_signal_handle(sig, f)

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)

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)

Safely attempts to close an object.

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

Safely attempts to open a file in for xonsh subprocs.

xonsh.built_ins.subproc_captured_hiddenobject(*cmds)

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

xonsh.built_ins.subproc_captured_inject(*cmds)

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)

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

xonsh.built_ins.subproc_captured_stdout(*cmds)

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

xonsh.built_ins.subproc_uncaptured(*cmds)

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

xonsh.built_ins.superhelper(x, name='')

Prints help about, and then returns that variable.

xonsh.built_ins.unload_builtins()

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

xonsh.built_ins.xonsh_builtins(execer=None)

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