rez.shells

Pluggable API for creating subshells using different programs, such as bash.

rez.shells.get_shell_types() → list[str]

Returns the available shell types: bash, tcsh etc.

Returns:

Shells.

Return type:

list[str]

rez.shells.get_shell_class(shell: str | None = None) → type[Shell]

Get the plugin class associated with the given or current shell.

Returns:

Plugin class for shell.

Return type:

type[Shell]

rez.shells.create_shell(shell: str | None = None, **kwargs: Any) → Shell

Returns a Shell of the given or current type.

Returns:

Instance of given shell.

Return type:

Shell

class rez.shells.Shell

Bases: ActionInterpreter

Class representing a shell, such as bash or tcsh.

schema_dict = {'prompt': <class 'str'>}

classmethod name() → str

Plugin name.

classmethod executable_name() → str

Name of executable to create shell instance.

classmethod executable_filepath() → str

Get full filepath to executable, or raise if not found.

property executable: str

classmethod is_available() → bool

Determine if the shell is available to instantiate.

Returns:

True if the shell can be created.

Return type:

bool

classmethod file_extension() → str

Get the file extension associated with the shell.

Returns:

Shell file extension.

Return type:

str

classmethod startup_capabilities(rcfile: str | None | Literal[False] = False, norc: bool = False, stdin: bool = False, command: bool = False) → tuple[str | None | Literal[False], bool, bool, bool]

Given a set of options related to shell startup, return the actual options that will be applied.

Returns:

4-tuple representing applied value of each option.

Return type:

tuple

classmethod get_syspaths()

__init__() → None

get_output(style: OutputStyle = OutputStyle.file) → str

Returns any implementation specific data.

Parameters:

style (OutputStyle) – Style affecting output format.

Returns:

Depends on implementation, but usually a code string.

new_shell() → Self

Returns A new, reset shell of the same type.

classmethod find_executable(name: str, check_syspaths: bool = False) → str

Find an executable.

Parameters:

• name (str) – Program name.

• check_syspaths (bool) – If True, check the standard system paths as well, if program was not found on current $PATH.

Returns:

Full filepath of executable.

Return type:

str

spawn_shell(context_file: str, tmpdir, rcfile: str | None = None, norc: bool = False, stdin: bool = False, command=None, env=None, quiet: bool = False, pre_command: str | list[str] | None = None, add_rez: bool = True, package_commands_sourced_first=None, **Popen_args) → subprocess.Popen

Spawn a possibly interactive subshell.

Parameters:

• context_file – File that must be sourced in the new shell, this configures the Rez environment.

• tmpdir – Tempfiles, if needed, should be created within this path.

• rcfile – Custom startup script.

• norc – Don’t run startup scripts. Overrides rcfile.

• stdin – If True, read commands from stdin in a non-interactive shell. If a different non-False value, such as subprocess.PIPE, the same occurs, but stdin is also passed to the resulting subprocess.Popen object.

• command – If not None, execute this command in a non-interactive shell. If an empty string, don’t run a command, but don’t open an interactive shell either.

• env – Environ dict to execute the shell within; uses the current environment if None.

• quiet – If True, don’t show the configuration summary, and suppress any stdout from startup scripts.

• pre_command – Command to inject before the shell command itself. This is for internal use.

• add_rez – If True, assume this shell is being used with rez, and do things such as set the prompt etc.

• package_commands_sourced_first – If True, source the context file before sourcing startup scripts (such as .bashrc). If False, source the context file AFTER. If None, use the configured setting.

• popen_args – args to pass to the shell process object constructor.

Returns:

A subprocess.Popen object representing the shell process.

Return type:

subprocess.Popen

classmethod convert_tokens(value) → str

Converts any token like ${VAR} and $VAR to shell specific form. Uses the ENV_VAR_REGEX to correctly parse tokens.

Parameters:

value – str to convert

Returns:

str with shell specific variables

classmethod get_key_token(key) → str

Encodes the environment variable into the shell specific form. Shells might implement multiple forms, but the most common/safest should be returned here.

Parameters:

key – Variable name to encode

Returns:

str of encoded token form

classmethod get_all_key_tokens(key: str) → list[str]

Encodes the environment variable into the shell specific forms. Shells might implement multiple forms, but the most common/safest should be always returned at index 0.

Parameters:

key – Variable name to encode

Returns:

list of str with encoded token forms

classmethod line_terminator() → str

Returns:

default line terminator

Return type:

str

classmethod join(command: Iterable[str]) → str

Note: Default to unix sh/bash- friendly behaviour.

Parameters:

command – A sequence of program arguments to be joined into a single string that can be executed in the current shell.

Returns:

A string object representing the command.

ENV_VAR_REGEX = re.compile('\\${([^\\{\\}]+?)}|\\$([a-zA-Z_]+[a-zA-Z0-9_]*?)')

alias(key, value)

appendenv(key, value: str | EscapedString)

This is optional, but if it is not implemented, you must implement setenv.

command(value)

comment(value: str)

error(value: str)

escape_string(value: str | EscapedString, is_path: bool = False) → str

Escape a string.

Escape the given string so that special characters (such as quotes and whitespace) are treated properly. If value is a string, assume that this is an expandable string in this interpreter.

Note that is_path provided because of the special case where a path-like envvar is set. In this case, path normalization, if it needs to occur, has to be part of the string escaping process.

Note

This default implementation returns the string with no escaping applied.

Parameters:

• value (str or EscapedString) – String to escape.

• is_path (bool) – True if the value is path-like.

Returns:

The escaped string.

Return type:

str

expand_env_vars = False

info(value: str)

normalize_path(path)

Normalize a path.

Change path to a valid filepath representation for this interpreter.

IMPORTANT: Because var references like ${THIS} might be passed to funcs like appendvar, path might be in this form. You need to take that into account (ie, ensure normalization doesn’t break such a var reference).

Parameters:

path (str) – A filepath which may be in posix format, or windows format, or some combination of the two. For eg, a string like {root}/bin on windows will evaluate to C:.../bin - in this case, the cmd shell would want to normalize this and convert to all forward slashes.

Returns:

The normalized path.

Return type:

str

normalize_paths(value)

Normalize value if it’s a path(s).

Note that value may be more than one pathsep-delimited paths.

pathsep = ':'

prependenv(key, value: str | EscapedString)

This is optional, but if it is not implemented, you must implement setenv.

resetenv(key, value, friends=None)

setenv(key: str, value: str | EscapedString)

shebang()

source(value)

unsetenv(key: str)

class rez.shells.UnixShell

Bases: Shell

A base class for common *nix shells, such as bash and tcsh.

rcfile_arg: str = None

norc_arg: str = None

histfile: str = None

histvar: str = None

command_arg = '-c'

stdin_arg = '-s'

last_command_status = '$?'

syspaths: list[str] = None

classmethod supports_norc() → bool

classmethod supports_command() → bool

classmethod supports_stdin() → bool

classmethod get_startup_sequence(rcfile: str | None, norc: bool, stdin: bool, command: bool)

Return a dict containing:

• ‘stdin’: resulting stdin setting.

• ‘command’: resulting command setting.

• ‘do_rcfile’: True if a file should be sourced directly.

• ‘envvar’: Env-var that points at a file to source at startup. Can be None.

• ‘files’: Existing files that will be sourced (non-user-expanded), in source

  order. This may also incorporate rcfile, and file pointed at via envvar. Can be empty.

• ‘bind_files’: Files to inject Rez binding into, even if that file doesn’t

  already exist.

• ‘source_bind_files’: Whether to source bind files, if they exist.

spawn_shell(context_file: str, tmpdir: str, rcfile: str | None = None, norc: bool = False, stdin: bool = False, command=None, env=None, quiet: bool = False, pre_command: str | list[str] | None = None, add_rez: bool = True, package_commands_sourced_first=None, **Popen_args)

Spawn a possibly interactive subshell.

Parameters:

• context_file – File that must be sourced in the new shell, this configures the Rez environment.

• tmpdir – Tempfiles, if needed, should be created within this path.

• rcfile – Custom startup script.

• norc – Don’t run startup scripts. Overrides rcfile.

• stdin – If True, read commands from stdin in a non-interactive shell. If a different non-False value, such as subprocess.PIPE, the same occurs, but stdin is also passed to the resulting subprocess.Popen object.

• command – If not None, execute this command in a non-interactive shell. If an empty string, don’t run a command, but don’t open an interactive shell either.

• env – Environ dict to execute the shell within; uses the current environment if None.

• quiet – If True, don’t show the configuration summary, and suppress any stdout from startup scripts.

• pre_command – Command to inject before the shell command itself. This is for internal use.

• add_rez – If True, assume this shell is being used with rez, and do things such as set the prompt etc.

• package_commands_sourced_first – If True, source the context file before sourcing startup scripts (such as .bashrc). If False, source the context file AFTER. If None, use the configured setting.

• popen_args – args to pass to the shell process object constructor.

Returns:

A subprocess.Popen object representing the shell process.

Return type:

subprocess.Popen

resetenv(key, value, friends=None) → None

info(value: str) → None

error(value: str) → None

command(value) → None

comment(value) → None

shebang() → None

classmethod get_all_key_tokens(key)

Encodes the environment variable into the shell specific forms. Shells might implement multiple forms, but the most common/safest should be always returned at index 0.

Parameters:

key – Variable name to encode

Returns:

list of str with encoded token forms

classmethod line_terminator() → str

Returns:

default line terminator

Return type:

str

ENV_VAR_REGEX = re.compile('\\${([^\\{\\}]+?)}|\\$([a-zA-Z_]+[a-zA-Z0-9_]*?)')

__init__() → None

alias(key, value)

appendenv(key, value: str | EscapedString)

This is optional, but if it is not implemented, you must implement setenv.

classmethod convert_tokens(value) → str

Converts any token like ${VAR} and $VAR to shell specific form. Uses the ENV_VAR_REGEX to correctly parse tokens.

Parameters:

value – str to convert

Returns:

str with shell specific variables

escape_string(value: str | EscapedString, is_path: bool = False) → str

Escape a string.

Escape the given string so that special characters (such as quotes and whitespace) are treated properly. If value is a string, assume that this is an expandable string in this interpreter.

Note that is_path provided because of the special case where a path-like envvar is set. In this case, path normalization, if it needs to occur, has to be part of the string escaping process.

Note

This default implementation returns the string with no escaping applied.

Parameters:

• value (str or EscapedString) – String to escape.

• is_path (bool) – True if the value is path-like.

Returns:

The escaped string.

Return type:

str

property executable: str

classmethod executable_filepath() → str

Get full filepath to executable, or raise if not found.

classmethod executable_name() → str

Name of executable to create shell instance.

expand_env_vars = False

classmethod file_extension() → str

Get the file extension associated with the shell.

Returns:

Shell file extension.

Return type:

str

classmethod find_executable(name: str, check_syspaths: bool = False) → str

Find an executable.

Parameters:

• name (str) – Program name.

• check_syspaths (bool) – If True, check the standard system paths as well, if program was not found on current $PATH.

Returns:

Full filepath of executable.

Return type:

str

classmethod get_key_token(key) → str

Encodes the environment variable into the shell specific form. Shells might implement multiple forms, but the most common/safest should be returned here.

Parameters:

key – Variable name to encode

Returns:

str of encoded token form

get_output(style: OutputStyle = OutputStyle.file) → str

Returns any implementation specific data.

Parameters:

style (OutputStyle) – Style affecting output format.

Returns:

Depends on implementation, but usually a code string.

classmethod get_syspaths()

classmethod is_available() → bool

Determine if the shell is available to instantiate.

Returns:

True if the shell can be created.

Return type:

bool

classmethod join(command: Iterable[str]) → str

Note: Default to unix sh/bash- friendly behaviour.

Parameters:

command – A sequence of program arguments to be joined into a single string that can be executed in the current shell.

Returns:

A string object representing the command.

classmethod name() → str

Plugin name.

new_shell() → Self

Returns A new, reset shell of the same type.

normalize_path(path)

Normalize a path.

Change path to a valid filepath representation for this interpreter.

IMPORTANT: Because var references like ${THIS} might be passed to funcs like appendvar, path might be in this form. You need to take that into account (ie, ensure normalization doesn’t break such a var reference).

Parameters:

path (str) – A filepath which may be in posix format, or windows format, or some combination of the two. For eg, a string like {root}/bin on windows will evaluate to C:.../bin - in this case, the cmd shell would want to normalize this and convert to all forward slashes.

Returns:

The normalized path.

Return type:

str

normalize_paths(value)

Normalize value if it’s a path(s).

Note that value may be more than one pathsep-delimited paths.

pathsep = ':'

prependenv(key, value: str | EscapedString)

This is optional, but if it is not implemented, you must implement setenv.

schema_dict = {'prompt': <class 'str'>}

setenv(key: str, value: str | EscapedString)

source(value)

classmethod startup_capabilities(rcfile: str | None | Literal[False] = False, norc: bool = False, stdin: bool = False, command: bool = False) → tuple[str | None | Literal[False], bool, bool, bool]

Given a set of options related to shell startup, return the actual options that will be applied.

Returns:

4-tuple representing applied value of each option.

Return type:

tuple

unsetenv(key: str)