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

# xonsh.environ

Environment for the xonsh shell.

class xonsh.environ.AsyncPromptSetting

  Asynchronous Prompt Load `$PROMPT` in background without blocking read-eval loop.

  classmethod get_doc()
  classmethod get_group_description() → str
  classmethod get_group_title() → str
  classmethod get_groups() → Iterator[tuple[tuple[Xettings, ...], tuple[tuple[str, Var], ...]]]
  classmethod get_settings() → Iterator[tuple[str, Var]]
  ASYNC_INVALIDATE_INTERVAL = (<function is_float>, <class 'float'>, <class 'str'>, 0.05, 'When ENABLE_ASYNC_PROMPT is True, it may call the redraw frequently. This is to group such calls into one that happens within that timeframe. The number is set in seconds.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  ASYNC_PROMPT_THREAD_WORKERS = (<function is_int>, <function to_int_or_none>, <class 'str'>, None, "Define the number of workers used by the ASYNC_PROMPT's pool. By default it is the same as defined by Python's concurrent.futures.ThreadPoolExecutor class.", True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  AUTO_SUGGEST_IN_COMPLETIONS = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'Places the auto-suggest result as the first option in the completions. This enables you to tab complete the auto-suggestion.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  BOTTOM_TOOLBAR = (<function is_string_or_callable>, <function ensure_string>, <function ensure_string>, '', 'Template string for the bottom toolbar. This may be parametrized in the same way as the ``$PROMPT`` variable. Currently, this is only available in the prompt-toolkit shell.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  COLOR_INPUT = (<function is_bool>, <function to_bool>, <function bool_to_str>, True, 'Flag for syntax highlighting interactive input.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  COLOR_RESULTS = (<function is_bool>, <function to_bool>, <function bool_to_str>, True, 'Flag for syntax highlighting return values.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  DYNAMIC_CWD_ELISION_CHAR = (<function is_string>, <function ensure_string>, <function ensure_string>, '', "The string used to show a shortened directory in a shortened cwd, e.g. ``'…'``.", True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  DYNAMIC_CWD_WIDTH = (<function is_dynamic_cwd_width>, <function to_dynamic_cwd_tuple>, <function dynamic_cwd_tuple_to_str>, (inf, 'c'), 'Maximum length in number of characters or as a percentage for the ``cwd`` prompt variable. For example, "20" is a twenty character width and "10%" is ten percent of the number of columns available.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  ENABLE_ASYNC_PROMPT = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'When enabled the prompt is rendered using threads. ``$PROMPT_FIELDS`` that take long will be updated in the background and will not affect prompt speed.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  IGNOREEOF = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'Prevents Ctrl-D from exiting the shell.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  INDENT = (<function is_string>, <function ensure_string>, <function ensure_string>, ' ', 'Indentation string for multiline input', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  LS_COLORS = (<function is_lscolors>, <bound method LsColors.convert of <class 'xonsh.environ.LsColors'>>, <function detype>, <function default_lscolors>, "Color settings for ``ls`` command line utility and, with ``$SHELL_TYPE='prompt_toolkit'``, file arguments in subprocess mode.", True, '``*.7z=1;0;31:*.Z=1;0;31:*.aac=0;36:*.ace=1;0;31:*.alz=1;0;31:*.arc=1;0;31:*.arj=1;0;31:*.asf=1;0;35:*.au=0;36:*.avi=1;0;35:*.bmp=1;0;35:*.bz=1;0;31:*.bz2=1;0;31:*.cab=1;0;31:*.cgm=1;0;35:*.cpio=1;0;31:*.deb=1;0;31:*.dl=1;0;35:*.dwm=1;0;31:*.dz=1;0;31:*.ear=1;0;31:*.emf=1;0;35:*.esd=1;0;31:*.flac=0;36:*.flc=1;0;35:*.fli=1;0;35:*.flv=1;0;35:*.gif=1;0;35:*.gl=1;0;35:*.gz=1;0;31:*.jar=1;0;31:*.jpeg=1;0;35:*.jpg=1;0;35:*.lha=1;0;31:*.lrz=1;0;31:*.lz=1;0;31:*.lz4=1;0;31:*.lzh=1;0;31:*.lzma=1;0;31:*.lzo=1;0;31:*.m2v=1;0;35:*.m4a=0;36:*.m4v=1;0;35:*.mid=0;36:*.midi=0;36:*.mjpeg=1;0;35:*.mjpg=1;0;35:*.mka=0;36:*.mkv=1;0;35:*.mng=1;0;35:*.mov=1;0;35:*.mp3=0;36:*.mp4=1;0;35:*.mp4v=1;0;35:*.mpc=0;36:*.mpeg=1;0;35:*.mpg=1;0;35:*.nuv=1;0;35:*.oga=0;36:*.ogg=0;36:*.ogm=1;0;35:*.ogv=1;0;35:*.ogx=1;0;35:*.opus=0;36:*.pbm=1;0;35:*.pcx=1;0;35:*.pgm=1;0;35:*.png=1;0;35:*.ppm=1;0;35:*.qt=1;0;35:*.ra=0;36:*.rar=1;0;31:*.rm=1;0;35:*.rmvb=1;0;35:*.rpm=1;0;31:*.rz=1;0;31:*.sar=1;0;31:*.spx=0;36:*.svg=1;0;35:*.svgz=1;0;35:*.swm=1;0;31:*.t7z=1;0;31:*.tar=1;0;31:*.taz=1;0;31:*.tbz=1;0;31:*.tbz2=1;0;31:*.tga=1;0;35:*.tgz=1;0;31:*.tif=1;0;35:*.tiff=1;0;35:*.tlz=1;0;31:*.txz=1;0;31:*.tz=1;0;31:*.tzo=1;0;31:*.tzst=1;0;31:*.vob=1;0;35:*.war=1;0;31:*.wav=0;36:*.webm=1;0;35:*.wim=1;0;31:*.wmv=1;0;35:*.xbm=1;0;35:*.xcf=1;0;35:*.xpm=1;0;35:*.xspf=0;36:*.xwd=1;0;35:*.xz=1;0;31:*.yuv=1;0;35:*.z=1;0;31:*.zip=1;0;31:*.zoo=1;0;31:*.zst=1;0;31:bd=40;0;33:ca=0;30;41:cd=40;0;33:di=1;0;34:do=1;0;35:ex=1;0;32:ln=1;0;36:mh=0:mi=0:or=40;0;31:ow=0;34;42:pi=40;0;33:rs=0:sg=0;30;43:so=1;0;35:st=0;37;44:su=0;37;41:tw=0;30;42``', False, None, '', False)
  MOUSE_SUPPORT = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'Enable mouse support in the ``prompt_toolkit`` shell. This allows clicking for positioning the cursor or selecting a completion. In some terminals however, this disables the ability to scroll back through the history of the terminal. Only usable with ``$SHELL_TYPE=prompt_toolkit``', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  MULTILINE_PROMPT = (<function is_string_or_callable>, <function ensure_string>, <function ensure_string>, ' ', 'Prompt text for 2nd+ lines of input, may be str or function which returns a str.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  MULTILINE_PROMPT_POS = (<function is_string_or_callable>, <function ensure_string>, <function ensure_string>, <xonsh.tools.DefaultNotGivenType object>, 'Indicator inserted after the line continuation marks set in ``$MULTILINE_PROMPT``. Can be used to mark the end of a semantic continuation prompt and the beginning of user input (see `Semantic Prompts <https://gitlab.freedesktop.org/Per_Bothner/specifications/blob/master/proposals/semantic-prompts.md>`_ or `WezTerm <https://wezfurlong.org/wezterm/shell-integration.html>`_ for more details). May be str or function which returns a str.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  MULTILINE_PROMPT_PRE = (<function is_string_or_callable>, <function ensure_string>, <function ensure_string>, <xonsh.tools.DefaultNotGivenType object>, 'Indicator inserted before the line continuation marks set in ``$MULTILINE_PROMPT``. Can be used to mark the start of a semantic continuation prompt (see `Semantic Prompts <https://gitlab.freedesktop.org/Per_Bothner/specifications/blob/master/proposals/semantic-prompts.md>`_ or `WezTerm <https://wezfurlong.org/wezterm/shell-integration.html>`_ for more details). May be str or function which returns a str.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  PRETTY_PRINT_RESULTS = (<function is_bool>, <function to_bool>, <function bool_to_str>, True, 'Flag for "pretty printing" return values.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  PROMPT = (<function is_string_or_callable>, <function ensure_string>, <function ensure_string>, '{YELLOW}{env_name}{RESET}{BOLD_GREEN}{user}@{hostname}{BOLD_BLUE} {cwd}{branch_color}{curr_branch: {}}{RESET} {RED}{last_return_code_if_nonzero:[{BOLD_INTENSE_RED}{}{RED}] }{RESET}{BOLD_BLUE}{prompt_end}{RESET} ', "The prompt text. May contain keyword arguments which are auto-formatted, see 'Customizing the Prompt' at http://xon.sh/tutorial.html#customizing-the-prompt. This value is never inherited from parent processes.", True, '``xonsh.environ.DEFAULT_PROMPT``', False, None, '', False)
  PROMPT_FIELDS = (<function always_true>, None, None, <function default_prompt_fields>, "Dictionary containing variables to be used when formatting ``$PROMPT`` and ``$TITLE``. See 'Customizing the Prompt' http://xon.sh/tutorial.html#customizing-the-prompt.", False, '``xonsh.prompt.base.PromptFields``', False, None, '', False)
  PROMPT_REFRESH_INTERVAL = (<function is_float>, <class 'float'>, <class 'str'>, 0.0, 'Interval (in seconds) to evaluate and update ``$PROMPT``, ``$RIGHT_PROMPT`` and ``$BOTTOM_TOOLBAR``. The default is zero (no update). NOTE: ``$UPDATE_PROMPT_ON_KEYPRESS`` must be set to ``True`` for this variable to take effect.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  PROMPT_TOKENS_FORMATTER = (<built-in function callable>, None, None, <function prompt_tokens_formatter_default>, 'Final processor that receives all tokens in the prompt template. It gives option to format the prompt with different prefix based on other tokens values. Highly useful for implementing something like powerline theme.', True, '``xonsh.prompt.base.prompt_tokens_formatter_default``', False, None, '', False)
  PROMPT_TOOLKIT_COLOR_DEPTH = (<function always_false>, <function ptk2_color_depth_setter>, <function ensure_string>, '', 'The color depth used by prompt toolkit 2. Possible values are: ``DEPTH_1_BIT``, ``DEPTH_4_BIT``, ``DEPTH_8_BIT``, ``DEPTH_24_BIT`` colors. Default is an empty string which means that prompt toolkit decide.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  PTK_STYLE_OVERRIDES = (<function is_tok_color_dict>, <function to_tok_color_dict>, <function dict_to_str>, {}, 'A dictionary containing custom prompt_toolkit style definitions. (deprecated)', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  RIGHT_PROMPT = (<function is_string_or_callable>, <function ensure_string>, <function ensure_string>, '', 'Template string for right-aligned text at the prompt. This may be parametrized in the same way as the ``$PROMPT`` variable. Currently, this is only available in the prompt-toolkit shell.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  SHELL_TYPE = (<function is_string>, <function ensure_string>, <function ensure_string>, 'best', "Which shell is used. Currently two base shell types are supported:\n\n- ``readline`` - backed by Python's readline module\n- ``prompt_toolkit`` - uses external library of the same name\n- ``random`` - selects a random shell from the above on startup\n- ``best`` - selects the most feature-rich shell available on the user's system\n\nTo use the ``prompt_toolkit`` shell you need to have the `prompt_toolkit <https://github.com/jonathanslenders/python-prompt-toolkit>`_ library installed. To specify which shell should be used, do so in the run control file. It also accepts a class type that inherits from ``xonsh.shells.base_shell.BaseShell``.", True, '``best``', False, None, '', False)
  SUGGEST_COMMANDS = (<function is_bool>, <function to_bool>, <function bool_to_str>, True, 'When a user types an invalid command, xonsh will try to offer suggestions of similar valid commands if this is True.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  SUGGEST_MAX_NUM = (<function is_int>, <class 'int'>, <class 'str'>, 5, 'xonsh will show at most this many suggestions in response to an invalid command. If negative, there is no limit to how many suggestions are shown.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  SUGGEST_THRESHOLD = (<function is_int>, <class 'int'>, <class 'str'>, 3, 'An error threshold. If the Levenshtein distance between the entered command and a valid command is less than this value, the valid command will be offered as a suggestion. Also used for "fuzzy" tab completion of paths.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  SUPPRESS_BRANCH_TIMEOUT_MESSAGE = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'Whether or not to suppress branch timeout warning messages when getting {gitstatus} PROMPT_FIELD.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  TITLE = (<function is_string_or_callable>, <function ensure_string>, <function ensure_string>, '{current_job:{} | }{user}@{hostname}: {cwd} | xonsh', "The title text for the window in which xonsh is running. Formatted in the same manner as ``$PROMPT``, see 'Customizing the Prompt' http://xon.sh/tutorial.html#customizing-the-prompt.", True, '``xonsh.environ.DEFAULT_TITLE``', False, None, '', False)
  UPDATE_PROMPT_ON_KEYPRESS = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'Disables caching the prompt between commands, so that it would be reevaluated on each keypress. Disabled by default because of the incurred performance penalty.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  VC_BRANCH_TIMEOUT = (<function is_float>, <class 'float'>, <class 'str'>, 0.1, 'The timeout (in seconds) for version control branch computations. This is a timeout per subprocess call, so the total time to compute will be larger than this in many cases.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  VC_GIT_INCLUDE_UNTRACKED = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, "Whether or not untracked file changes should count as 'dirty' in git.", True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  VC_HG_SHOW_BRANCH = (<function is_bool>, <function to_bool>, <function bool_to_str>, True, 'Whether or not to show the Mercurial branch in the prompt.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  VIRTUAL_ENV = (<function is_string>, <function ensure_string>, <function ensure_string>, <xonsh.tools.DefaultNotGivenType object>, 'Path to the currently active Python environment.', False, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  VI_MODE = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'Flag to enable ``vi_mode`` in the ``prompt_toolkit`` shell.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_AUTOPAIR = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'Whether Xonsh will auto-insert matching parentheses, brackets, and quotes. Only available under the prompt-toolkit shell.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_COPY_ON_DELETE = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'Whether to copy words/lines to clipboard on deletion (must be set in the run control file). Does not have any effect in ``vi_mode``. Only available under the prompt-toolkit shell.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_CTRL_BKSP_DELETION = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'Delete a word on CTRL-Backspace (like ALT-Backspace). This will only work when your terminal emulator sends ``\\x7f`` on backspace and ``\\x08`` on CTRL-Backspace (which is configurable on most terminal emulators). On windows, the keys are reversed.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_HISTORY_MATCH_ANYWHERE = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'When searching history from a partial string (by pressing up arrow), match command history anywhere in a given line (not just the start).', True, 'False', False, None, '', False)
  XONSH_PROMPT_AUTO_SUGGEST = (<function is_bool>, <function to_bool>, <function bool_to_str>, True, 'Enable automatic command suggestions based on history.\n\nPressing the right arrow key inserts the currently displayed suggestion. Set before starting the prompt e.g. in ``.xonshrc`` file.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, 'AUTO_SUGGEST', False)
  XONSH_PROMPT_CURSOR_SHAPE = (<function always_false>, <function to_ptk_cursor_shape>, <function to_ptk_cursor_shape_display_value>, <function PTKSetting.<lambda>>, 'The cursor shape. Possible values for prompt toolkit are: ``block``, ``beam``, ``underline``, ``blinking-block``, ``blinking-beam``, ``blinking-underline``, ``modal``, ``modal-vi-mode-only``, ``never-change``. Default value is ``modal-vi-mode-only`` which means ``modal`` if in vi mode and ``never-change`` if not in vi mode.', True, 'modal-vi-mode-only', False, None, '', False)
  XONSH_PROMPT_NEXT_CMD = (<function is_string>, <function ensure_string>, <function ensure_string>, '', "The text of the next command that will be inserted in the next prompt. Use ``<cursor>`` marker to set the cursor position, e.g. ``$XONSH_PROMPT_NEXT_CMD = 'echo <cursor> world'``.", True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_PROMPT_NEXT_CMD_SUGGESTION = (<function is_string>, <function ensure_string>, <function ensure_string>, '', 'The text of the next command suggestion that will be inserted in the next prompt.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_PROMPT_SHOW_SUBPROC_ERROR = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, "Whether the interactive prompt should display the ``subprocess.CalledProcessError`` message when a command at the prompt fails. The failing command's own ``stderr`` is always shown — this flag only controls xonsh's own exception printout that follows it.\n\n* ``False`` *(default)*: after a failing command the prompt returns silently; the command's ``stderr`` is still visible and ``$LAST_RETURN_CODE`` is set.\n* ``True``: xonsh additionally prints ``subprocess.CalledProcessError: Command '...' returned non-zero exit status N.``.\n\nNotes:\n\n* Per-command ``@error_raise`` decorator always shows the exception, regardless of this flag.\n* Non-interactive scripts (run via ``./script.xsh`` or ``xonsh -c``) are unaffected — there the exception propagates normally so the failure is visible.", True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_STDERR_POSTFIX = (<function is_string>, <function ensure_string>, <function ensure_string>, '', 'A format string, using the same keys and colors as ``$PROMPT``, that is appended whenever stderr is displayed. This may be used in conjunction with ``$XONSH_STDERR_PREFIX`` to start the block. For example, to have stderr appear on a red background, the prefix & postfix pair would be "{BACKGROUND_RED}" & "{RESET}". It works with ``!()`` (colors will be reduced) or ``$XONSH_CAPTURE_ALWAYS=True``.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_STDERR_PREFIX = (<function is_string>, <function ensure_string>, <function ensure_string>, '', 'A format string, using the same keys and colors as ``$PROMPT``, that is prepended whenever stderr is displayed. This may be used in conjunction with ``$XONSH_STDERR_POSTFIX`` to close out the block. For example, to have stderr appear on a red background, the prefix & postfix pair would be "{BACKGROUND_RED}" & "{RESET}". It works with ``!()`` (colors will be reduced) or ``$XONSH_CAPTURE_ALWAYS=True``.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_SUPPRESS_WELCOME = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'Suppresses the welcome message.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_USE_SYSTEM_CLIPBOARD = (<function is_bool>, <function to_bool>, <function bool_to_str>, True, 'Whether to let the shell use the system clipboard (must be set in the run control file). The main use-case is to fully disable clipboard integration in ``vi_mode``. Only available under the prompt-toolkit shell.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)

class xonsh.environ.AutoCompletionSetting

  Tab-completion behavior.

  classmethod get_doc()
  classmethod get_group_description() → str
  classmethod get_group_title() → str
  classmethod get_groups() → Iterator[tuple[tuple[Xettings, ...], tuple[tuple[str, Var], ...]]]
  classmethod get_settings() → Iterator[tuple[str, Var]]
  ALIAS_COMPLETIONS_OPTIONS_BY_DEFAULT = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'If True, :py:class:`xonsh.completers.argparser.ArgparseCompleter` based completions will show options (e.g. ``--help``) without requesting explicitly with option prefix ``-``.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  ALIAS_COMPLETIONS_OPTIONS_LONGEST = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'Whether to show all options or just the longest for the :py:class:`xonsh.completers.argparser.ArgparseCompleter` based completions. For example, with ``-h``, ``--help`` both denoting ``help`` action. If True, then only ``--help`` is shown. This is to reduce the noise in generated completions.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  BASH_COMPLETIONS = (<function is_env_path>, <function str_to_env_path>, <function env_path_to_str>, ('/usr/share/bash-completion/bash_completion', '/home/linuxbrew/.linuxbrew/share/bash-completion/bash_completion', '/run/current-system/sw/share/bash-completion/bash_completion', '/sbuild-nonexistent/.nix-profile/share/bash-completion/bash_completion', '/sbuild-nonexistent/.bash_completions'), 'This is a list (or tuple) of strings that specifies where the ``bash_completion`` script and supplemental completion scripts may be found. The first valid ``bash_completion`` framework file will be used; non-framework files and files in directories are sourced after it. For better performance, bash-completion v2.x is recommended since it lazy-loads individual completion scripts. For both bash-completion v1.x and v2.x, paths of package-managed individual completion scripts (like ``.../completes/ssh``) do not need to be included here. The default values are platform dependent, but reasonable. To specify an alternate list, do so in the run control file.', True, 'Platform-dependent. The list probes every known install prefix for the bash-completion framework script and the first existing framework file is sourced, followed by supplemental user completion scripts:\n\n* **Linux / Cygwin / MSYS** — the standard FHS path ``/usr/share/bash-completion/bash_completion``, plus Linuxbrew (``/home/linuxbrew/.linuxbrew/...``), Nix (``/run/current-system/sw/...``, ``~/.nix-profile/...``), and ``~/.bash_completions``.\n* **macOS** — Homebrew on Intel (``/usr/local/...``) and Apple Silicon (``/opt/homebrew/...``), MacPorts (``/opt/local/...``), ``~/.bash_completions``, and Nix.\n* **BSD** — ``/usr/local/...``, ``/usr/pkg/...`` (pkgsrc), and ``~/.bash_completions``.\n* **Windows** — Git for Windows installation prefix (both bash-completion and the bundled ``git-completion.bash``).\n\nEach entry covers both v1.x and v2.x of bash-completion where applicable; v2.x is preferred for performance (lazy per-command loading).', False, None, '', False)
  CMD_COMPLETIONS_SHOW_DESC = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'If True, command completions will show description part with path to the binary and alias in case of xonsh functions.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  COMPLETIONS_BRACKETS = (<function is_bool>, <function to_bool>, <function bool_to_str>, True, 'Flag to enable/disable inclusion of square brackets and parentheses in Python attribute completions.', True, 'True', False, None, '', False)
  COMPLETION_QUERY_LIMIT = (<function is_int>, <class 'int'>, <class 'str'>, 1000, "Maximum number of completions to collect. In prompt_toolkit the list is truncated at this value and a notice is shown above the prompt; in readline the user is asked 'Display all N possibilities?'.", True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  FUZZY_PATH_COMPLETION = (<function is_bool>, <function to_bool>, <function bool_to_str>, True, "Toggles 'fuzzy' matching of paths for tab completion, which is only used as a fallback if no other completions succeed but can be used as a way to adjust for typographical errors. If ``True``, then, e.g., ``xonhs`` will match ``xonsh``.", True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  SUBSEQUENCE_PATH_COMPLETION = (<function is_bool>, <function to_bool>, <function bool_to_str>, True, 'Toggles subsequence matching of paths for tab completion. If ``True``, then, e.g., ``~/u/ro`` can match ``~/lou/carcolh``.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_BASH_PATH_OVERRIDE = (<function always_true>, None, <function ensure_string>, None, 'Override the path used to call bash externally. This allows a user to choose which bash executable to call for ``source-bash`` and any bash completions that are configured. This variable overrides the default settings in ``xonsh.platform.bash_command``.', True, 'None', False, None, '', False)
  XONSH_COMPLETER_DIRS = (<function is_env_path>, <function str_to_env_path>, <function env_path_to_str>, <function default_completer_dirs>, 'A list of paths where Xonsh searches for command completions.\nAny completions defined are lazy loaded when needed.\nThe name of the completer file should match that of the completing command.\nThe file should contain a function with the signature\n``xonsh_complete(ctx: CommandContext) -> Iterator[RichCompletion|str]``.\n', True, 'By default, the following paths are searched.\n1. ``$XONSH_CONFIG_DIR/completions`` - user level completions\n2. ``$XONSH_SYS_CONFIG_DIR/completions`` - system level completions\n3. ``$XONSH_DATA_DIR/generated_completions`` - auto generated completers from man pages\n4. ``$XDG_DATA_DIRS/xonsh/vendor_completions`` - completers from other programs can be placed here.\n\nOther than this, Python package namespace ``xompletions`` can be used to put completer modules as well.', False, None, '', False)
  XONSH_COMPLETER_EMOJI_PREFIX = (<function always_true>, None, <function ensure_string>, None, "Trigger prefix for colorful emoji completion. Set to ``'::'`` to enable, then type ``::<TAB>`` or ``::cat<TAB>`` to search. Default is ``None`` (disabled).", True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_COMPLETER_MODE = (<function is_string>, <function ensure_string>, <function ensure_string>, 'substring_tier', "Controls how completions are filtered.\n\n``'substring_tier'`` (default) — shows all completions that contain the typed text as a substring, ranked in tiers from best to worst match:\n\n 1. Exact prefix (``test`` matches ``test_foo``)\n 2. Case-insensitive prefix (``test`` matches ``TEST_FOO``)\n 3. Substring (``test`` matches ``my_test_bar``)\n 4. Case-insensitive substring (``test`` matches ``MY_TEST_BAR``)\n\nWithin each tier, results are sorted by the position of the match, then alphabetically. This gives a natural ranking where the best matches appear first while still showing all possibilities.\n\n``'prefix'`` — shows only completions that start with the typed text (case-insensitive). Substring matches are hidden.", True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_COMPLETER_SYMBOLS_PREFIX = (<function always_true>, None, <function ensure_string>, None, "Trigger prefix for unicode symbol completion. Set to ``':::'`` to enable, then type ``:::<TAB>`` or ``:::arrow<TAB>`` to search. Default is ``None`` (disabled).", True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_COMPLETER_TRACE = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'Set to ``True`` to show completers invoked and their return values. Each completion is printed on its own line with its ``source`` completer and any non-default ``RichCompletion`` attributes.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)

class xonsh.environ.CacheSetting

  Cache Settings

  classmethod get_doc()
  classmethod get_group_description() → str
  classmethod get_group_title() → str
  classmethod get_groups() → Iterator[tuple[tuple[Xettings, ...], tuple[tuple[str, Var], ...]]]
  classmethod get_settings() → Iterator[tuple[str, Var]]
  COMMANDS_CACHE_SAVE_INTERMEDIATE = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'If enabled, the CommandsCache is saved between runs and can reduce the startup time.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  ENABLE_COMMANDS_CACHE = (<function always_true>, None, <function ensure_string>, True, 'Command names in a directory are cached when enabled. On some platforms it may not be accurate enough (e.g. Windows, Linux save mtime in seconds). Setting it to False would disable the caching mechanism and may slow down the shell.', True, 'True', False, None, '', False)
  XONSH_CACHE_DIR = (<function is_string>, <function ensure_string>, <function ensure_string>, <function xonsh_cache_dir>, 'This is the location where cache files used by xonsh are stored, such as commands-cache...', True, '``$XDG_CACHE_HOME/xonsh``', False, None, '', False)
  XONSH_CACHE_EVERYTHING = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'Controls whether all code (including code entered at the interactive prompt) will be cached.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_CACHE_SCRIPTS = (<function is_bool>, <function to_bool>, <function bool_to_str>, True, 'Controls whether the code for scripts run from xonsh will be cached (``True``) or re-compiled each time (``False``).', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_COMMANDS_CACHE_READ_DIR_ONCE = (<function is_env_path>, <function str_to_env_path>, <function env_path_to_str>, [], "List of directory prefixes whose contents are cached on first access and never re-read within the session. Any ``$PATH`` entry that starts with one of these prefixes (or is a subdirectory) will have its file listing cached. This helps on systems with I/O lag, network drives, and similar issues. On Windows this defaults to ``['C:\\\\Windows']`` (via ``%WINDIR%``). On WSL it auto-detects ``/mnt/*/Windows`` directories. On Linux/Mac it is empty by default but can be extended (e.g. ``$XONSH_COMMANDS_CACHE_READ_DIR_ONCE += ['/bin', '/sbin']``).", True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_COMMANDS_CACHE_TRACE = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'If True, print trace messages showing where each command was resolved from (cached directory listing XONSH_COMMANDS_CACHE_READ_DIR_ONCE vs. disk stat) and how long it took.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)

class xonsh.environ.ChangeDirSetting

  `cd` Behavior

  classmethod get_doc()
  classmethod get_group_description() → str
  classmethod get_group_title() → str
  classmethod get_groups() → Iterator[tuple[tuple[Xettings, ...], tuple[tuple[str, Var], ...]]]
  classmethod get_settings() → Iterator[tuple[str, Var]]
  AUTO_CD = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'Flag to enable changing to a directory by entering the dirname or full path only (without the cd command).', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  AUTO_PUSHD = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'Flag for automatically pushing directories onto the directory stack.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  CDPATH = (<function is_env_path>, <function str_to_env_path>, <function env_path_to_str>, (), 'A list of paths to be used as roots for a cd, breaking compatibility with Bash, xonsh always prefer an existing relative path.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  COMPLETE_DOTS = (<function is_string>, <function ensure_string>, <function ensure_string>, 'matching', 'Flag to specify how current and previous directories should be tab completed (``./``, ``../``):\n\n- ``always`` - Always complete paths with ``./`` and ``../``\n- ``never`` - Never complete paths with ``./`` and ``../``\n- ``matching`` - Complete if path starts with ``.`` or ``..``', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  DIRSTACK_SIZE = (<function is_int>, <class 'int'>, <class 'str'>, 20, 'Maximum size of the directory stack.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  PUSHD_MINUS = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'Flag for directory pushing functionality. False is the normal behavior.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  PUSHD_SILENT = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'Whether or not to suppress directory stack manipulation output.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)

class xonsh.environ.DeprecatedSetting

  Deprecated settings.

  classmethod get_doc()
  classmethod get_group_description() → str
  classmethod get_group_title() → str
  classmethod get_groups() → Iterator[tuple[tuple[Xettings, ...], tuple[tuple[str, Var], ...]]]
  classmethod get_settings() → Iterator[tuple[str, Var]]
  AUTO_SUGGEST = (<function is_bool>, <function to_bool>, <function bool_to_str>, True, 'Deprecated. Use XONSH_PROMPT_AUTO_SUGGEST.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, 'XONSH_PROMPT_AUTO_SUGGEST', True)
  RAISE_SUBPROC_ERROR = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'Deprecated. Use XONSH_SUBPROC_CMD_RAISE_ERROR.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, 'XONSH_SUBPROC_CMD_RAISE_ERROR', True)

class xonsh.environ.Env(*args, **kwargs)

  A xonsh environment, whose variables have limited typing. Most variables are, by default, strings. However, the following rules also apply based on variable-name:

  - PATH: any variable whose name ends in PATH is a list of strings.

  - XONSH_HISTORY_SIZE: this variable is an (int | float, str) tuple.

  - LC_* (locale categories): locale category names get/set the Python locale via locale.getlocale() and locale.setlocale() functions.

  An Env instance may be converted to an untyped version suitable for use in a subprocess.

  If no initial environment is given, os_environ is used.

  clear() → None. Remove all items from D.
  deregister(name)

    Deregister an enviornment variable and all its type handling, default value, doc.

    Parameters:
      name str

        Environment variable name to deregister. Typically all caps.

  detype()

    Returns a dict of detyped variables. Note! If env variable wasn’t explicitly set (e.g. the value has default value in `Xettings`) it will be not in this list.

  detype_all()

    Returns a dict of all available detyped env variables.

    Builds on top of detype() by adding default values for keys that weren’t explicitly set.

  get(key, default=None)

    The environment will look up default values from its own defaults if a default is not given here.

  get_converter(key, default=None)

    Gets a converter for the given key.

  get_default(key, default=None)

    Gets default for the given key.

  get_detyped(key: str)
  get_detyper(key, default=None)

    Gets a detyper for the given key.

  get_docs(key, default=None)

    Gets the documentation for the environment variable.

  get_stringified(key, default=None)
  get_swapped_values()
  get_validator(key, default=None)

    Gets a validator for the given key.

  help(key, short=False)

    Get information about a specific environment variable.

  is_configurable(name)
  is_manually_set(varname)

    Checks if an environment variable has been manually set.

  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.

  rawkeys()

    An iterator that returns all environment keys in their original form. This include string & compiled regular expression keys.

  register(name, type=None, default=None, doc='', validate=<function always_true>, convert=None, detype=<function ensure_string>, is_configurable=True, doc_default=<xonsh.tools.DefaultNotGivenType object>, can_store_as_str=False)

    Register an enviornment variable with optional type handling, default value, doc.

    Parameters:
      name str

        Environment variable name to register. Typically all caps.

      type str, optional, {‘bool’, ‘str’, ‘path’, ‘env_path’, ‘int’, ‘float’}

        Variable type. If not one of the available presets, use validate, convert, and detype to specify type behavior.

      default optional

        Default value for variable. `ValueError` raised if type does not match that specified by type (or validate).

      doc str, optional

        Docstring for variable. This description will be shown in the autocomplete menu (tab-completion).

      validate func, optional

        Function to validate type.

      convert func, optional

        Function to convert variable from a string representation to its type.

      detype func, optional

        Function to convert variable from its type to a string representation.

      is_configurable bool, optional

        Flag for whether the environment variable is configurable or not.

      doc_default str, optional

        Custom docstring for the default value for complex defaults.

      can_store_as_str bool, optional

        Flag for whether the environment variable should be stored as a string. This is used when persisting a variable that is not JSON serializable to the config file. For example, sets, frozensets, and potentially other non-trivial data types. default, False.

  replace_env()

    Replaces the contents of os_environ with a detyped version of the xonsh environment.

  set(key, val)

    Set an environment variable and return the stored value. Used by `$VAR := val`.

  set_swapped_values(swapped_values)
  setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D
  swap(other=None, overlay=None, **kwargs)

    Provides a context manager for temporarily swapping out certain environment variables with other values. On exit from the context manager, the original values are restored. The changes are only applied to the current thread, so that they don’t leak between threads. To get the thread-local overrides use get_swapped_values and set_swapped_values.

    If `overlay` is provided (a dict), it is pushed as a thread-local overlay that shadows both swapped and global values on reads. Callable aliases use this to provide scoped `env` variables.

  undo_replace_env()

    Replaces the contents of os_environ with a detyped version of the xonsh environment.

  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
  DELETE_VAR = <XSH.env.DELETE_VAR>

class xonsh.environ.EnvPath(args=None)

  A class that implements an environment path, which is a list of strings. Provides a custom method that expands all paths if the relevant env variable has been set.

  add(data, front=False, replace=False)

    Add a value to this EnvPath,

    path.add(data, front=bool, replace=bool) -> ensures that path contains data, with position determined by kwargs

    Parameters:
      data string or bytes or pathlib.Path

        value to be added

      front bool

        whether the value should be added to the front, will be ignored if the data already exists in this EnvPath and replace is False Default : False

      replace bool

        If True, the value will be removed and added to the start or end(depending on the value of front) Default : False

    Returns:
      None
  append(value)

    S.append(value) – append value to the end of the sequence

  clear() → None -- remove all items from S
  count(value) → integer -- return number of occurrences of value
  extend(values)

    S.extend(iterable) – extend sequence by appending elements from the iterable

  index(value[, start[, stop]]) → integer -- return first index of

    value. Raises ValueError if the value is not present.

    Supporting start and stop arguments is optional, but recommended.

  insert(index, value)

    S.insert(index, value) – insert value before index

  pop([index]) → item -- remove and return item at index (default

    last). Raise IndexError if list is empty or index is out of range.

  prepend(value)
  remove(value)

    S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

  reverse()

    S.reverse() – reverse IN PLACE

  property paths

    Returns the list of directories that this EnvPath contains.

class xonsh.environ.ErrorHandlingSetting

  Error Handling Settings

  classmethod get_doc()
  classmethod get_group_description() → str
  classmethod get_group_title() → str
  classmethod get_groups() → Iterator[tuple[tuple[Xettings, ...], tuple[tuple[str, Var], ...]]]
  classmethod get_settings() → Iterator[tuple[str, Var]]
  XONSH_SHOW_TRACEBACK = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'Controls if a traceback is shown if exceptions occur in the shell. Set to ``True`` to always show traceback or ``False`` to always hide. If undefined then the traceback is hidden but a notice is shown on how to enable the full traceback.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_TRACEBACK_LOGFILE = (<function is_logfile_opt>, <function to_logfile_opt>, <function logfile_opt_to_str>, None, 'Specifies a file to store the traceback log to, regardless of whether ``XONSH_SHOW_TRACEBACK`` has been set. Its value must be a writable file or None / the empty string if traceback logging is not desired. Logging to a file is not enabled by default.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)

class xonsh.environ.GeneralSetting

  General

  classmethod get_doc()
  classmethod get_group_description() → str
  classmethod get_group_title() → str
  classmethod get_groups() → Iterator[tuple[tuple[Xettings, ...], tuple[tuple[str, Var], ...]]]
  classmethod get_settings() → Iterator[tuple[str, Var]]
  UPDATE_OS_ENVIRON = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'If True ``os_environ`` will always be updated when the xonsh environment changes. The environment can be reset to the default value by calling ``__xonsh__.env.undo_replace_env()``', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSHRC = (<function is_env_path>, <function str_to_env_path>, <function env_path_to_str>, <function default_xonshrc>, 'A list of the locations of run control files, if they exist. User defined run control file will supersede values set in system-wide control file if there is a naming collision. ``$THREAD_SUBPROCS=None`` when reading in run control files.', True, "``['$XONSH_SYS_CONFIG_DIR/xonshrc', '$XONSH_CONFIG_DIR/xonsh/rc.xsh', '~/.xonshrc']``", False, None, '', False)
  XONSHRC_DIR = (<function is_env_path>, <function str_to_env_path>, <function env_path_to_str>, <function default_xonshrcdir>, 'A list of directories, from which all .xsh|.py files will be loaded at startup, sorted in lexicographic order. Files in these directories are loaded after any files in XONSHRC.', True, "``['$XONSH_SYS_CONFIG_DIR/rc.d', '$XONSH_CONFIG_DIR/rc.d']``", False, None, '', False)
  XONSH_COLOR_STYLE = (<function is_string>, <function ensure_string>, <function ensure_string>, 'default', 'Sets the color style for xonsh colors. This is a style name, not a color map. Run ``xonfig styles`` to see the available styles.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_CONFIG_DIR = (<function is_string>, <function ensure_string>, <function ensure_string>, <function xonsh_config_dir>, 'This is the location where xonsh user-level configuration information is stored.', True, '``$XDG_CONFIG_HOME/xonsh``', False, None, '', False)
  XONSH_DATA_DIR = (<function is_string>, <function ensure_string>, <function ensure_string>, <function xonsh_data_dir>, 'This is the location where xonsh data files are stored, such as history, generated completers ...', True, '``$XDG_DATA_HOME/xonsh``', False, None, '', False)
  XONSH_DEBUG = (<function always_false>, <function to_debug>, <function bool_or_int_to_str>, 0, 'Sets the xonsh debugging level. This may be an integer or a boolean. Setting it to ``1`` will get some basic information like input transformation, command replacement. With ``2`` or a higher number will make more debugging information presented, like PLY parsing messages.', False, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_DEBUG_BREAKPOINT_ENGINE = (<function is_breakpoint_engine>, <function to_breakpoint_engine>, <class 'str'>, 'auto', "Default engine used by ``@.debug.breakpoint()`` when called without an explicit ``engine=`` argument. One of ``'auto'``, ``'pdbp'``, ``'ipdb'``, ``'pdb'``, ``'eval'``. When set to ``'auto'``, the first importable debugger is used, in priority order ``pdbp`` -> ``ipdb`` -> ``pdb``, falling back to the ``'eval'`` REPL if none are available.", True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_ENCODING = (<function is_string>, <function ensure_string>, <function ensure_string>, 'utf-8', 'This is the encoding that xonsh should use for subprocess operations.', True, '``sys.getdefaultencoding()``', False, None, '', False)
  XONSH_ENCODING_ERRORS = (<function is_string>, <function ensure_string>, <function ensure_string>, 'surrogateescape', "The flag for how to handle encoding errors should they happen. Any string flag that has been previously registered with Python is allowed. See the 'Python codecs documentation' (https://docs.python.org/3/library/codecs.html#error-handlers) for more information and available options.", True, '``surrogateescape``', False, None, '', False)
  XONSH_ENV_PATTERN_DIRS = (<function VarPattern.is_var_pattern>, <function VarPattern.to_var_pattern>, <function VarPattern.detype_var_pattern>, VarPattern('\\w*DIRS$', 'env_path'), 'Pattern rule: env vars matching this regex are treated as env_path.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_ENV_PATTERN_PATH = (<function VarPattern.is_var_pattern>, <function VarPattern.to_var_pattern>, <function VarPattern.detype_var_pattern>, VarPattern('\\w*PATH$', 'env_path'), 'Pattern rule: env vars matching this regex are treated as env_path.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_INTERACTIVE = (<function is_bool>, <function to_bool>, <function bool_to_str>, True, "``True`` if xonsh is running interactively, and ``False`` otherwise. It's highly recommended to use this variable in your ``xonshrc`` files to split the code execution for interactive and non-interactive modes.", False, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_LOGIN = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, '``True`` if xonsh is running as a login shell, and ``False`` otherwise.', False, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_MODE = (<function is_string>, <function ensure_string>, <function ensure_string>, 'interactive', 'A string value representing the current xonsh execution mode: ``interactive``, ``script_from_file``, ``source``, ``single_command``, ``script_from_stdin``. Note! This variable reflects the mode at start time (e.g. ``script_from_file``) or code execution (e.g. ``source``). If you need to gate behavior in an RC file that you plan to ``source``, use ``$XONSH_INTERACTIVE`` as the flag instead.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_ORIGIN_ENV_FILE = (<function is_string>, <function ensure_string>, <function ensure_string>, <xonsh.tools.DefaultNotGivenType object>, 'The path to the file where environment variables are saved when running ``xonsh --save-origin-env``. When xonsh ``--load-origin-env`` is executed, this file is used as the basis for the environment. Thus, from an existing xonsh session, you can start a new one with the same environment variables that were used when launching the original session.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_SOURCE = (<function is_string>, <function ensure_string>, <function ensure_string>, '', "When running a xonsh script, this variable contains the absolute path to the currently executing script's file.", False, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_STORE_STDIN = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'Whether or not to store the stdin that is supplied to the ``!()`` and ``![]`` operators.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_STYLE_OVERRIDES = (<function is_tok_color_dict>, <function to_tok_color_dict>, <function dict_to_str>, {}, "A dictionary containing custom prompt_toolkit/pygments style definitions.\nThe following style definitions are supported:\n\n- ``pygments.token.Token`` - ``$XONSH_STYLE_OVERRIDES[Token.Keyword] = '#ff0000'``\n- pygments token name (string) - ``$XONSH_STYLE_OVERRIDES['Token.Keyword'] = '#ff0000'``\n- ptk style name (string) - ``$XONSH_STYLE_OVERRIDES['pygments.keyword'] = '#ff0000'``\n\n(The rules above all have the same effect.)", True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_SYS_CONFIG_DIR = (<function is_string>, <function ensure_string>, <function ensure_string>, <function xonsh_sys_config_dir>, 'This is the location where xonsh system-level configuration information is stored.', False, "On Linux & macOS: ``'/etc/xonsh'``\nOn Windows: ``'%ALLUSERSPROFILE%\\\\xonsh'``", False, None, '', False)

class xonsh.environ.InternalEnvironDict

  A dictionary which supports thread-local overrides. There are two reasons we can’t use ChainMap directly: 1. To use thread-local storage, we need to access the local().__dict__ directly each time to get the correct dict. 2. We want to set items to the local storage only if they were explicitly set there.

  Initialize a ChainMap by setting maps to the given mappings. If no mappings are provided, a single empty dictionary is used.

  classmethod fromkeys(iterable, value=None, /)

    Create a new ChainMap with keys from iterable and values set to value.

  clear()

    Clear maps[0], leaving maps[1:] intact.

  copy()

    New ChainMap or subclass with a new copy of maps[0] and refs to maps[1:]

  del_locally(key)
  get(k[, d]) → D[k] if k in D, else d. d defaults to None.
  get_local_overrides()
  items() → a set-like object providing a view on D's items
  keys() → a set-like object providing a view on D's keys
  new_child(m=None, **kwargs)

    New ChainMap with a new map followed by all previous maps. If no map is provided, an empty dict is used. Keyword arguments update the map or new empty dict.

  pop(key, *args)

    Remove key from maps[0] and return its value. Raise KeyError if key not in maps[0].

  popitem()

    Remove and return an item pair from maps[0]. Raise KeyError is maps[0] is empty.

  set_local_overrides(new_local)
  set_locally(key, value)
  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
  property maps
  property parents

    New ChainMap from maps[1:].

class xonsh.environ.InterpreterSetting

  Interpreter Behavior

  classmethod get_doc()
  classmethod get_group_description() → str
  classmethod get_group_title() → str
  classmethod get_groups() → Iterator[tuple[tuple[Xettings, ...], tuple[tuple[str, Var], ...]]]
  classmethod get_settings() → Iterator[tuple[str, Var]]
  DOTGLOB = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'Globbing files with ``*`` or ``**`` will also match dotfiles, or those hidden files whose names begin with a literal ``.``. Such files are filtered out by default.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  EXPAND_ENV_VARS = (<function is_bool>, <function to_bool>, <function bool_to_str>, True, 'Toggles whether environment variables are expanded inside of strings in subprocess mode.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  FOREIGN_ALIASES_OVERRIDE = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'Whether or not foreign aliases should override xonsh aliases with the same name. Note that setting of this must happen in the environment that xonsh was started from. It cannot be set in the ``.xonshrc`` as loading of foreign aliases happens before ``.xonshrc`` is parsed.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  FOREIGN_ALIASES_SUPPRESS_SKIP_MESSAGE = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'Whether or not foreign aliases should suppress the message that informs the user when a foreign alias has been skipped because it already exists in xonsh.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  GLOB_SORTED = (<function is_bool>, <function to_bool>, <function bool_to_str>, True, 'Toggles whether globbing results are manually sorted. If ``False``, the results are returned in arbitrary order.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_SUBPROC_ARG_EXPANDUSER = (<function is_bool>, <function to_bool>, <function bool_to_str>, True, 'If True, ``~`` and ``~user`` in subprocess arguments are expanded to home directories (e.g. ``~/docs`` → ``/home/user/docs``, ``~bob/docs`` → ``/home/bob/docs``). Set to False to pass ``~`` through as a literal character.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)

class xonsh.environ.JobsSetting

  Jobs Settings

  classmethod get_doc()
  classmethod get_group_description() → str
  classmethod get_group_title() → str
  classmethod get_groups() → Iterator[tuple[tuple[Xettings, ...], tuple[tuple[str, Var], ...]]]
  classmethod get_settings() → Iterator[tuple[str, Var]]
  AUTO_CONTINUE = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'If ``True``, automatically resume stopped jobs when they are disowned. When stopped jobs are disowned and this option is ``False``, a warning will print information about how to continue the stopped process.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)

class xonsh.environ.LangSetting

  Language and locale settings.

  classmethod get_doc()
  classmethod get_group_description() → str
  classmethod get_group_title() → str
  classmethod get_groups() → Iterator[tuple[tuple[Xettings, ...], tuple[tuple[str, Var], ...]]]
  classmethod get_settings() → Iterator[tuple[str, Var]]
  LANG = (<function is_string>, <function ensure_string>, <function ensure_string>, 'C.UTF-8', 'Fallback locale setting for systems where it matters.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  LC_COLLATE = (<function always_false>, <function locale_convert.<locals>.lc_converter>, <function ensure_string>, 'C.UTF-8', '', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  LC_CTYPE = (<function always_false>, <function locale_convert.<locals>.lc_converter>, <function ensure_string>, 'C.UTF-8', '', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  LC_MESSAGES = (<function always_false>, <function locale_convert.<locals>.lc_converter>, <function ensure_string>, 'C.UTF-8', '', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  LC_MONETARY = (<function always_false>, <function locale_convert.<locals>.lc_converter>, <function ensure_string>, 'C.UTF-8', '', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  LC_NUMERIC = (<function always_false>, <function locale_convert.<locals>.lc_converter>, <function ensure_string>, 'C.UTF-8', '', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  LC_TIME = (<function always_false>, <function locale_convert.<locals>.lc_converter>, <function ensure_string>, 'C.UTF-8', '', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_DATETIME_FORMAT = (<function is_string>, <function ensure_string>, <function ensure_string>, '%Y-%m-%d %H:%M', 'The format that is used for ``datetime.strptime()`` in various places, i.e the history timestamp option.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)

class xonsh.environ.LsColors(ini_dict: dict | None = None)

  Helps convert to/from `$LS_COLORS` format, respecting the xonsh color style. This accepts the same inputs as dict(). The special value `target` is replaced by no color, but sets a flag for cognizant application (see is_target()).

  classmethod convert(x)

    Converts an object to LsColors, if needed.

  classmethod fromdircolors(filename=None)

    Constructs an LsColors instance by running dircolors. If a filename is provided, it is passed down to the dircolors command.

  classmethod fromstring(s)

    Creates a new instance of the LsColors class from a colon-separated string of dircolor-valid keys to ANSI color escape sequences.

  clear() → None. Remove all items from D.
  detype()

    De-types the instance, allowing it to be exported to the environment.

  get(k[, d]) → D[k] if k in D, else d. d defaults to None.
  is_target(key) → bool

    Return True if key is ‘target’

  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.

  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
  default_settings = {'*.7z': ('BOLD_RED',), '*.Z': ('BOLD_RED',), '*.aac': ('CYAN',), '*.ace': ('BOLD_RED',), '*.alz': ('BOLD_RED',), '*.arc': ('BOLD_RED',), '*.arj': ('BOLD_RED',), '*.asf': ('BOLD_PURPLE',), '*.au': ('CYAN',), '*.avi': ('BOLD_PURPLE',), '*.bmp': ('BOLD_PURPLE',), '*.bz': ('BOLD_RED',), '*.bz2': ('BOLD_RED',), '*.cab': ('BOLD_RED',), '*.cgm': ('BOLD_PURPLE',), '*.cpio': ('BOLD_RED',), '*.deb': ('BOLD_RED',), '*.dl': ('BOLD_PURPLE',), '*.dwm': ('BOLD_RED',), '*.dz': ('BOLD_RED',), '*.ear': ('BOLD_RED',), '*.emf': ('BOLD_PURPLE',), '*.esd': ('BOLD_RED',), '*.flac': ('CYAN',), '*.flc': ('BOLD_PURPLE',), '*.fli': ('BOLD_PURPLE',), '*.flv': ('BOLD_PURPLE',), '*.gif': ('BOLD_PURPLE',), '*.gl': ('BOLD_PURPLE',), '*.gz': ('BOLD_RED',), '*.jar': ('BOLD_RED',), '*.jpeg': ('BOLD_PURPLE',), '*.jpg': ('BOLD_PURPLE',), '*.lha': ('BOLD_RED',), '*.lrz': ('BOLD_RED',), '*.lz': ('BOLD_RED',), '*.lz4': ('BOLD_RED',), '*.lzh': ('BOLD_RED',), '*.lzma': ('BOLD_RED',), '*.lzo': ('BOLD_RED',), '*.m2v': ('BOLD_PURPLE',), '*.m4a': ('CYAN',), '*.m4v': ('BOLD_PURPLE',), '*.mid': ('CYAN',), '*.midi': ('CYAN',), '*.mjpeg': ('BOLD_PURPLE',), '*.mjpg': ('BOLD_PURPLE',), '*.mka': ('CYAN',), '*.mkv': ('BOLD_PURPLE',), '*.mng': ('BOLD_PURPLE',), '*.mov': ('BOLD_PURPLE',), '*.mp3': ('CYAN',), '*.mp4': ('BOLD_PURPLE',), '*.mp4v': ('BOLD_PURPLE',), '*.mpc': ('CYAN',), '*.mpeg': ('BOLD_PURPLE',), '*.mpg': ('BOLD_PURPLE',), '*.nuv': ('BOLD_PURPLE',), '*.oga': ('CYAN',), '*.ogg': ('CYAN',), '*.ogm': ('BOLD_PURPLE',), '*.ogv': ('BOLD_PURPLE',), '*.ogx': ('BOLD_PURPLE',), '*.opus': ('CYAN',), '*.pbm': ('BOLD_PURPLE',), '*.pcx': ('BOLD_PURPLE',), '*.pgm': ('BOLD_PURPLE',), '*.png': ('BOLD_PURPLE',), '*.ppm': ('BOLD_PURPLE',), '*.qt': ('BOLD_PURPLE',), '*.ra': ('CYAN',), '*.rar': ('BOLD_RED',), '*.rm': ('BOLD_PURPLE',), '*.rmvb': ('BOLD_PURPLE',), '*.rpm': ('BOLD_RED',), '*.rz': ('BOLD_RED',), '*.sar': ('BOLD_RED',), '*.spx': ('CYAN',), '*.svg': ('BOLD_PURPLE',), '*.svgz': ('BOLD_PURPLE',), '*.swm': ('BOLD_RED',), '*.t7z': ('BOLD_RED',), '*.tar': ('BOLD_RED',), '*.taz': ('BOLD_RED',), '*.tbz': ('BOLD_RED',), '*.tbz2': ('BOLD_RED',), '*.tga': ('BOLD_PURPLE',), '*.tgz': ('BOLD_RED',), '*.tif': ('BOLD_PURPLE',), '*.tiff': ('BOLD_PURPLE',), '*.tlz': ('BOLD_RED',), '*.txz': ('BOLD_RED',), '*.tz': ('BOLD_RED',), '*.tzo': ('BOLD_RED',), '*.tzst': ('BOLD_RED',), '*.vob': ('BOLD_PURPLE',), '*.war': ('BOLD_RED',), '*.wav': ('CYAN',), '*.webm': ('BOLD_PURPLE',), '*.wim': ('BOLD_RED',), '*.wmv': ('BOLD_PURPLE',), '*.xbm': ('BOLD_PURPLE',), '*.xcf': ('BOLD_PURPLE',), '*.xpm': ('BOLD_PURPLE',), '*.xspf': ('CYAN',), '*.xwd': ('BOLD_PURPLE',), '*.xz': ('BOLD_RED',), '*.yuv': ('BOLD_PURPLE',), '*.z': ('BOLD_RED',), '*.zip': ('BOLD_RED',), '*.zoo': ('BOLD_RED',), '*.zst': ('BOLD_RED',), 'bd': ('BACKGROUND_BLACK', 'YELLOW'), 'ca': ('BLACK', 'BACKGROUND_RED'), 'cd': ('BACKGROUND_BLACK', 'YELLOW'), 'di': ('BOLD_BLUE',), 'do': ('BOLD_PURPLE',), 'ex': ('BOLD_GREEN',), 'fi': ('RESET',), 'ln': ('BOLD_CYAN',), 'mh': ('RESET',), 'mi': ('RESET',), 'or': ('BACKGROUND_BLACK', 'RED'), 'ow': ('BLUE', 'BACKGROUND_GREEN'), 'pi': ('BACKGROUND_BLACK', 'YELLOW'), 'rs': ('RESET',), 'sg': ('BLACK', 'BACKGROUND_YELLOW'), 'so': ('BOLD_PURPLE',), 'st': ('WHITE', 'BACKGROUND_BLUE'), 'su': ('WHITE', 'BACKGROUND_RED'), 'tw': ('BLACK', 'BACKGROUND_GREEN')}
  property style

    The ANSI color style for the current XONSH_COLOR_STYLE

  property style_name

    Current XONSH_COLOR_STYLE value

  target_color = ('RESET',)
  target_value = 'target'

class xonsh.environ.PTKCompletionSetting

  Prompt Toolkit tab-completion

  classmethod get_doc()
  classmethod get_group_description() → str
  classmethod get_group_title() → str
  classmethod get_groups() → Iterator[tuple[tuple[Xettings, ...], tuple[tuple[str, Var], ...]]]
  classmethod get_settings() → Iterator[tuple[str, Var]]
  ALIAS_COMPLETIONS_OPTIONS_BY_DEFAULT = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'If True, :py:class:`xonsh.completers.argparser.ArgparseCompleter` based completions will show options (e.g. ``--help``) without requesting explicitly with option prefix ``-``.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  ALIAS_COMPLETIONS_OPTIONS_LONGEST = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'Whether to show all options or just the longest for the :py:class:`xonsh.completers.argparser.ArgparseCompleter` based completions. For example, with ``-h``, ``--help`` both denoting ``help`` action. If True, then only ``--help`` is shown. This is to reduce the noise in generated completions.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  BASH_COMPLETIONS = (<function is_env_path>, <function str_to_env_path>, <function env_path_to_str>, ('/usr/share/bash-completion/bash_completion', '/home/linuxbrew/.linuxbrew/share/bash-completion/bash_completion', '/run/current-system/sw/share/bash-completion/bash_completion', '/sbuild-nonexistent/.nix-profile/share/bash-completion/bash_completion', '/sbuild-nonexistent/.bash_completions'), 'This is a list (or tuple) of strings that specifies where the ``bash_completion`` script and supplemental completion scripts may be found. The first valid ``bash_completion`` framework file will be used; non-framework files and files in directories are sourced after it. For better performance, bash-completion v2.x is recommended since it lazy-loads individual completion scripts. For both bash-completion v1.x and v2.x, paths of package-managed individual completion scripts (like ``.../completes/ssh``) do not need to be included here. The default values are platform dependent, but reasonable. To specify an alternate list, do so in the run control file.', True, 'Platform-dependent. The list probes every known install prefix for the bash-completion framework script and the first existing framework file is sourced, followed by supplemental user completion scripts:\n\n* **Linux / Cygwin / MSYS** — the standard FHS path ``/usr/share/bash-completion/bash_completion``, plus Linuxbrew (``/home/linuxbrew/.linuxbrew/...``), Nix (``/run/current-system/sw/...``, ``~/.nix-profile/...``), and ``~/.bash_completions``.\n* **macOS** — Homebrew on Intel (``/usr/local/...``) and Apple Silicon (``/opt/homebrew/...``), MacPorts (``/opt/local/...``), ``~/.bash_completions``, and Nix.\n* **BSD** — ``/usr/local/...``, ``/usr/pkg/...`` (pkgsrc), and ``~/.bash_completions``.\n* **Windows** — Git for Windows installation prefix (both bash-completion and the bundled ``git-completion.bash``).\n\nEach entry covers both v1.x and v2.x of bash-completion where applicable; v2.x is preferred for performance (lazy per-command loading).', False, None, '', False)
  CMD_COMPLETIONS_SHOW_DESC = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'If True, command completions will show description part with path to the binary and alias in case of xonsh functions.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  COMPLETIONS_BRACKETS = (<function is_bool>, <function to_bool>, <function bool_to_str>, True, 'Flag to enable/disable inclusion of square brackets and parentheses in Python attribute completions.', True, 'True', False, None, '', False)
  COMPLETIONS_CONFIRM = (<function is_bool>, <function to_bool>, <function bool_to_str>, True, 'While tab-completions menu is displayed, press <Enter> to confirm completion instead of running command. This only affects the prompt-toolkit shell.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  COMPLETIONS_DISPLAY = (<function is_completions_display_value>, <function to_completions_display_value>, <class 'str'>, 'multi', "Configure if and how Python completions are displayed by the ``prompt_toolkit`` shell.\n\nThis option does not affect Bash completions, auto-suggestions, etc.\n\nChanging it at runtime will take immediate effect, so you can quickly disable and enable completions during shell sessions.\n\n- If ``$COMPLETIONS_DISPLAY`` is ``none`` or ``false``, do not display those completions.\n- If ``$COMPLETIONS_DISPLAY`` is ``single``, display completions in a\n single column while typing.\n- If ``$COMPLETIONS_DISPLAY`` is ``multi`` or ``true``, display completions in multiple columns while typing.\n\n- If ``$COMPLETIONS_DISPLAY`` is ``readline``, display completions\n will emulate the behavior of readline.\n\nThese option values are not case- or type-sensitive, so e.g. writing ``$COMPLETIONS_DISPLAY = None`` and ``$COMPLETIONS_DISPLAY = 'none'`` are equivalent. Only usable with ``$SHELL_TYPE=prompt_toolkit``", True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  COMPLETIONS_MENU_ROWS = (<function is_int>, <class 'int'>, <class 'str'>, 5, 'Number of rows to reserve for tab-completions menu if ``$COMPLETIONS_DISPLAY`` is ``single`` or ``multi``. This only affects the prompt-toolkit shell.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  COMPLETION_IN_THREAD = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'When generating the completions takes time, it’s better to do this in a background thread. When this is True, background threads is used for completion.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  COMPLETION_MODE = (<function is_completion_mode>, <function to_completion_mode>, <class 'str'>, 'default', "Mode of tab completion in prompt-toolkit shell (only).\n\n'default', the default, selects the common prefix of completions on first TAB,\nthen cycles through all completions.\n'menu-complete' selects the first whole completion on the first TAB, \nthen cycles through the remaining completions, then the common prefix.", True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  COMPLETION_QUERY_LIMIT = (<function is_int>, <class 'int'>, <class 'str'>, 1000, "Maximum number of completions to collect. In prompt_toolkit the list is truncated at this value and a notice is shown above the prompt; in readline the user is asked 'Display all N possibilities?'.", True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  FUZZY_PATH_COMPLETION = (<function is_bool>, <function to_bool>, <function bool_to_str>, True, "Toggles 'fuzzy' matching of paths for tab completion, which is only used as a fallback if no other completions succeed but can be used as a way to adjust for typographical errors. If ``True``, then, e.g., ``xonhs`` will match ``xonsh``.", True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  SUBSEQUENCE_PATH_COMPLETION = (<function is_bool>, <function to_bool>, <function bool_to_str>, True, 'Toggles subsequence matching of paths for tab completion. If ``True``, then, e.g., ``~/u/ro`` can match ``~/lou/carcolh``.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  UPDATE_COMPLETIONS_ON_KEYPRESS = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'Completions display is evaluated and presented whenever a key is pressed. This avoids the need to press TAB, except to cycle through the possibilities. This currently only affects the prompt-toolkit shell.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_BASH_PATH_OVERRIDE = (<function always_true>, None, <function ensure_string>, None, 'Override the path used to call bash externally. This allows a user to choose which bash executable to call for ``source-bash`` and any bash completions that are configured. This variable overrides the default settings in ``xonsh.platform.bash_command``.', True, 'None', False, None, '', False)
  XONSH_COMPLETER_DIRS = (<function is_env_path>, <function str_to_env_path>, <function env_path_to_str>, <function default_completer_dirs>, 'A list of paths where Xonsh searches for command completions.\nAny completions defined are lazy loaded when needed.\nThe name of the completer file should match that of the completing command.\nThe file should contain a function with the signature\n``xonsh_complete(ctx: CommandContext) -> Iterator[RichCompletion|str]``.\n', True, 'By default, the following paths are searched.\n1. ``$XONSH_CONFIG_DIR/completions`` - user level completions\n2. ``$XONSH_SYS_CONFIG_DIR/completions`` - system level completions\n3. ``$XONSH_DATA_DIR/generated_completions`` - auto generated completers from man pages\n4. ``$XDG_DATA_DIRS/xonsh/vendor_completions`` - completers from other programs can be placed here.\n\nOther than this, Python package namespace ``xompletions`` can be used to put completer modules as well.', False, None, '', False)
  XONSH_COMPLETER_EMOJI_PREFIX = (<function always_true>, None, <function ensure_string>, None, "Trigger prefix for colorful emoji completion. Set to ``'::'`` to enable, then type ``::<TAB>`` or ``::cat<TAB>`` to search. Default is ``None`` (disabled).", True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_COMPLETER_MODE = (<function is_string>, <function ensure_string>, <function ensure_string>, 'substring_tier', "Controls how completions are filtered.\n\n``'substring_tier'`` (default) — shows all completions that contain the typed text as a substring, ranked in tiers from best to worst match:\n\n 1. Exact prefix (``test`` matches ``test_foo``)\n 2. Case-insensitive prefix (``test`` matches ``TEST_FOO``)\n 3. Substring (``test`` matches ``my_test_bar``)\n 4. Case-insensitive substring (``test`` matches ``MY_TEST_BAR``)\n\nWithin each tier, results are sorted by the position of the match, then alphabetically. This gives a natural ranking where the best matches appear first while still showing all possibilities.\n\n``'prefix'`` — shows only completions that start with the typed text (case-insensitive). Substring matches are hidden.", True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_COMPLETER_SYMBOLS_PREFIX = (<function always_true>, None, <function ensure_string>, None, "Trigger prefix for unicode symbol completion. Set to ``':::'`` to enable, then type ``:::<TAB>`` or ``:::arrow<TAB>`` to search. Default is ``None`` (disabled).", True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_COMPLETER_TRACE = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'Set to ``True`` to show completers invoked and their return values. Each completion is printed on its own line with its ``source`` completer and any non-default ``RichCompletion`` attributes.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)

class xonsh.environ.PTKSetting

  Prompt Toolkit shell Only usable with `$SHELL_TYPE=prompt_toolkit.`

  classmethod get_doc()
  classmethod get_group_description() → str
  classmethod get_group_title() → str
  classmethod get_groups() → Iterator[tuple[tuple[Xettings, ...], tuple[tuple[str, Var], ...]]]
  classmethod get_settings() → Iterator[tuple[str, Var]]
  AUTO_SUGGEST_IN_COMPLETIONS = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'Places the auto-suggest result as the first option in the completions. This enables you to tab complete the auto-suggestion.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  BOTTOM_TOOLBAR = (<function is_string_or_callable>, <function ensure_string>, <function ensure_string>, '', 'Template string for the bottom toolbar. This may be parametrized in the same way as the ``$PROMPT`` variable. Currently, this is only available in the prompt-toolkit shell.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  COLOR_INPUT = (<function is_bool>, <function to_bool>, <function bool_to_str>, True, 'Flag for syntax highlighting interactive input.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  COLOR_RESULTS = (<function is_bool>, <function to_bool>, <function bool_to_str>, True, 'Flag for syntax highlighting return values.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  DYNAMIC_CWD_ELISION_CHAR = (<function is_string>, <function ensure_string>, <function ensure_string>, '', "The string used to show a shortened directory in a shortened cwd, e.g. ``'…'``.", True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  DYNAMIC_CWD_WIDTH = (<function is_dynamic_cwd_width>, <function to_dynamic_cwd_tuple>, <function dynamic_cwd_tuple_to_str>, (inf, 'c'), 'Maximum length in number of characters or as a percentage for the ``cwd`` prompt variable. For example, "20" is a twenty character width and "10%" is ten percent of the number of columns available.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  IGNOREEOF = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'Prevents Ctrl-D from exiting the shell.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  INDENT = (<function is_string>, <function ensure_string>, <function ensure_string>, ' ', 'Indentation string for multiline input', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  LS_COLORS = (<function is_lscolors>, <bound method LsColors.convert of <class 'xonsh.environ.LsColors'>>, <function detype>, <function default_lscolors>, "Color settings for ``ls`` command line utility and, with ``$SHELL_TYPE='prompt_toolkit'``, file arguments in subprocess mode.", True, '``*.7z=1;0;31:*.Z=1;0;31:*.aac=0;36:*.ace=1;0;31:*.alz=1;0;31:*.arc=1;0;31:*.arj=1;0;31:*.asf=1;0;35:*.au=0;36:*.avi=1;0;35:*.bmp=1;0;35:*.bz=1;0;31:*.bz2=1;0;31:*.cab=1;0;31:*.cgm=1;0;35:*.cpio=1;0;31:*.deb=1;0;31:*.dl=1;0;35:*.dwm=1;0;31:*.dz=1;0;31:*.ear=1;0;31:*.emf=1;0;35:*.esd=1;0;31:*.flac=0;36:*.flc=1;0;35:*.fli=1;0;35:*.flv=1;0;35:*.gif=1;0;35:*.gl=1;0;35:*.gz=1;0;31:*.jar=1;0;31:*.jpeg=1;0;35:*.jpg=1;0;35:*.lha=1;0;31:*.lrz=1;0;31:*.lz=1;0;31:*.lz4=1;0;31:*.lzh=1;0;31:*.lzma=1;0;31:*.lzo=1;0;31:*.m2v=1;0;35:*.m4a=0;36:*.m4v=1;0;35:*.mid=0;36:*.midi=0;36:*.mjpeg=1;0;35:*.mjpg=1;0;35:*.mka=0;36:*.mkv=1;0;35:*.mng=1;0;35:*.mov=1;0;35:*.mp3=0;36:*.mp4=1;0;35:*.mp4v=1;0;35:*.mpc=0;36:*.mpeg=1;0;35:*.mpg=1;0;35:*.nuv=1;0;35:*.oga=0;36:*.ogg=0;36:*.ogm=1;0;35:*.ogv=1;0;35:*.ogx=1;0;35:*.opus=0;36:*.pbm=1;0;35:*.pcx=1;0;35:*.pgm=1;0;35:*.png=1;0;35:*.ppm=1;0;35:*.qt=1;0;35:*.ra=0;36:*.rar=1;0;31:*.rm=1;0;35:*.rmvb=1;0;35:*.rpm=1;0;31:*.rz=1;0;31:*.sar=1;0;31:*.spx=0;36:*.svg=1;0;35:*.svgz=1;0;35:*.swm=1;0;31:*.t7z=1;0;31:*.tar=1;0;31:*.taz=1;0;31:*.tbz=1;0;31:*.tbz2=1;0;31:*.tga=1;0;35:*.tgz=1;0;31:*.tif=1;0;35:*.tiff=1;0;35:*.tlz=1;0;31:*.txz=1;0;31:*.tz=1;0;31:*.tzo=1;0;31:*.tzst=1;0;31:*.vob=1;0;35:*.war=1;0;31:*.wav=0;36:*.webm=1;0;35:*.wim=1;0;31:*.wmv=1;0;35:*.xbm=1;0;35:*.xcf=1;0;35:*.xpm=1;0;35:*.xspf=0;36:*.xwd=1;0;35:*.xz=1;0;31:*.yuv=1;0;35:*.z=1;0;31:*.zip=1;0;31:*.zoo=1;0;31:*.zst=1;0;31:bd=40;0;33:ca=0;30;41:cd=40;0;33:di=1;0;34:do=1;0;35:ex=1;0;32:ln=1;0;36:mh=0:mi=0:or=40;0;31:ow=0;34;42:pi=40;0;33:rs=0:sg=0;30;43:so=1;0;35:st=0;37;44:su=0;37;41:tw=0;30;42``', False, None, '', False)
  MOUSE_SUPPORT = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'Enable mouse support in the ``prompt_toolkit`` shell. This allows clicking for positioning the cursor or selecting a completion. In some terminals however, this disables the ability to scroll back through the history of the terminal. Only usable with ``$SHELL_TYPE=prompt_toolkit``', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  MULTILINE_PROMPT = (<function is_string_or_callable>, <function ensure_string>, <function ensure_string>, ' ', 'Prompt text for 2nd+ lines of input, may be str or function which returns a str.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  MULTILINE_PROMPT_POS = (<function is_string_or_callable>, <function ensure_string>, <function ensure_string>, <xonsh.tools.DefaultNotGivenType object>, 'Indicator inserted after the line continuation marks set in ``$MULTILINE_PROMPT``. Can be used to mark the end of a semantic continuation prompt and the beginning of user input (see `Semantic Prompts <https://gitlab.freedesktop.org/Per_Bothner/specifications/blob/master/proposals/semantic-prompts.md>`_ or `WezTerm <https://wezfurlong.org/wezterm/shell-integration.html>`_ for more details). May be str or function which returns a str.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  MULTILINE_PROMPT_PRE = (<function is_string_or_callable>, <function ensure_string>, <function ensure_string>, <xonsh.tools.DefaultNotGivenType object>, 'Indicator inserted before the line continuation marks set in ``$MULTILINE_PROMPT``. Can be used to mark the start of a semantic continuation prompt (see `Semantic Prompts <https://gitlab.freedesktop.org/Per_Bothner/specifications/blob/master/proposals/semantic-prompts.md>`_ or `WezTerm <https://wezfurlong.org/wezterm/shell-integration.html>`_ for more details). May be str or function which returns a str.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  PRETTY_PRINT_RESULTS = (<function is_bool>, <function to_bool>, <function bool_to_str>, True, 'Flag for "pretty printing" return values.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  PROMPT = (<function is_string_or_callable>, <function ensure_string>, <function ensure_string>, '{YELLOW}{env_name}{RESET}{BOLD_GREEN}{user}@{hostname}{BOLD_BLUE} {cwd}{branch_color}{curr_branch: {}}{RESET} {RED}{last_return_code_if_nonzero:[{BOLD_INTENSE_RED}{}{RED}] }{RESET}{BOLD_BLUE}{prompt_end}{RESET} ', "The prompt text. May contain keyword arguments which are auto-formatted, see 'Customizing the Prompt' at http://xon.sh/tutorial.html#customizing-the-prompt. This value is never inherited from parent processes.", True, '``xonsh.environ.DEFAULT_PROMPT``', False, None, '', False)
  PROMPT_FIELDS = (<function always_true>, None, None, <function default_prompt_fields>, "Dictionary containing variables to be used when formatting ``$PROMPT`` and ``$TITLE``. See 'Customizing the Prompt' http://xon.sh/tutorial.html#customizing-the-prompt.", False, '``xonsh.prompt.base.PromptFields``', False, None, '', False)
  PROMPT_REFRESH_INTERVAL = (<function is_float>, <class 'float'>, <class 'str'>, 0.0, 'Interval (in seconds) to evaluate and update ``$PROMPT``, ``$RIGHT_PROMPT`` and ``$BOTTOM_TOOLBAR``. The default is zero (no update). NOTE: ``$UPDATE_PROMPT_ON_KEYPRESS`` must be set to ``True`` for this variable to take effect.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  PROMPT_TOKENS_FORMATTER = (<built-in function callable>, None, None, <function prompt_tokens_formatter_default>, 'Final processor that receives all tokens in the prompt template. It gives option to format the prompt with different prefix based on other tokens values. Highly useful for implementing something like powerline theme.', True, '``xonsh.prompt.base.prompt_tokens_formatter_default``', False, None, '', False)
  PROMPT_TOOLKIT_COLOR_DEPTH = (<function always_false>, <function ptk2_color_depth_setter>, <function ensure_string>, '', 'The color depth used by prompt toolkit 2. Possible values are: ``DEPTH_1_BIT``, ``DEPTH_4_BIT``, ``DEPTH_8_BIT``, ``DEPTH_24_BIT`` colors. Default is an empty string which means that prompt toolkit decide.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  PTK_STYLE_OVERRIDES = (<function is_tok_color_dict>, <function to_tok_color_dict>, <function dict_to_str>, {}, 'A dictionary containing custom prompt_toolkit style definitions. (deprecated)', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  RIGHT_PROMPT = (<function is_string_or_callable>, <function ensure_string>, <function ensure_string>, '', 'Template string for right-aligned text at the prompt. This may be parametrized in the same way as the ``$PROMPT`` variable. Currently, this is only available in the prompt-toolkit shell.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  SHELL_TYPE = (<function is_string>, <function ensure_string>, <function ensure_string>, 'best', "Which shell is used. Currently two base shell types are supported:\n\n- ``readline`` - backed by Python's readline module\n- ``prompt_toolkit`` - uses external library of the same name\n- ``random`` - selects a random shell from the above on startup\n- ``best`` - selects the most feature-rich shell available on the user's system\n\nTo use the ``prompt_toolkit`` shell you need to have the `prompt_toolkit <https://github.com/jonathanslenders/python-prompt-toolkit>`_ library installed. To specify which shell should be used, do so in the run control file. It also accepts a class type that inherits from ``xonsh.shells.base_shell.BaseShell``.", True, '``best``', False, None, '', False)
  SUGGEST_COMMANDS = (<function is_bool>, <function to_bool>, <function bool_to_str>, True, 'When a user types an invalid command, xonsh will try to offer suggestions of similar valid commands if this is True.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  SUGGEST_MAX_NUM = (<function is_int>, <class 'int'>, <class 'str'>, 5, 'xonsh will show at most this many suggestions in response to an invalid command. If negative, there is no limit to how many suggestions are shown.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  SUGGEST_THRESHOLD = (<function is_int>, <class 'int'>, <class 'str'>, 3, 'An error threshold. If the Levenshtein distance between the entered command and a valid command is less than this value, the valid command will be offered as a suggestion. Also used for "fuzzy" tab completion of paths.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  SUPPRESS_BRANCH_TIMEOUT_MESSAGE = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'Whether or not to suppress branch timeout warning messages when getting {gitstatus} PROMPT_FIELD.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  TITLE = (<function is_string_or_callable>, <function ensure_string>, <function ensure_string>, '{current_job:{} | }{user}@{hostname}: {cwd} | xonsh', "The title text for the window in which xonsh is running. Formatted in the same manner as ``$PROMPT``, see 'Customizing the Prompt' http://xon.sh/tutorial.html#customizing-the-prompt.", True, '``xonsh.environ.DEFAULT_TITLE``', False, None, '', False)
  UPDATE_PROMPT_ON_KEYPRESS = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'Disables caching the prompt between commands, so that it would be reevaluated on each keypress. Disabled by default because of the incurred performance penalty.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  VC_BRANCH_TIMEOUT = (<function is_float>, <class 'float'>, <class 'str'>, 0.1, 'The timeout (in seconds) for version control branch computations. This is a timeout per subprocess call, so the total time to compute will be larger than this in many cases.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  VC_GIT_INCLUDE_UNTRACKED = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, "Whether or not untracked file changes should count as 'dirty' in git.", True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  VC_HG_SHOW_BRANCH = (<function is_bool>, <function to_bool>, <function bool_to_str>, True, 'Whether or not to show the Mercurial branch in the prompt.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  VIRTUAL_ENV = (<function is_string>, <function ensure_string>, <function ensure_string>, <xonsh.tools.DefaultNotGivenType object>, 'Path to the currently active Python environment.', False, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  VI_MODE = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'Flag to enable ``vi_mode`` in the ``prompt_toolkit`` shell.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_AUTOPAIR = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'Whether Xonsh will auto-insert matching parentheses, brackets, and quotes. Only available under the prompt-toolkit shell.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_COPY_ON_DELETE = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'Whether to copy words/lines to clipboard on deletion (must be set in the run control file). Does not have any effect in ``vi_mode``. Only available under the prompt-toolkit shell.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_CTRL_BKSP_DELETION = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'Delete a word on CTRL-Backspace (like ALT-Backspace). This will only work when your terminal emulator sends ``\\x7f`` on backspace and ``\\x08`` on CTRL-Backspace (which is configurable on most terminal emulators). On windows, the keys are reversed.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_HISTORY_MATCH_ANYWHERE = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'When searching history from a partial string (by pressing up arrow), match command history anywhere in a given line (not just the start).', True, 'False', False, None, '', False)
  XONSH_PROMPT_AUTO_SUGGEST = (<function is_bool>, <function to_bool>, <function bool_to_str>, True, 'Enable automatic command suggestions based on history.\n\nPressing the right arrow key inserts the currently displayed suggestion. Set before starting the prompt e.g. in ``.xonshrc`` file.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, 'AUTO_SUGGEST', False)
  XONSH_PROMPT_CURSOR_SHAPE = (<function always_false>, <function to_ptk_cursor_shape>, <function to_ptk_cursor_shape_display_value>, <function PTKSetting.<lambda>>, 'The cursor shape. Possible values for prompt toolkit are: ``block``, ``beam``, ``underline``, ``blinking-block``, ``blinking-beam``, ``blinking-underline``, ``modal``, ``modal-vi-mode-only``, ``never-change``. Default value is ``modal-vi-mode-only`` which means ``modal`` if in vi mode and ``never-change`` if not in vi mode.', True, 'modal-vi-mode-only', False, None, '', False)
  XONSH_PROMPT_NEXT_CMD = (<function is_string>, <function ensure_string>, <function ensure_string>, '', "The text of the next command that will be inserted in the next prompt. Use ``<cursor>`` marker to set the cursor position, e.g. ``$XONSH_PROMPT_NEXT_CMD = 'echo <cursor> world'``.", True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_PROMPT_NEXT_CMD_SUGGESTION = (<function is_string>, <function ensure_string>, <function ensure_string>, '', 'The text of the next command suggestion that will be inserted in the next prompt.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_PROMPT_SHOW_SUBPROC_ERROR = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, "Whether the interactive prompt should display the ``subprocess.CalledProcessError`` message when a command at the prompt fails. The failing command's own ``stderr`` is always shown — this flag only controls xonsh's own exception printout that follows it.\n\n* ``False`` *(default)*: after a failing command the prompt returns silently; the command's ``stderr`` is still visible and ``$LAST_RETURN_CODE`` is set.\n* ``True``: xonsh additionally prints ``subprocess.CalledProcessError: Command '...' returned non-zero exit status N.``.\n\nNotes:\n\n* Per-command ``@error_raise`` decorator always shows the exception, regardless of this flag.\n* Non-interactive scripts (run via ``./script.xsh`` or ``xonsh -c``) are unaffected — there the exception propagates normally so the failure is visible.", True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_STDERR_POSTFIX = (<function is_string>, <function ensure_string>, <function ensure_string>, '', 'A format string, using the same keys and colors as ``$PROMPT``, that is appended whenever stderr is displayed. This may be used in conjunction with ``$XONSH_STDERR_PREFIX`` to start the block. For example, to have stderr appear on a red background, the prefix & postfix pair would be "{BACKGROUND_RED}" & "{RESET}". It works with ``!()`` (colors will be reduced) or ``$XONSH_CAPTURE_ALWAYS=True``.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_STDERR_PREFIX = (<function is_string>, <function ensure_string>, <function ensure_string>, '', 'A format string, using the same keys and colors as ``$PROMPT``, that is prepended whenever stderr is displayed. This may be used in conjunction with ``$XONSH_STDERR_POSTFIX`` to close out the block. For example, to have stderr appear on a red background, the prefix & postfix pair would be "{BACKGROUND_RED}" & "{RESET}". It works with ``!()`` (colors will be reduced) or ``$XONSH_CAPTURE_ALWAYS=True``.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_SUPPRESS_WELCOME = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'Suppresses the welcome message.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_USE_SYSTEM_CLIPBOARD = (<function is_bool>, <function to_bool>, <function bool_to_str>, True, 'Whether to let the shell use the system clipboard (must be set in the run control file). The main use-case is to fully disable clipboard integration in ``vi_mode``. Only available under the prompt-toolkit shell.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)

class xonsh.environ.PromptHistorySetting

  Interactive Prompt History

  classmethod get_doc()
  classmethod get_group_description() → str
  classmethod get_group_title() → str
  classmethod get_groups() → Iterator[tuple[tuple[Xettings, ...], tuple[tuple[str, Var], ...]]]
  classmethod get_settings() → Iterator[tuple[str, Var]]
  HISTCONTROL = (<function is_string_set>, <function histcontrol_csv_to_set>, <function set_to_csv>, {}, 'A set of strings (comma-separated list in string form) of options that determine what commands are saved to the history list. By default all commands are saved. Options are as follows:\n\n- ``ignoredups`` will not save the command if it matches the previous command\n- ``ignoreerr`` will cause any commands that fail (i.e. return non-zero exit status) to not be added to the history list\n- ``ignorespace`` will not save the command if it begins with a space\n', True, <xonsh.tools.DefaultNotGivenType object>, True, None, '', False)
  XONSH_HISTORY_BACKEND = (<function is_history_backend>, <function to_itself>, <function ensure_string>, 'json', "Set which history backend to use. Options are: 'json', 'sqlite', and 'dummy'. The default is 'json'. ``XONSH_HISTORY_BACKEND`` also accepts a class type that inherits from ``xonsh.history.base.History``, or its instance.", True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_HISTORY_FILE = (<function is_path>, <function str_to_abs_path>, <function abs_path_to_str>, None, 'Location of history file set by history backend (default) or set by the user.', False, 'None', False, None, '', False)
  XONSH_HISTORY_IGNORE_REGEX = (<function is_regex>, <function to_itself>, <function ensure_string>, None, "Set a filter criteria for history items using a regular expression. Any matching items will not be retained in the history. Example: ``$XONSH_HISTORY_IGNORE_REGEX = '(^echo|^.*\\#\\#\\#\\s*|.*\\#\\#\\#\\s*$)'`` - skip commands that start from ``echo`` or ``###``, or end from ``###``.", True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_HISTORY_SAVE_CWD = (<function is_bool>, <function to_bool>, <function bool_to_str>, True, 'Save current working directory to the history.', True, 'True', False, None, '', False)
  XONSH_HISTORY_SIGINT_FLUSH = (<function is_bool>, <function to_bool>, <function bool_to_str>, True, 'Save history after getting SIGINT (Ctrl+C).', True, 'True', False, None, '', False)
  XONSH_HISTORY_SIZE = (<function is_history_tuple>, <function to_history_tuple>, <function history_tuple_to_str>, (8128, 'commands'), "Value and units tuple that sets the size of history after garbage collection. Canonical units are:\n\n- ``commands`` for the number of past commands executed,\n- ``files`` for the number of history files to keep,\n- ``s`` for the number of seconds in the past that are allowed, and\n- ``b`` for the number of bytes that history may consume.\n\nCommon abbreviations, such as '6 months' or '1 GB' are also allowed.", True, "``(8128, 'commands')`` or ``'8128 commands'``", False, None, '', False)
  XONSH_STORE_STDOUT = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'Store the ``stdout`` and ``stderr`` streams to the history. Requires that XONSH_CAPTURE_ALWAYS is True.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)

class xonsh.environ.PromptSetting

  Interactive Prompt

  classmethod get_doc()
  classmethod get_group_description() → str
  classmethod get_group_title() → str
  classmethod get_groups() → Iterator[tuple[tuple[Xettings, ...], tuple[tuple[str, Var], ...]]]
  classmethod get_settings() → Iterator[tuple[str, Var]]
  BOTTOM_TOOLBAR = (<function is_string_or_callable>, <function ensure_string>, <function ensure_string>, '', 'Template string for the bottom toolbar. This may be parametrized in the same way as the ``$PROMPT`` variable. Currently, this is only available in the prompt-toolkit shell.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  COLOR_INPUT = (<function is_bool>, <function to_bool>, <function bool_to_str>, True, 'Flag for syntax highlighting interactive input.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  COLOR_RESULTS = (<function is_bool>, <function to_bool>, <function bool_to_str>, True, 'Flag for syntax highlighting return values.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  DYNAMIC_CWD_ELISION_CHAR = (<function is_string>, <function ensure_string>, <function ensure_string>, '', "The string used to show a shortened directory in a shortened cwd, e.g. ``'…'``.", True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  DYNAMIC_CWD_WIDTH = (<function is_dynamic_cwd_width>, <function to_dynamic_cwd_tuple>, <function dynamic_cwd_tuple_to_str>, (inf, 'c'), 'Maximum length in number of characters or as a percentage for the ``cwd`` prompt variable. For example, "20" is a twenty character width and "10%" is ten percent of the number of columns available.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  IGNOREEOF = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'Prevents Ctrl-D from exiting the shell.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  INDENT = (<function is_string>, <function ensure_string>, <function ensure_string>, ' ', 'Indentation string for multiline input', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  LS_COLORS = (<function is_lscolors>, <bound method LsColors.convert of <class 'xonsh.environ.LsColors'>>, <function detype>, <function default_lscolors>, "Color settings for ``ls`` command line utility and, with ``$SHELL_TYPE='prompt_toolkit'``, file arguments in subprocess mode.", True, '``*.7z=1;0;31:*.Z=1;0;31:*.aac=0;36:*.ace=1;0;31:*.alz=1;0;31:*.arc=1;0;31:*.arj=1;0;31:*.asf=1;0;35:*.au=0;36:*.avi=1;0;35:*.bmp=1;0;35:*.bz=1;0;31:*.bz2=1;0;31:*.cab=1;0;31:*.cgm=1;0;35:*.cpio=1;0;31:*.deb=1;0;31:*.dl=1;0;35:*.dwm=1;0;31:*.dz=1;0;31:*.ear=1;0;31:*.emf=1;0;35:*.esd=1;0;31:*.flac=0;36:*.flc=1;0;35:*.fli=1;0;35:*.flv=1;0;35:*.gif=1;0;35:*.gl=1;0;35:*.gz=1;0;31:*.jar=1;0;31:*.jpeg=1;0;35:*.jpg=1;0;35:*.lha=1;0;31:*.lrz=1;0;31:*.lz=1;0;31:*.lz4=1;0;31:*.lzh=1;0;31:*.lzma=1;0;31:*.lzo=1;0;31:*.m2v=1;0;35:*.m4a=0;36:*.m4v=1;0;35:*.mid=0;36:*.midi=0;36:*.mjpeg=1;0;35:*.mjpg=1;0;35:*.mka=0;36:*.mkv=1;0;35:*.mng=1;0;35:*.mov=1;0;35:*.mp3=0;36:*.mp4=1;0;35:*.mp4v=1;0;35:*.mpc=0;36:*.mpeg=1;0;35:*.mpg=1;0;35:*.nuv=1;0;35:*.oga=0;36:*.ogg=0;36:*.ogm=1;0;35:*.ogv=1;0;35:*.ogx=1;0;35:*.opus=0;36:*.pbm=1;0;35:*.pcx=1;0;35:*.pgm=1;0;35:*.png=1;0;35:*.ppm=1;0;35:*.qt=1;0;35:*.ra=0;36:*.rar=1;0;31:*.rm=1;0;35:*.rmvb=1;0;35:*.rpm=1;0;31:*.rz=1;0;31:*.sar=1;0;31:*.spx=0;36:*.svg=1;0;35:*.svgz=1;0;35:*.swm=1;0;31:*.t7z=1;0;31:*.tar=1;0;31:*.taz=1;0;31:*.tbz=1;0;31:*.tbz2=1;0;31:*.tga=1;0;35:*.tgz=1;0;31:*.tif=1;0;35:*.tiff=1;0;35:*.tlz=1;0;31:*.txz=1;0;31:*.tz=1;0;31:*.tzo=1;0;31:*.tzst=1;0;31:*.vob=1;0;35:*.war=1;0;31:*.wav=0;36:*.webm=1;0;35:*.wim=1;0;31:*.wmv=1;0;35:*.xbm=1;0;35:*.xcf=1;0;35:*.xpm=1;0;35:*.xspf=0;36:*.xwd=1;0;35:*.xz=1;0;31:*.yuv=1;0;35:*.z=1;0;31:*.zip=1;0;31:*.zoo=1;0;31:*.zst=1;0;31:bd=40;0;33:ca=0;30;41:cd=40;0;33:di=1;0;34:do=1;0;35:ex=1;0;32:ln=1;0;36:mh=0:mi=0:or=40;0;31:ow=0;34;42:pi=40;0;33:rs=0:sg=0;30;43:so=1;0;35:st=0;37;44:su=0;37;41:tw=0;30;42``', False, None, '', False)
  MULTILINE_PROMPT = (<function is_string_or_callable>, <function ensure_string>, <function ensure_string>, ' ', 'Prompt text for 2nd+ lines of input, may be str or function which returns a str.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  MULTILINE_PROMPT_POS = (<function is_string_or_callable>, <function ensure_string>, <function ensure_string>, <xonsh.tools.DefaultNotGivenType object>, 'Indicator inserted after the line continuation marks set in ``$MULTILINE_PROMPT``. Can be used to mark the end of a semantic continuation prompt and the beginning of user input (see `Semantic Prompts <https://gitlab.freedesktop.org/Per_Bothner/specifications/blob/master/proposals/semantic-prompts.md>`_ or `WezTerm <https://wezfurlong.org/wezterm/shell-integration.html>`_ for more details). May be str or function which returns a str.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  MULTILINE_PROMPT_PRE = (<function is_string_or_callable>, <function ensure_string>, <function ensure_string>, <xonsh.tools.DefaultNotGivenType object>, 'Indicator inserted before the line continuation marks set in ``$MULTILINE_PROMPT``. Can be used to mark the start of a semantic continuation prompt (see `Semantic Prompts <https://gitlab.freedesktop.org/Per_Bothner/specifications/blob/master/proposals/semantic-prompts.md>`_ or `WezTerm <https://wezfurlong.org/wezterm/shell-integration.html>`_ for more details). May be str or function which returns a str.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  PRETTY_PRINT_RESULTS = (<function is_bool>, <function to_bool>, <function bool_to_str>, True, 'Flag for "pretty printing" return values.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  PROMPT = (<function is_string_or_callable>, <function ensure_string>, <function ensure_string>, '{YELLOW}{env_name}{RESET}{BOLD_GREEN}{user}@{hostname}{BOLD_BLUE} {cwd}{branch_color}{curr_branch: {}}{RESET} {RED}{last_return_code_if_nonzero:[{BOLD_INTENSE_RED}{}{RED}] }{RESET}{BOLD_BLUE}{prompt_end}{RESET} ', "The prompt text. May contain keyword arguments which are auto-formatted, see 'Customizing the Prompt' at http://xon.sh/tutorial.html#customizing-the-prompt. This value is never inherited from parent processes.", True, '``xonsh.environ.DEFAULT_PROMPT``', False, None, '', False)
  PROMPT_FIELDS = (<function always_true>, None, None, <function default_prompt_fields>, "Dictionary containing variables to be used when formatting ``$PROMPT`` and ``$TITLE``. See 'Customizing the Prompt' http://xon.sh/tutorial.html#customizing-the-prompt.", False, '``xonsh.prompt.base.PromptFields``', False, None, '', False)
  PROMPT_REFRESH_INTERVAL = (<function is_float>, <class 'float'>, <class 'str'>, 0.0, 'Interval (in seconds) to evaluate and update ``$PROMPT``, ``$RIGHT_PROMPT`` and ``$BOTTOM_TOOLBAR``. The default is zero (no update). NOTE: ``$UPDATE_PROMPT_ON_KEYPRESS`` must be set to ``True`` for this variable to take effect.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  PROMPT_TOKENS_FORMATTER = (<built-in function callable>, None, None, <function prompt_tokens_formatter_default>, 'Final processor that receives all tokens in the prompt template. It gives option to format the prompt with different prefix based on other tokens values. Highly useful for implementing something like powerline theme.', True, '``xonsh.prompt.base.prompt_tokens_formatter_default``', False, None, '', False)
  RIGHT_PROMPT = (<function is_string_or_callable>, <function ensure_string>, <function ensure_string>, '', 'Template string for right-aligned text at the prompt. This may be parametrized in the same way as the ``$PROMPT`` variable. Currently, this is only available in the prompt-toolkit shell.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  SHELL_TYPE = (<function is_string>, <function ensure_string>, <function ensure_string>, 'best', "Which shell is used. Currently two base shell types are supported:\n\n- ``readline`` - backed by Python's readline module\n- ``prompt_toolkit`` - uses external library of the same name\n- ``random`` - selects a random shell from the above on startup\n- ``best`` - selects the most feature-rich shell available on the user's system\n\nTo use the ``prompt_toolkit`` shell you need to have the `prompt_toolkit <https://github.com/jonathanslenders/python-prompt-toolkit>`_ library installed. To specify which shell should be used, do so in the run control file. It also accepts a class type that inherits from ``xonsh.shells.base_shell.BaseShell``.", True, '``best``', False, None, '', False)
  SUGGEST_COMMANDS = (<function is_bool>, <function to_bool>, <function bool_to_str>, True, 'When a user types an invalid command, xonsh will try to offer suggestions of similar valid commands if this is True.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  SUGGEST_MAX_NUM = (<function is_int>, <class 'int'>, <class 'str'>, 5, 'xonsh will show at most this many suggestions in response to an invalid command. If negative, there is no limit to how many suggestions are shown.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  SUGGEST_THRESHOLD = (<function is_int>, <class 'int'>, <class 'str'>, 3, 'An error threshold. If the Levenshtein distance between the entered command and a valid command is less than this value, the valid command will be offered as a suggestion. Also used for "fuzzy" tab completion of paths.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  SUPPRESS_BRANCH_TIMEOUT_MESSAGE = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'Whether or not to suppress branch timeout warning messages when getting {gitstatus} PROMPT_FIELD.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  TITLE = (<function is_string_or_callable>, <function ensure_string>, <function ensure_string>, '{current_job:{} | }{user}@{hostname}: {cwd} | xonsh', "The title text for the window in which xonsh is running. Formatted in the same manner as ``$PROMPT``, see 'Customizing the Prompt' http://xon.sh/tutorial.html#customizing-the-prompt.", True, '``xonsh.environ.DEFAULT_TITLE``', False, None, '', False)
  UPDATE_PROMPT_ON_KEYPRESS = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'Disables caching the prompt between commands, so that it would be reevaluated on each keypress. Disabled by default because of the incurred performance penalty.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  VC_BRANCH_TIMEOUT = (<function is_float>, <class 'float'>, <class 'str'>, 0.1, 'The timeout (in seconds) for version control branch computations. This is a timeout per subprocess call, so the total time to compute will be larger than this in many cases.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  VC_GIT_INCLUDE_UNTRACKED = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, "Whether or not untracked file changes should count as 'dirty' in git.", True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  VC_HG_SHOW_BRANCH = (<function is_bool>, <function to_bool>, <function bool_to_str>, True, 'Whether or not to show the Mercurial branch in the prompt.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  VIRTUAL_ENV = (<function is_string>, <function ensure_string>, <function ensure_string>, <xonsh.tools.DefaultNotGivenType object>, 'Path to the currently active Python environment.', False, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_HISTORY_MATCH_ANYWHERE = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'When searching history from a partial string (by pressing up arrow), match command history anywhere in a given line (not just the start).', True, 'False', False, None, '', False)
  XONSH_PROMPT_SHOW_SUBPROC_ERROR = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, "Whether the interactive prompt should display the ``subprocess.CalledProcessError`` message when a command at the prompt fails. The failing command's own ``stderr`` is always shown — this flag only controls xonsh's own exception printout that follows it.\n\n* ``False`` *(default)*: after a failing command the prompt returns silently; the command's ``stderr`` is still visible and ``$LAST_RETURN_CODE`` is set.\n* ``True``: xonsh additionally prints ``subprocess.CalledProcessError: Command '...' returned non-zero exit status N.``.\n\nNotes:\n\n* Per-command ``@error_raise`` decorator always shows the exception, regardless of this flag.\n* Non-interactive scripts (run via ``./script.xsh`` or ``xonsh -c``) are unaffected — there the exception propagates normally so the failure is visible.", True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_STDERR_POSTFIX = (<function is_string>, <function ensure_string>, <function ensure_string>, '', 'A format string, using the same keys and colors as ``$PROMPT``, that is appended whenever stderr is displayed. This may be used in conjunction with ``$XONSH_STDERR_PREFIX`` to start the block. For example, to have stderr appear on a red background, the prefix & postfix pair would be "{BACKGROUND_RED}" & "{RESET}". It works with ``!()`` (colors will be reduced) or ``$XONSH_CAPTURE_ALWAYS=True``.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_STDERR_PREFIX = (<function is_string>, <function ensure_string>, <function ensure_string>, '', 'A format string, using the same keys and colors as ``$PROMPT``, that is prepended whenever stderr is displayed. This may be used in conjunction with ``$XONSH_STDERR_POSTFIX`` to close out the block. For example, to have stderr appear on a red background, the prefix & postfix pair would be "{BACKGROUND_RED}" & "{RESET}". It works with ``!()`` (colors will be reduced) or ``$XONSH_CAPTURE_ALWAYS=True``.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_SUPPRESS_WELCOME = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'Suppresses the welcome message.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)

class xonsh.environ.SubprocessSetting

  Subprocess Settings

  classmethod get_doc()
  classmethod get_group_description() → str
  classmethod get_group_title() → str
  classmethod get_groups() → Iterator[tuple[tuple[Xettings, ...], tuple[tuple[str, Var], ...]]]
  classmethod get_settings() → Iterator[tuple[str, Var]]
  LAST_RETURN_CODE = (<function is_int>, <class 'int'>, <class 'str'>, 0, 'Integer return code of the last command. Only updated during interactive use, i.e. not during execution of scripts.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  THREAD_SUBPROCS = (<function is_bool_or_none>, <function to_bool_or_none>, <function bool_or_none_to_str>, True, 'Note: The ``$XONSH_CAPTURE_ALWAYS`` variable introduces finer control and you should probably use that instead.\n\nWhether or not to try to run subprocess mode in a Python thread, when trying to capture its output. There are various trade-offs.\n\nIf True, xonsh is able capture & store the stdin, stdout, and stderr of threadable subprocesses.\nThe disadvantages are listed in ``$XONSH_CAPTURE_ALWAYS``.\nThe desired effect is often up to the command, user, or use case.\n\nNone values are for internal use only and are used to turn off threading when loading xonshrc files. This is done because Bash was automatically placing new xonsh instances in the background at startup when threadable subprocs were used. Please see https://github.com/xonsh/xonsh/pull/3705 for more information.\n', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_APPEND_NEWLINE = (<function is_bool>, <function to_bool>, <function bool_to_str>, <function xonsh_append_newline>, 'Append new line when a partial line is preserved in output.', True, '``$XONSH_INTERACTIVE``', False, None, '', False)
  XONSH_BUILTINS_TO_CMD = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'If True, Python builtin names (e.g. ``dir``, ``zip``, ``type``) will be executed as a subprocess command when a matching alias or executable exists. Covers two cases that otherwise run as Python and may fail or return surprising values: (1) a bare builtin name typed as a standalone expression (``zip`` → run the ``zip`` command); (2) a builtin name followed by flag-looking arguments that also parses as a valid Python ``BinOp`` expression (``zip --help``, ``id -a``). Otherwise the Python builtin value is returned as usual.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_CAPTURE_ALWAYS = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, "Try to capture output of commands run without explicit capturing.\nIf True, xonsh will capture the output of commands run directly or in ``![]`` to the session history.\nSetting to True has the following disadvantages:\n* Some interactive commands won't work properly (like when ``git`` invokes an interactive editor).\n For more information see discussion at https://github.com/xonsh/xonsh/issues/3672.\n* Stopping these commands with ^Z (i.e. ``SIGTSTP``)\n is disabled as it causes deadlocked terminals.\n ``SIGTSTP`` may still be issued and only the physical pressing\n of ``Ctrl+Z`` is ignored.\n\nRegardless of this value, commands run in ``$()``, ``!()`` or with an IO redirection (``>`` or ``|``) will always be captured.\nSetting this to True depends on ``$THREAD_SUBPROCS`` being True.", True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_PROC_FREQUENCY = (<function is_float>, <class 'float'>, <class 'str'>, 0.0001, 'The process frequency is the time that xonsh process threads sleep for while running command pipelines. The value has units of seconds [s].', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_SUBPROC_CAPTURED_PRINT_STDERR = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'If ``True`` the stderr from captured subproc will be printed automatically.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_SUBPROC_CMD_RAISE_ERROR = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'Whether or not to raise an error if a subprocess (captured or uncaptured) returns a non-zero exit status, which indicates failure. This is most useful in xonsh scripts or modules where failures should cause an end to execution. This is less useful at a terminal. The error that is raised is a ``subprocess.CalledProcessError``. (Replaces the deprecated ``$RAISE_SUBPROC_ERROR``.)', True, <xonsh.tools.DefaultNotGivenType object>, False, None, 'RAISE_SUBPROC_ERROR', False)
  XONSH_SUBPROC_OUTPUT_FORMAT = (<function is_string>, <function ensure_string>, <function ensure_string>, 'stream_lines', 'Set output format for subprocess e.g. ``du $(ls)``. By default (``stream_lines``) subprocess operator returns text output. Set ``list_lines`` to have list of lines.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_SUBPROC_RAISE_ERROR = (<function is_bool>, <function to_bool>, <function bool_to_str>, True, 'Whether or not to raise an error when the *final* command of a logical chain (``cmd1 && cmd2`` / ``cmd1 || cmd2``) returns a non-zero exit status. Unlike ``$XONSH_SUBPROC_CMD_RAISE_ERROR`` (which raises on every individual non-zero subprocess), commands inside a logical chain do not raise on their own — only the result of the whole short-circuit evaluation is checked. Examples (with the default ``True``):\n\n* ``echo 1 && echo 2`` — last executed is ``echo 2`` (rc=0): no raise.\n* ``ls nono || echo 1`` — last executed is ``echo 1`` (rc=0): no raise.\n* ``ls nono && echo 1`` — last executed is ``ls nono`` (rc≠0): raises.\n* ``(echo 1 && ls /etc) || echo 1`` — last executed is ``ls /etc`` (rc=0): no raise.\n\nThe exception raised is a ``subprocess.CalledProcessError``.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_SUBPROC_TRACE = (<function SubprocessSetting.<lambda>>, <function SubprocessSetting.<lambda>>, <function ensure_string>, False, 'Set to ``True`` or ``1`` to show arguments list of every executed subprocess command. Use ``2`` to have a specification. Use ``3`` to have full specification. Alternatively assign a callable ``f(cmds, captured=..., specs=...)`` to format the trace output yourself — it is invoked instead of the default printer. ``specs`` is the list of :class:`SubprocSpec` objects about to be executed; ``CommandPipeline`` is not yet built at this point.', True, 'By default it just prints ``cmds`` like below.\n\n.. code-block:: xonsh\n\n def _tracer(cmds, captured, specs):\n # ``specs`` is a list of SubprocSpec — use e.g. ``s.args``,\n # ``s.alias``, ``s.binary_loc``, ``s.threadable`` for details.\n print(f"TRACE SUBPROC: {cmds}, captured={captured}", file=sys.stderr)\n\n $XONSH_SUBPROC_TRACE = _tracer', False, None, '', False)

class xonsh.environ.SystemSetting

  System Environment Variables

  Common, well-known variables inherited from the surrounding OS / shell (POSIX-standard and XDG Base Directory Specification). They are not xonsh-specific — xonsh only provides sensible defaults and lets scripts read/write them the same way any other shell would.

  classmethod get_doc()
  classmethod get_group_description() → str
  classmethod get_group_title() → str
  classmethod get_groups() → Iterator[tuple[tuple[Xettings, ...], tuple[tuple[str, Var], ...]]]
  classmethod get_settings() → Iterator[tuple[str, Var]]
  HOSTNAME = (<function is_string>, <function ensure_string>, <function ensure_string>, <function SystemSetting.<lambda>>, 'Automatically set to the name of the current host.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  HOSTTYPE = (<function is_string>, <function ensure_string>, <function ensure_string>, <function SystemSetting.<lambda>>, 'Automatically set to a string that fully describes the system type on which xonsh is executing.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  OLDPWD = (<function is_string>, <function ensure_string>, <function ensure_string>, '.', 'Used to represent a previous present working directory.', False, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  PATH = (<function is_env_path>, <function str_to_env_path>, <function env_path_to_str>, ('/sbuild-nonexistent/bin', '/usr/local/sbin', '/usr/local/bin', '/usr/sbin', '/usr/bin', '/sbin', '/bin', '/usr/games', '/usr/local/games'), 'List of strings representing where to look for executables.', True, "\n\n- **Windows**: ``Path`` value from registry ``HKEY_LOCAL_MACHINE\\SYSTEM\\CurrentControlSet\\Control\\Session Manager\\Environment``\n- **macOS**: ``('/usr/local/bin', '/usr/bin', '/bin', '/usr/sbin', '/sbin')``\n- **Linux/Cygwin/MSYS** (arch-like): ``('/usr/local/sbin', '/usr/local/bin', '/usr/bin', '/usr/bin/site_perl', '/usr/bin/vendor_perl', '/usr/bin/core_perl')``\n- **Linux/Cygwin/MSYS** (other): ``('~/bin', '/usr/local/sbin', '/usr/local/bin', '/usr/sbin', '/usr/bin', '/sbin', '/bin', '/usr/games', '/usr/local/games')``", False, None, '', False)
  PATHEXT = (<function is_nonstring_seq_of_strings>, <function pathsep_to_upper_seq>, <function seq_to_upper_pathsep>, [], 'Sequence of extension strings (e.g., ``.EXE``) for filtering valid executables by. Each element must be uppercase.', True, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  PWD = (<function is_string>, <function ensure_string>, <function ensure_string>, '/build/xonsh-FqRqDH/xonsh-0.24.0+dfsg/docs', 'Current working directory.', False, 'os.getcwd()', False, None, '', False)
  SHLVL = (<function is_valid_shlvl>, <function to_shlvl>, <class 'str'>, 0, "Shell nesting level typed as integer, mirrors bash's ``$SHLVL``.", False, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  TERM = (<function is_string>, <function ensure_string>, <function ensure_string>, <xonsh.tools.DefaultNotGivenType object>, 'TERM is sometimes set by the terminal emulator. This is used (when valid) to determine whether the terminal emulator can support the selected shell, or whether or not to set the title. Users shouldn\'t need to set this themselves. Note that this variable should be set as early as possible in order to ensure it is effective. Here are a few options:\n\n* Set this from the program that launches xonsh. On POSIX systems, \n this can be performed by using env, e.g. \n ``/usr/bin/env TERM=xterm-color xonsh`` or similar.\n* From the xonsh command line, namely ``xonsh -DTERM=xterm-color``.\n* In the config file with ``{"env": {"TERM": "xterm-color"}}``.\n* Lastly, in xonshrc with ``$TERM``\n\nIdeally, your terminal emulator will set this correctly but that does not always happen.', False, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XDG_CACHE_HOME = (<function is_string>, <function ensure_string>, <function ensure_string>, '/sbuild-nonexistent/.cache', 'The base directory relative to which user-specific non-essential data files should be stored.', True, '``~/.cache``', False, None, '', False)
  XDG_CONFIG_HOME = (<function is_string>, <function ensure_string>, <function ensure_string>, '/sbuild-nonexistent/.config', 'Open desktop standard configuration home dir. This is the same default as used in the standard.', False, '``~/.config``', False, None, '', False)
  XDG_DATA_DIRS = (<function is_env_path>, <function str_to_env_path>, <function env_path_to_str>, <function xdg_data_dirs>, 'A list of directories where system level data files are stored.', True, "On Windows: ``[%ProgramData%]`` (normally C:\\ProgramData)\n - More Info: https://docs.microsoft.com/en-us/windows-hardware/customize/desktop/unattend/microsoft-windows-shell-setup-folderlocations-programdata\n\nOn Linux and Unix based systemd it is the same as in open-desktop standard: ``['/usr/share', '/usr/local/share']``", False, None, '', False)
  XDG_DATA_HOME = (<function is_string>, <function ensure_string>, <function ensure_string>, '/sbuild-nonexistent/.local/share', 'Open desktop standard data home dir. This is the same default as used in the standard.', True, '``~/.local/share``', False, None, '', False)

class xonsh.environ.Var(validate: Callable | None = <function always_true>, convert: Callable | None = None, detype: Callable | None = <function ensure_string>, default: Any = <xonsh.tools.DefaultNotGivenType object>, doc: str = '', is_configurable: bool | LazyBool = True, doc_default: str | DefaultNotGivenType = <xonsh.tools.DefaultNotGivenType object>, can_store_as_str: bool = False, pattern: Pattern | None = None, sync: str = '', deprecated: bool = False)

  Named tuples whose elements represent environment variable validation, conversion, detyping; default values; and documentation.

  Attributes:
    validate func

      Validator function returning a bool; checks that the variable is of the expected type.

    convert func

      Function to convert variable from a string representation to its type.

    detype func

      Function to convert variable from its type to a string representation.

    default

      Default value for variable. If set to DefaultNotGiven, raise KeyError instead of returning this default value. Used for env vars defined outside of Xonsh.

    doc str, optional

      The environment variable docstring.

    doc_default str, optional

      Custom docstring for the default value for complex defaults.

    is_configurable bool, optional

      Flag for whether the environment variable is configurable or not.

    can_store_as_str bool, optional

      Flag for whether the environment variable should be stored as a string. This is used when persisting a variable that is not JSON serializable to the config file. For example, sets, frozensets, and potentially other non-trivial data types. default, False.

    pattern

      a regex pattern to match for the given variable

    sync str, optional

      The name of env variable for mirroring the setting.

    deprecated bool, optional

      Show warning about deprecated variable in case of setting.

  Create new instance of Var(validate, convert, detype, default, doc, is_configurable, doc_default, can_store_as_str, pattern, sync, deprecated)

  classmethod for_locale(lcle: str)
  classmethod no_default(type_str: str, doc: str = '', **kwargs)
  classmethod with_default(default: object, doc: str = '', doc_default: str | DefaultNotGivenType = <xonsh.tools.DefaultNotGivenType object>, type_str: str = '', **kwargs)

    fill arguments from the value of default

  count(value, /)

    Return number of occurrences of value.

  index(value, start=0, stop=sys.maxsize, /)

    Return first index of value.

    Raises ValueError if the value is not present.

  set_attrs(attrs: dict)
  can_store_as_str: bool

    Alias for field number 7

  convert: Callable | None

    Alias for field number 1

  default: Any

    Alias for field number 3

  deprecated: bool

    Alias for field number 10

  detype: Callable | None

    Alias for field number 2

  doc: str

    Alias for field number 4

  doc_default: str | DefaultNotGivenType

    Alias for field number 6

  is_configurable: bool | LazyBool

    Alias for field number 5

  pattern: Pattern | None

    Alias for field number 8

  sync: str

    Alias for field number 9

  validate: Callable | None

    Alias for field number 0

class xonsh.environ.VarPattern(pattern, var_type, exclude=None)

  A pattern rule for dynamic env var typing.

  When stored as the value of an env variable, any env var whose name matches `pattern` will receive the type handling specified by `var_type` (a key in `ENSURERS`, e.g. `"env_path"`).

  Example:

      $XONSH_ENV_PATTERN_PATH = VarPattern(r"\w*PATH$", "env_path")

  static detype_var_pattern(x)
  static is_var_pattern(x)
  static to_var_pattern(x)
  match(key)
  to_var()

    Return a Var with the type handling from ENSURERS.

class xonsh.environ.WindowsSetting

  Windows OS

  classmethod get_doc()
  classmethod get_group_description() → str
  classmethod get_group_title() → str
  classmethod get_groups() → Iterator[tuple[tuple[Xettings, ...], tuple[tuple[str, Var], ...]]]
  classmethod get_settings() → Iterator[tuple[str, Var]]
  ANSICON = (<function is_string>, <function ensure_string>, <function ensure_string>, <xonsh.tools.DefaultNotGivenType object>, 'This is used on Windows to set the title, if available.', False, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  FORCE_POSIX_PATHS = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'Forces forward slashes (``/``) on Windows systems when using auto completion if set to anything truthy.', False, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  INTENSIFY_COLORS_ON_WIN = (<function always_false>, <function intensify_colors_on_win_setter>, <function bool_to_str>, True, 'Enhance style colors for readability when using the default terminal (``cmd.exe``) on Windows. Blue colors, which are hard to read, are replaced with cyan. Other colors are generally replaced by their bright counter parts.', False, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)
  XONSH_WIN_CONSOLE_HISTORY_BUFFERS = (<function is_int>, <class 'int'>, <class 'str'>, 32, 'On Windows, number of console command-history buffers to reserve at startup (one per attached console process). The default of 4 is exhausted by nested consoles (xonsh -> ``py`` -> ``python``), losing up-arrow history in the child REPL; ``0`` disables. For the other fields, set this to ``0`` and call ``@.imp.xonsh.platforms.winutils.set_console_history_info(nbuf=64, bufsize=1024, flags=1)`` from your xonsh RC.', False, <xonsh.tools.DefaultNotGivenType object>, False, None, '', False)

class xonsh.environ.Xettings

  Parent class - All setting classes will be inheriting from this. The first line of those class’s docstring will become the group’s title. Rest of the docstring will become the description of that Group of settings.

  classmethod get_doc()
  classmethod get_group_description() → str
  classmethod get_group_title() → str
  classmethod get_groups() → Iterator[tuple[tuple[Xettings, ...], tuple[tuple[str, Var], ...]]]
  classmethod get_settings() → Iterator[tuple[str, Var]]

class xonsh.environ.XontribSetting

  Xontrib Settings

  classmethod get_doc()
  classmethod get_group_description() → str
  classmethod get_group_title() → str
  classmethod get_groups() → Iterator[tuple[tuple[Xettings, ...], tuple[tuple[str, Var], ...]]]
  classmethod get_settings() → Iterator[tuple[str, Var]]
  XONTRIBS_AUTOLOAD_DISABLED = (<function is_bool>, <function to_bool>, <function bool_to_str>, False, 'Controls auto-loading behaviour of xontrib packages at the startup.\n\n* Set this to ``True`` to disable autoloading completely.\n* Setting this to a list of xontrib names will block loading those specifically.', True, 'Xontribs with ``xonsh.xontrib`` entrypoint will be loaded automatically by default.', False, None, '', False)

xonsh.environ.default_completer_dirs(env)

  By default, the following paths are searched. 1. `$XONSH_CONFIG_DIR/completions` - user level completions 2. `$XONSH_SYS_CONFIG_DIR/completions` - system level completions 3. `$XONSH_DATA_DIR/generated_completions` - auto generated completers from man pages 4. `$XDG_DATA_DIRS/xonsh/vendor_completions` - completers from other programs can be placed here.

  Other than this, Python package namespace `xompletions` can be used to put completer modules as well.

xonsh.environ.default_env(env=None)

  Constructs a default xonsh environment.

xonsh.environ.default_lscolors(env)

  Gets a default instanse of LsColors

xonsh.environ.default_prompt_fields(env)

  `xonsh.prompt.base.PromptFields`

xonsh.environ.default_value(f)

  Decorator for making callable default values.

xonsh.environ.default_xonshrc(env) → tuple[str, ...]

  `['$XONSH_SYS_CONFIG_DIR/xonshrc', '$XONSH_CONFIG_DIR/xonsh/rc.xsh', '~/.xonshrc']`

xonsh.environ.default_xonshrcdir(env)

  `['$XONSH_SYS_CONFIG_DIR/rc.d', '$XONSH_CONFIG_DIR/rc.d']`

xonsh.environ.ensure_ls_colors_in_env(spec=None, **kwargs)

  This ensures that the `$LS_COLORS` environment variable is in the environment. This fires exactly once upon the first time the ls command is called.

xonsh.environ.foreign_env_fixes(ctx)

  Environment fixes for all operating systems

xonsh.environ.get_config_paths(env: Env, name: str) → tuple[str, ...]

xonsh.environ.get_home_xonshrc_path()

  Cross-platform implementation of getting `~/.xonshrc` path.

xonsh.environ.histcontrol_csv_to_set(x)

  Convert HISTCONTROL value, warning if erasedups is used.

xonsh.environ.is_callable_default(x)

  Checks if a value is a callable default.

xonsh.environ.is_env_path(x)

  This tests if something is an environment path, ie a list of strings.

xonsh.environ.is_lscolors(x)

  Checks if an object is an instance of LsColors

xonsh.environ.load_origin_env_from_file()

xonsh.environ.locale_convert(key)

  Creates a converter for a locale key.

xonsh.environ.locate_binary(name)

  Locates an executable on the file system.

  NOT RECOMMENDED because `commands_cache.locate_binary` contains `update_cache` with scanning all files in `$PATH`. First of all take a look into `xonsh.specs.executables` for more fast implementation the locate operation.

xonsh.environ.make_args_env(args=None)

  Makes a dictionary containing the `$ARGS` and `$ARG<N>` environment variables. If the supplied ARGS is None, then sys.argv is used.

xonsh.environ.save_origin_env_to_file(env, session_id)

xonsh.environ.scan_dir_for_source_files(path: str)

xonsh.environ.str_to_abs_path(x)

  Converts a string to an absolute path.

xonsh.environ.str_to_env_path(x)

  Converts a string to an environment path, ie a list of strings, splitting on the OS separator.

xonsh.environ.str_to_path(x)

  Converts a string to a path.

xonsh.environ.to_debug(x)

  Converts value using to_bool_or_int() and sets this value on as the execer’s debug level.

xonsh.environ.windows_foreign_env_fixes(ctx)

  Environment fixes for Windows. Operates in-place.

xonsh.environ.xdg_data_dirs(env)
  On Windows: `[%ProgramData%]` (normally C:ProgramData)

    - More Info: https://docs.microsoft.com/en-us/windows-hardware/customize/desktop/unattend/microsoft-windows-shell-setup-folderlocations-programdata

  On Linux and Unix based systemd it is the same as in open-desktop standard: `['/usr/share', '/usr/local/share']`

xonsh.environ.xonsh_append_newline(env)

  Appends a newline if we are in interactive mode

xonsh.environ.xonsh_cache_dir(env)

  Ensures and returns the `$XONSH_CACHE_DIR`

xonsh.environ.xonsh_config_dir(env)

  `$XDG_CONFIG_HOME/xonsh`

xonsh.environ.xonsh_data_dir(env)

  Ensures and returns the `$XONSH_DATA_DIR`

xonsh.environ.xonsh_script_run_control(filename, ctx, env, execer=None, login=True)

  Loads a xonsh file and applies it as a run control. Any exceptions are logged here, returns boolean indicating success.

xonsh.environ.xonsh_sys_config_dir(env)

  On Linux & macOS: `'/etc/xonsh'` On Windows: `'%ALLUSERSPROFILE%\\xonsh'`

xonsh.environ.xonshconfig(env)

  Ensures and returns the `$XONSHCONFIG`

xonsh.environ.xonshrc_context(rcfiles=None, rcdirs=None, execer=None, ctx=None, env=None, login=True)

  Attempts to read in all xonshrc files (and search xonshrc directories), and returns the list of rc file paths successfully loaded, in the order of loading.