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)

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.

detype()

get(key, default=None)

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

Gets the documentation for the environment variable.

get_ensurer(key, default=None)

Gets an ensurer 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.

replace_env()

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

set_ensurer(key, value)

Sets an ensurer.

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(*args, **kwargs)

Helps convert to/from $LS_COLORS format, respecting the xonsh color style. This accepts the same inputs as dict().

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.

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',), 'ln': ('BOLD_CYAN',), 'mh': ('NO_COLOR',), 'mi': ('NO_COLOR',), 'or': ('BACKGROUND_BLACK', 'RED'), 'ow': ('BLUE', 'BACKGROUND_GREEN'), 'pi': ('BACKGROUND_BLACK', 'YELLOW'), 'rs': ('NO_COLOR',), 'sg': ('BLACK', 'BACKGROUND_YELLOW'), 'so': ('BOLD_PURPLE',), 'st': ('WHITE', 'BACKGROUND_BLUE'), 'su': ('WHITE', 'BACKGROUND_RED'), 'tw': ('BLACK', 'BACKGROUND_GREEN')}

style

The ANSI color style for the current XONSH_COLOR_STYLE

style_name

Current XONSH_COLOR_STYLE value

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)

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.