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.¶
-
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.
-
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.
branch_bg_color
()[source]¶ Return red if the current branch is dirty, yellow if the dirtiness can not be determined, and green if it clean. These are bacground colors.
-
xonsh.environ.
branch_color
()[source]¶ Return red if the current branch is dirty, yellow if the dirtiness can not be determined, and green if it clean. These are bold, intense colors for the foreground.
-
xonsh.environ.
current_branch
(pad=NotImplemented)[source]¶ Gets the branch for a current working directory. Returns an empty string if the cwd is not a repository. This currently only works for git and hg and should be extended in the future. If a timeout occurred, the string ‘<branch-timeout>’ is returned.
-
xonsh.environ.
default_env
(env=None, config=None, login=True)[source]¶ Constructs a default xonsh environment.
-
xonsh.environ.
dirty_working_directory
(cwd=None)[source]¶ Returns a boolean as to whether there are uncommitted files in version control repository we are inside. If this cannot be determined, returns None. Currently supports git and hg.
-
xonsh.environ.
env_name
(pre_chars='(', post_chars=')')[source]¶ Extract the current environment name from $VIRTUAL_ENV or $CONDA_DEFAULT_ENV if that is set
-
xonsh.environ.
get_git_branch
()[source]¶ Attempts to find the current git branch. If no branch is found, then an empty string is returned. If a timeout occured, the timeout exception (subprocess.TimeoutExpired) is returned.
-
xonsh.environ.
git_dirty_working_directory
(cwd=None, include_untracked=False)[source]¶ Returns whether or not the git directory is dirty. If this could not be determined (timeout, file not sound, etc.) then this returns None.
-
xonsh.environ.
hg_dirty_working_directory
()[source]¶ Computes whether or not the mercurial working directory is dirty or not. If this cannot be deterimined, None is returned.
-
xonsh.environ.
is_template_string
(template, formatter_dict=None)[source]¶ Returns whether or not the string is a valid template.
-
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.
multiline_prompt
(curr='')[source]¶ Returns the filler text for the prompt in multiline scenarios.
-
xonsh.environ.
partial_format_prompt
(template='{env_name:{} }{BOLD_GREEN}{user}@{hostname}{BOLD_BLUE} {cwd}{branch_color}{curr_branch: {}}{NO_COLOR} {BOLD_BLUE}{prompt_end}{NO_COLOR} ', formatter_dict=None)[source]¶ Formats a xonsh prompt template string.
-
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.
vte_new_tab_cwd
()[source]¶ This prints an escape squence that tells VTE terminals the hostname and pwd. This should not be needed in most cases, but sometimes is for certain Linux terminals that do not read the PWD from the environment on startup. Note that this does not return a string, it simply prints and flushes the escape sequence to stdout directly.