rez.shells#

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

rez.shells.get_shell_types()#

Returns the available shell types: bash, tcsh etc.

Returns:: Shells.
Return type:: list[str]

rez.shells.get_shell_class(shell=None)#

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=None, **kwargs)#

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()#: Plugin name.

classmethod executable_name()#: Name of executable to create shell instance.

classmethod executable_filepath()#: Get full filepath to executable, or raise if not found.

property executable#

classmethod is_available()#

Determine if the shell is available to instantiate.

Returns:: True if the shell can be created.
Return type:: bool

classmethod file_extension()#

Get the file extension associated with the shell.

Returns:: Shell file extension.
Return type:: str

classmethod startup_capabilities(rcfile=False, norc=False, stdin=False, command=False)#

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__()#

get_output(style=OutputStyle.file)#

Returns any implementation specific data.

Parameters:: style (OutputStyle) – Style affecting output format.
Returns:: Depends on implementation, but usually a code string.

new_shell()#: Returns A new, reset shell of the same type.

classmethod find_executable(name, check_syspaths=False)#

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, tmpdir, rcfile=None, norc=False, stdin=False, command=None, env=None, quiet=False, pre_command=None, add_rez=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

classmethod convert_tokens(value)#

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

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

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

Returns:: default line terminator
Return type:: str

classmethod join(command)#

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)#: This is optional, but if it is not implemented, you must implement setenv.

command(value)#

comment(value)#

error(value)#

escape_string(value, is_path=False)#

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

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)#: This is optional, but if it is not implemented, you must implement setenv.

resetenv(key, value, friends=None)#

setenv(key, value)#

shebang()#

source(value)#

unsetenv(key)#

class rez.shells.UnixShell#

Bases: Shell

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

rcfile_arg = None#

norc_arg = None#

histfile = None#

histvar = None#

command_arg = '-c'#

stdin_arg = '-s'#

last_command_status = '$?'#

syspaths = None#

classmethod supports_norc()#

classmethod supports_command()#

classmethod supports_stdin()#

classmethod get_startup_sequence(rcfile, norc, stdin, command)#

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

info(value)#

error(value)#

command(value)#

comment(value)#

shebang()#

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

Returns:: default line terminator
Return type:: str

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

__init__()#

alias(key, value)#

appendenv(key, value)#: This is optional, but if it is not implemented, you must implement setenv.

classmethod convert_tokens(value)#

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, is_path=False)#

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#

classmethod executable_filepath()#: Get full filepath to executable, or raise if not found.

classmethod executable_name()#: Name of executable to create shell instance.

expand_env_vars = False#

classmethod file_extension()#

Get the file extension associated with the shell.

Returns:: Shell file extension.
Return type:: str

classmethod find_executable(name, check_syspaths=False)#

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

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.file)#

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

Determine if the shell is available to instantiate.

Returns:: True if the shell can be created.
Return type:: bool

classmethod join(command)#

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()#: Plugin name.

new_shell()#: 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.

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)#: This is optional, but if it is not implemented, you must implement setenv.

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

setenv(key, value)#

source(value)#

classmethod startup_capabilities(rcfile=False, norc=False, stdin=False, command=False)#

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