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.

help(key)[source]

Get information about a specific enviroment variable.

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.default_env(env=None)[source]

Constructs a default xonsh environment.

xonsh.environ.default_value(f)[source]

Decorator for making callable default values.

xonsh.environ.default_xonshrc(env)[source]

Creates a new instance of the default xonshrc tuple.

xonsh.environ.foreign_env_fixes(ctx)[source]

Environment fixes for all operating systems

xonsh.environ.is_callable_default(x)[source]

Checks if a value is a callable default.

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.static_config_run_control(filename, ctx, env, execer=None, login=True)[source]

Loads a static config file and applies it as a run control.

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.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.xonsh_script_run_control(filename, ctx, env, execer=None, login=True)[source]

Loads a xonsh file and applies it as a run control.

xonsh.environ.xonshconfig(env)[source]

Ensures and returns the $XONSHCONFIG

xonsh.environ.xonshrc_context(rcfiles=None, execer=None, ctx=None, env=None, login=True)[source]

Attempts to read in all xonshrc files and return the context.