Environment (xonsh.environ
)¶
Environment for the xonsh shell.
-
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 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)[source]¶ Deregister an enviornment variable and all its type handling, default value, doc.
- Parameters
- namestr
Environment variable name to deregister. Typically all caps.
-
get
(key, default=None)[source]¶ The environment will look up default values from its own defaults if a default is not given here.
-
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
()[source]¶ 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)[source]¶ 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 fromDEFAULT_VALUES
and converted to astr
.- 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
()[source]¶ 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)[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 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)[source]¶ 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
fromdircolors
(filename=None)[source]¶ Constructs an LsColors instance by running dircolors. If a filename is provided, it is passed down to the dircolors command.
-
classmethod
fromstring
(s)[source]¶ 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',), '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.
ensure_ls_colors_in_env
(spec=None, **kwargs)[source]¶ 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.
make_args_env
(args=None)[source]¶ 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)[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.