Environment (xonsh.environ)

Environment for the xonsh shell.

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

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

namestr

Environment variable name to deregister. Typically all caps.

detype()

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_detyper(key, default=None)

Gets a detyper for the given key.

get_docs(key, default=None)

Gets the documentation for the environment variable.

get_validator(key, default=None)

Gets a validator for the given key.

help(key)

Get information about a specific environment variable.

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>, doc_configurable=True, doc_default=<xonsh.tools.DefaultNotGivenType object>, doc_store_as_str=False)

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

Parameters

namestr

Environment variable name to register. Typically all caps.

typestr, 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.

defaultoptional

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

docstr, optional

Docstring for variable.

validatefunc, optional

Function to validate type.

convertfunc, optional

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

detypefunc, optional

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

doc_configurablebool, optional

Flag for whether the environment variable is configurable or not.

doc_defaultstr, optional

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

doc_store_as_strbool, 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.

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

swap(other=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.

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: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v

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

class xonsh.environ.LsColors(ini_dict: Optional[dict] = 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()).

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

classmethod convert(x)

Converts an object to LsColors, if needed.

detype()

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

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.

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: 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.Var(validate=<function always_true>, convert=None, detype=<function ensure_string>, default=None, doc='', doc_configurable=True, doc_default=<xonsh.tools.DefaultNotGivenType object>, doc_store_as_str=False)

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

Parameters

validatefunc

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

convertfunc

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

detypefunc

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.

docstr

The environment variable docstring.

doc_configurablebool, optional

Flag for whether the environment variable is configurable or not.

doc_defaultstr, 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.

doc_store_as_strbool, 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 Var(validate, convert, detype, default, doc, doc_configurable, doc_default, doc_store_as_str)

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.

convert

Alias for field number 1

default

Alias for field number 3

detype

Alias for field number 2

doc

Alias for field number 4

doc_configurable

Alias for field number 5

doc_default

Alias for field number 6

doc_store_as_str

Alias for field number 7

validate

Alias for field number 0

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_value(f)

Decorator for making callable default values.

xonsh.environ.default_xonshrc(env)

Creates a new instance of the default xonshrc tuple.

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.is_callable_default(x)

Checks if a value is a callable default.

xonsh.environ.is_lscolors(x)

Checks if an object is an instance of LsColors

xonsh.environ.locale_convert(key)

Creates a converter for a locale key.

xonsh.environ.locate_binary(name)

Locates an executable on the file system.

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.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.xonsh_append_newline(env)

Appends a newline if we are in interactive mode

xonsh.environ.xonsh_config_dir(env)

Ensures and returns the $XONSH_CONFIG_DIR

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.

xonsh.environ.xonshconfig(env)

Ensures and returns the $XONSHCONFIG

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

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