Environment (xonsh.environ)

Environment for the xonsh shell.

class xonsh.environ.DefaultNotGivenType[source]

Singleton for representing when no default value is given.

class xonsh.environ.Ensurer

Named tuples whose elements are functions that represent environment variable validation, conversion, detyping.

count(value) → integer -- return number of occurrences of value
index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.


Alias for field number 1


Alias for field number 2


Alias for field number 0

class xonsh.environ.Env(*args, **kwargs)[source]

A xonsh environment, whose variables have limited typing (unlike BASH). Most variables are, by default, strings (like BASH). 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 catergory 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.
get(key, default=<xonsh.environ.DefaultNotGivenType object>)[source]

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

get_ensurer(key, default=Ensurer(validate=<function always_true at 0x2b46094dda60>, convert=None, detype=<function ensure_string at 0x2b46094ddb70>))[source]

Gets an ensurer for the given key.

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.


Replaces the contents of os.environ with a detyped version of the xonsh environement.

setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D

Replaces the contents of os.environ with a detyped version of the xonsh environement.

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: 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

Return red if the current branch is dirty, otherwise green

xonsh.environ.call_hg_command(command, cwd)[source]

Gets the branch for a current working directory. Returns None if the cwd is not a repository. This currently only works for git and hg and should be extended in the future.


Constructs a default xonsh environment.


Decorator for making callable default values.


Returns a boolean as to whether there are uncommitted files in version control repository we are inside. Currently supports git and hg.

xonsh.environ.format_prompt(template='{BOLD_GREEN}{user}@{hostname}{BOLD_BLUE} {cwd}{branch_color}{curr_branch} {BOLD_BLUE}{prompt_end}{NO_COLOR} ', formatter_dict=None)[source]

Formats a xonsh prompt template string.

xonsh.environ.get_hg_branch(cwd=None, root=None)[source]
xonsh.environ.hg_dirty_working_directory(cwd=None, root=None)[source]

Checks if a value is a callable default.


Loads a static configuration file from a given context, rather than the current environment.


Creates a converter for a locale key.

xonsh.environ.locate_binary(name, cwd)[source]

Returns the filler text for the prompt in multiline scenarios.


Environment fixes for Windows. Operates in-place.


Ensures and returns the $XONSH_CONFIG_DIR


Ensures and returns the $XONSH_DATA_DIR


Ensures and returns the $XONSHCONFIG

xonsh.environ.xonshrc_context(rcfiles=None, execer=None)[source]

Attempts to read in xonshrc file, and return the contents.