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

# xonsh.aliases

Aliases for the xonsh shell.

class xonsh.aliases.Aliases(*args, **kwargs)

  Represents a location to hold and look up aliases.

  clear() → None. Remove all items from D.
  eval_alias(value, seen_tokens=frozenset({}), acc_args=(), decorators=None)

    “Evaluates” the alias `value`, by recursively looking up the leftmost token and “expanding” if it’s also an alias.

    A value like `["cmd", "arg"]` might transform like this: `> ["cmd", "arg"] -> ["ls", "-al", "arg"] -> callable()` where `cmd=ls -al` and `ls` is an alias with its value being a callable. The resulting callable will be “partially applied” with `["-al", "arg"]`.

  expand_alias(line: str, cursor_index: int) → str

    Expands any aliases present in line if alias does not point to a builtin function and if alias is only a single command. The command won’t be expanded if the cursor’s inside/behind it.

  get(key, default=None, decorators=None)

    Returns list that represent command with resolved aliases. The `key` can be string with alias name or list for a command. In the first position will be the resolved command name or callable alias. If the key is not present, then default is returned.

    `decorators` is the list of DecoratorAlias objects that found during resolving aliases (#5443).

    Note! The return value is always list because during resolving we can find return_command alias that can completely replace command and add new arguments.

  items() → a set-like object providing a view on D's items
  keys() → a set-like object providing a view on D's keys
  pop(k[, d]) → v, remove specified key and return the corresponding value.

    If key is not found, d is returned if given, otherwise KeyError is raised.

  popitem() → (k, v), remove and return some (key, value) pair

    as a 2-tuple; but raise KeyError if D is empty.

  register(func: LambdaType) → LambdaType
  register(name: str, *, dash_case: bool = True) → Callable[[LambdaType], LambdaType]

    Decorator to register the given function by name.

  return_command(f)

    Decorator that switches alias from returning result to return in new command for execution.

  setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D
  update([E, ]**F) → None. Update D from mapping/iterable E and F.

    If E present and has a .keys() method, does: for k in E.keys(): D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v

  values() → an object providing a view on D's values

class xonsh.aliases.ExecAlias(src, filename='<exec-alias>')

  Provides an exec alias for xonsh source code.

  Parameters:
    src str

      Source code that will be

class xonsh.aliases.FuncAlias(name, func=None)

  Provides a callable alias for xonsh commands.

  attributes_inherit = ['__xonsh_threadable__', '__xonsh_capturable__', 'return_what', '__doc__']
  attributes_show = ['__xonsh_threadable__', '__xonsh_capturable__', 'return_what']
  return_what: Literal['command', 'result'] = 'result'

class xonsh.aliases.PartialEvalAlias0(f, acc_args=())
  Parameters:
    f callable

      A function to dispatch to.

    acc_args sequence of strings, optional

      Additional arguments to prepent to the argument list passed in when the alias is called.

class xonsh.aliases.PartialEvalAlias1(f, acc_args=())
  Parameters:
    f callable

      A function to dispatch to.

    acc_args sequence of strings, optional

      Additional arguments to prepent to the argument list passed in when the alias is called.

class xonsh.aliases.PartialEvalAlias2(f, acc_args=())
  Parameters:
    f callable

      A function to dispatch to.

    acc_args sequence of strings, optional

      Additional arguments to prepent to the argument list passed in when the alias is called.

class xonsh.aliases.PartialEvalAlias3(f, acc_args=())
  Parameters:
    f callable

      A function to dispatch to.

    acc_args sequence of strings, optional

      Additional arguments to prepent to the argument list passed in when the alias is called.

class xonsh.aliases.PartialEvalAlias4(f, acc_args=())
  Parameters:
    f callable

      A function to dispatch to.

    acc_args sequence of strings, optional

      Additional arguments to prepent to the argument list passed in when the alias is called.

class xonsh.aliases.PartialEvalAlias5(f, acc_args=())
  Parameters:
    f callable

      A function to dispatch to.

    acc_args sequence of strings, optional

      Additional arguments to prepent to the argument list passed in when the alias is called.

class xonsh.aliases.PartialEvalAlias6(f, acc_args=())
  Parameters:
    f callable

      A function to dispatch to.

    acc_args sequence of strings, optional

      Additional arguments to prepent to the argument list passed in when the alias is called.

class xonsh.aliases.PartialEvalAlias7(f, acc_args=())
  Parameters:
    f callable

      A function to dispatch to.

    acc_args sequence of strings, optional

      Additional arguments to prepent to the argument list passed in when the alias is called.

class xonsh.aliases.PartialEvalAliasBase(f, acc_args=())

  Partially evaluated alias.

  Parameters:
    f callable

      A function to dispatch to.

    acc_args sequence of strings, optional

      Additional arguments to prepent to the argument list passed in when the alias is called.

class xonsh.aliases.SourceForeignAlias(threadable=True, **kwargs)
  exception Error(message: str, errno=1)

    Special case, when raised, the traceback will not be shown. Instead the process with exit with error code and message

    add_note(note, /)

      Add a note to the exception

    with_traceback(tb, /)

      Set self.__traceback__ to tb and return self.

    args
  build()

    Sub-classes should return constructed ArgumentParser

  create_parser(func=None, has_args=False, allowed_params=None, **kwargs) → ArgParser

    create root parser

  err(*args, **kwargs)

    Write text to error stream

  out(*args, **kwargs)

    Write text to output stream

  write_to(stream: str, *args, **kwargs)
  xonsh_complete(command, **kwargs)
  property parser

xonsh.aliases.detect_xpip_alias()

  Determines the correct invocation to get xonsh’s pip

xonsh.aliases.make_default_aliases()

  Creates a new default aliases dictionary.

xonsh.aliases.partial_eval_alias(f, acc_args=())

  Dispatches the appropriate eval alias based on the number of args to the original callable alias and how many arguments to apply.

xonsh.aliases.run_alias_by_params(func: Callable, params: dict[str, Any])

  Run alias function based on signature and params. If function param names are in alias signature fill them. If function params have unknown names fill using alias signature order.

xonsh.aliases.showcmd(args, stdin=None)

  usage: showcmd [-e|–expand-alias] [-h|–help] cmd

  Displays the command and arguments as a list of strings that xonsh would run in subprocess mode. This is useful for determining how xonsh evaluates your commands and arguments prior to running these commands.

  optional arguments:
    `-e, --expand-alias`

      expand alias

    `-h, --help`

      show this help message and exit

  Examples

  @ showcmd echo $USER “can’t” hear “the sea” [‘echo’, ‘I’, “can’t”, ‘hear’, ‘the sea’]

  @ aliases[‘ali’] = ‘echo 1’ @ showcmd -e ali 2 [‘echo’, ‘1’, ‘2’]

xonsh.aliases.source_alias_fn(files: Annotated[list[str], (), 'nargs', '+', 'completer', None], ignore_ext=False, _stdin=None)

  Executes the contents of the provided files in the current context. If sourced file isn’t found in cwd, search for file along $PATH to source instead.

  Parameters:
    files

      paths to source files.

    ignore_ext-e, –ignore-ext

      don’t check the file extension

xonsh.aliases.source_cmd_fn(files: Annotated[list[str], (), 'nargs', '+', 'completer', None], login=False, aliascmd=None, extra_args='', safe=True, postcmd='', funcscmd='', seterrprevcmd=None, overwrite_aliases=False, suppress_skip_message=False, show=False, dryrun=False, _stderr=None)

  > Source cmd.exe files

  Parameters:
    files

      paths to source files.

    login-l, –login

      whether the sourced shell should be login

    envcmd–envcmd

      command to print environment

    aliascmd–aliascmd

      command to print aliases

    extra_args–extra-args

      extra arguments needed to run the shell

    safe-s, –safe

      whether the source shell should be run safely, and not raise any errors, even if they occur.

    postcmd–postcmd

      command(s) to run after all other commands

    funcscmd–funcscmd

      code to find locations of all native functions in the shell language.

    seterrprevcmd–seterrprevcmd

      command(s) to set exit-on-error before any other commands.

    overwrite_aliases–overwrite-aliases

      flag for whether or not sourced aliases should replace the current xonsh aliases.

    suppress_skip_message–suppress-skip-message

      flag for whether or not skip messages should be suppressed.

    show–show

      show the script output.

    dryrun-d, –dry-run

      Will not actually source the file.

xonsh.aliases.source_foreign_fn(shell: str, files_or_code: Annotated[list[str], (), 'nargs', '+', 'completer', None], interactive=False, login=False, envcmd=None, aliascmd=None, extra_args='', safe=True, prevcmd='', postcmd='', funcscmd='', sourcer=None, use_tmpfile=False, seterrprevcmd=None, seterrpostcmd=None, overwrite_aliases=False, suppress_skip_message=False, show=False, dryrun=False, _stderr=None)

  Sources a file written in a foreign shell language.

  Parameters:
    shell

      Name or path to the foreign shell

    files_or_code

      file paths to source or code in the target language.

    interactive-i, –interactive

      whether the sourced shell should be interactive

    login-l, –login

      whether the sourced shell should be login

    envcmd–envcmd

      command to print environment

    aliascmd–aliascmd

      command to print aliases

    extra_args–extra-args

      extra arguments needed to run the shell

    safe-u, –unsafe

      whether the source shell should be run safely, and not raise any errors, even if they occur.

    prevcmd-p, –prevcmd

      command(s) to run before any other commands, replaces traditional source.

    postcmd–postcmd

      command(s) to run after all other commands

    funcscmd–funcscmd

      code to find locations of all native functions in the shell language.

    sourcer–sourcer

      the source command in the target shell language. If this is not set, a default value will attempt to be looked up based on the shell name.

    use_tmpfile–use-tmpfile

      whether the commands for source shell should be written to a temporary file.

    seterrprevcmd–seterrprevcmd

      command(s) to set exit-on-error before any other commands.

    seterrpostcmd–seterrpostcmd

      command(s) to set exit-on-error after all other commands.

    overwrite_aliases–overwrite-aliases

      flag for whether or not sourced aliases should replace the current xonsh aliases.

    suppress_skip_message–suppress-skip-message

      flag for whether or not skip messages should be suppressed.

    show–show

      show the script output.

    dryrun-d, –dry-run

      Will not actually source the file.

xonsh.aliases.trace(args, stdin=None, stdout=None, stderr=None, spec=None)

  Runs the xonsh tracer utility.

xonsh.aliases.xexec_fn(command: Annotated[list[str], (), 'nargs', '...', 'completer', None], login=False, clean=False, name='', _stdin=None)

  exec (also aliased as xexec) uses the os.execvpe() function to replace the xonsh process with the specified program.

  This provides the functionality of the bash ‘exec’ builtin:

      >>> exec bash -l -i
      bash $

  Parameters:
    command

      program to launch along its arguments

    login-l, –login

      the shell places a dash at the beginning of the zeroth argument passed to command to simulate login shell.

    clean-c, –clean

      causes command to be executed with an empty environment.

    name-a, –name

      the shell passes name as the zeroth argument to the executed command.

  Notes

  This command is not the same as the Python builtin function exec(). That function is for running Python code. This command, which shares the same name as the sh-lang statement, is for launching a command directly in the same process. In the event of a name conflict, please use the xexec command directly or dive into subprocess mode explicitly with ![exec command]. For more details, please see http://xon.sh/faq.html#exec.

xonsh.aliases.xonsh_exit(args, stdin=None)

  Sends signal to exit shell.

xonsh.aliases.xonsh_reset(args, stdin=None)

  Clears __xonsh__.ctx