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.

property convert

Alias for field number 1

property detype

Alias for field number 2

property 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(). The link target is represented by the special "TARGET" color.

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

property style

The ANSI color style for the current XONSH_COLOR_STYLE

property style_name

Current XONSH_COLOR_STYLE value

class xonsh.environ.VarDocs

Named tuple for environment variable documentation

Parameters

docstrstr

The environment variable docstring.

configurablebool, optional

Flag for whether the environment variable is configurable or not.

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.

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

property configurable

Alias for field number 1

property default

Alias for field number 2

property docstr

Alias for field number 0

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