Environment (xonsh.environ)

Environment for the xonsh shell.

class xonsh.environ.Ensurer

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

Create new instance of Ensurer(validate, convert, detype)

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.

convert

Alias for field number 1

detype

Alias for field number 2

validate

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.
detype()[source]
static detypeable(val)[source]
get(key, default=None)[source]

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

get_docs(key, default=VarDocs(docstr='<no documentation>', configurable=True, default=<xonsh.tools.DefaultNotGivenType object>, store_as_str=False))[source]

Gets the documentation for the environment variable.

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

Gets an ensurer for the given key.

is_manually_set(varname)[source]

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.

replace_env()[source]

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
swap(other=None, **kwargs)[source]

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.

undo_replace_env()[source]

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
arg_regex
class xonsh.environ.VarDocs

Named tuple for environment variable documentation

Parameters:

docstr : str

The environment variable docstring.

configurable : bool, optional

Flag for whether the environment variable is configurable or not.

default : str, optional

Custom docstring for the default value for complex defaults. Is this is DefaultNotGiven, then the default will be looked up from DEFAULT_VALUES and converted to a str.

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.

Create new instance of VarDocs(docstr, configurable, default, store_as_str)

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.

configurable

Alias for field number 1

default

Alias for field number 2

docstr

Alias for field number 0

store_as_str

Alias for field number 3

xonsh.environ.branch_bg_color()[source]

Return red if the current branch is dirty, yellow if the dirtiness can not be determined, and green if it clean. These are bacground colors.

xonsh.environ.branch_color()[source]

Return red if the current branch is dirty, yellow if the dirtiness can not be determined, and green if it clean. These are bold, intense colors for the foreground.

xonsh.environ.current_branch(pad=NotImplemented)[source]

Gets the branch for a current working directory. Returns an empty string if the cwd is not a repository. This currently only works for git and hg and should be extended in the future. If a timeout occurred, the string ‘<branch-timeout>’ is returned.

xonsh.environ.default_env(env=None, config=None, login=True)[source]

Constructs a default xonsh environment.

xonsh.environ.default_prompt()[source]

Creates a new instance of the default prompt.

xonsh.environ.default_value(f)[source]

Decorator for making callable default values.

xonsh.environ.default_xonshrc()[source]

Creates a new instance of the default xonshrc tuple.

xonsh.environ.dirty_working_directory(cwd=None)[source]

Returns a boolean as to whether there are uncommitted files in version control repository we are inside. If this cannot be determined, returns None. Currently supports git and hg.

xonsh.environ.env_name(pre_chars='(', post_chars=')')[source]

Extract the current environment name from $VIRTUAL_ENV or $CONDA_DEFAULT_ENV if that is set

xonsh.environ.foreign_env_fixes(ctx)[source]

Environment fixes for all operating systems

xonsh.environ.get_git_branch()[source]

Attempts to find the current git branch. If no branch is found, then an empty string is returned. If a timeout occured, the timeout exception (subprocess.TimeoutExpired) is returned.

xonsh.environ.get_hg_branch(cwd=None, root=None)[source]
xonsh.environ.git_dirty_working_directory(cwd=None, include_untracked=False)[source]

Returns whether or not the git directory is dirty. If this could not be determined (timeout, file not sound, etc.) then this returns None.

xonsh.environ.hg_dirty_working_directory()[source]

Computes whether or not the mercurial working directory is dirty or not. If this cannot be deterimined, None is returned.

xonsh.environ.is_callable_default(x)[source]

Checks if a value is a callable default.

xonsh.environ.is_template_string(template, formatter_dict=None)[source]

Returns whether or not the string is a valid template.

xonsh.environ.load_static_config(ctx, config=None)[source]

Loads a static configuration file from a given context, rather than the current environment. Optionally may pass in configuration file name.

xonsh.environ.locale_convert(key)[source]

Creates a converter for a locale key.

xonsh.environ.locate_binary(name)[source]

Locates an executable on the file system.

xonsh.environ.multiline_prompt(curr='')[source]

Returns the filler text for the prompt in multiline scenarios.

xonsh.environ.partial_format_prompt(template=<xonsh.lazyasd.LazyObject object>, formatter_dict=None)[source]

Formats a xonsh prompt template string.

xonsh.environ.to_debug(x)[source]

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

xonsh.environ.vte_new_tab_cwd()[source]

This prints an escape squence that tells VTE terminals the hostname and pwd. This should not be needed in most cases, but sometimes is for certain Linux terminals that do not read the PWD from the environment on startup. Note that this does not return a string, it simply prints and flushes the escape sequence to stdout directly.

xonsh.environ.windows_foreign_env_fixes(ctx)[source]

Environment fixes for Windows. Operates in-place.

xonsh.environ.xonsh_config_dir(env)[source]

Ensures and returns the $XONSH_CONFIG_DIR

xonsh.environ.xonsh_data_dir(env)[source]

Ensures and returns the $XONSH_DATA_DIR

xonsh.environ.xonshconfig(env)[source]

Ensures and returns the $XONSHCONFIG

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

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