genvid.toolbox.BaseTool¶
-
class
genvid.toolbox.
BaseTool
(logname=None, command_option_name='command', **kwargs)¶ Bases:
object
Base class for all tools.
This class sets up and provides basic functionalities to all other tools. In particular, it handles the
main()
andget_parser()
methods. Seeadd_commands()
,add_command()
andrun_command()
for more details.Please, note that most attributes of this class aren’t initialized properly before instantiation.
-
BINDIR
= None¶ A mirror of
BINDIR
containing the folder where the binaries of the project are stored.
-
COMMAND_OPTION_NAME
= None¶ The name used for the command arguments on the command line.
See
add_command()
for more details.
-
CURDIR
= None¶ A mirror of
CURDIR
containing the current script directory path if set correctly, or the current working directory by default.Warning: This variable is not very reliable. Try to avoid using it.
-
DESCRIPTION
= None¶ A description of the tool, used in the help parser. Must be redefined in children.
-
ENVIRONMENT_VARIABLES
= {'MSBUILD', 'UE4ROOT', 'GENVID_TOOLBOX_LOGLEVEL', 'VAULT_TOKEN', 'UE4ENGINEDIR_4_18', 'GENVID_BASTION_URL', 'UE4ENGINEDIR_4_17', 'GENVID_VAULT_POLICIES_FOLDER', 'CURDIR', 'GENVID_VAULT_TOKEN_ROLES_FOLDER', 'GENVID_TOOLBOX_VERSION', 'GENVID_DEFAULT_IP', 'UE4ENGINEDIR_4_16', 'UE4ENGINEDIR_4_19', 'BINDIR', 'VAULT_KEYS', 'VAULT_ADDR', 'ROOTDIR', 'UE4ENGINEDIR_4_15', 'UE4ENGINEDIR_4_20', 'DOCKER_MACHINE_NAME', 'UTROOT', 'PYTHON_EXECUTABLE', 'HOME', 'UE4ENGINEDIR'}¶ The set of environment variables used by all tools.
The list is updated each time
setdefault()
is called. It is used byenv()
and func:print_env.
-
GENVID_BASTION_URL
= None¶ A mirror of
GENVID_BASTION_URL
representing the bastion-api URL.
-
GENVID_TOOLBOX_LOGLEVEL
= None¶ A mirror of
GENVID_TOOLBOX_LOGLEVEL
that set thelogger
level in toolbox.
-
GENVID_TOOLBOX_VERSION
= None¶ A mirror of
GENVID_TOOLBOX_VERSION
containing the currently installed toolbox version.Warning: This variable shouldn’t be overriden.
-
HOME
= None¶ A mirror of
HOME
containing the user home directory name.Taken from environment variable or
os.path.expanduser()
.
-
KILL_SIGNAL
= 1¶ Default kill signal.
Default to
signal.SIGKILL
on UNIX, andsignal.CTRL_BREAK_EVENT
on Windows.New in version 1.15.0.
-
MODE_0600
= 384¶ User RW file permissions
-
MODE_0644
= 420¶ User RW, Group and Other Read file permissions
-
MODE_0700
= 448¶ User RWX file permissions
-
MODE_0755
= 493¶ User RWX and Group and Other RX file permissions
-
NAME
= None¶ The name of the logger for this tool. Must be redefined in children.
-
PLATFORM
= None¶ Name of the current platform.
Could be either linux or windows for now.
-
PYTHON_EXECUTABLE
= None¶ A mirror of
PYTHON_EXECUTABLE
containing the current python executable by default.Taken from the environment or
sys.executable
if not set.
-
RE_VERSION_MATCH
= re.compile('(?P<version>(\\d+).(\\d+).(\\d+))(?P<dirty>(\\.post(\\d+)(\\+dirty)?)?)$')¶
-
add_base_commands
()¶
-
add_command
(name: str, description: str, **kwargs)¶ Add a new command to the tool.
The command will be added to the list of
commands
.Parameters: - name – The name of the command.
- description – Help for the command.
- kwargs – Other keyword arguments to pass to the parser for this
tool
subparsers
.
Returns: A command parser.
Raises: AssertionError
if name already exists as a command.
-
add_commands
()¶ Add commands for the tool.
This method must be overridden. It allows the child class to add new commands using
add_commands()
. The list of all existing commands and their parsers are available fromcommands
.
-
commands
= None¶ A dictionary of the parser for each command.
See
add_command()
for more details.
-
copy_files
(srcdir: pathlib.Path, dstdir: pathlib.Path, files: typing.List[typing.Union[str, pathlib.Path]], dryrun=False)¶ Copy all files in
files``from ``srcdir
todstdir
.Parameters: - srcdir – the base folder of the original files.
- dstdir – the destination folder of the files.
- files – a list of files to copy.
- dryrun – If true, will only log the result, without doing the copy.
-
static
delenv
(name: str)¶
-
static
env
()¶ Return the list of used environment variables and their values.
The list of variables to return is taken from
ENVIRONMENT_VARIABLES
.
-
get_files
(srcdir: pathlib.Path)¶ Get all files (but not folders) under
srcdir
.Equivalent to srcdir.rglob(“*”) but with folder filtered out.
Parameters: srcdir – The folder to check for new files. Returns: an iterator of Path
objects.
-
get_parser
(subparsers=None, name=None, description=None, fromfile_prefix_chars='@', **kwargs)¶ Returns the parser for the tool.
Parameters: - subparsers – Custom subparsers to use.
- name – The name of the tool (defaults to
NAME
). - description – The description of the tool (defaults to
DESCRIPTION
). - fromfile_prefix_chars – The set of characters that prefix files from which additional arguments should be read.
- kwargs – Other keyword arguments to pass to the parser
for this
argparse.ArgumentParser
factory.
Returns: The parser for this tool.
Changed in version 1.13.0: New default for fromfile_prefix_chars to ‘@’. Pass None to switch to old behaviour (which is None).
-
install_file
(src: typing.Union[str, pathlib.Path], dst: typing.Union[str, pathlib.Path], mode=420, uid=-1, gid=-1, backup=False)¶ Copy a file src to dst, and change its permissions.
Parameters: - src – The file to be copied.
- dst – The destination of the copy.
- mode – The permission of the destination.
- uid – The user ID of the destination. If -1, uses the user ID of the process.
- gid – The GID of the destination. If -1, uses the uid.
- backup – Backup the file, adding a
~
at the end of the filename.
Changed in version 1.16.0: Make it a non-staticmethod and add the backup argument.
-
install_json
(dest: typing.Union[str, pathlib.Path], config, **kwargs)¶ Dump config as a JSON file and copy it to destination.
Parameters: - dest – The destination of the content.
- data – The data to write to write into the file as JSON.
Changed in version 1.16.0: Now a non-staticmethod
-
install_tmp_file
(dest: typing.Union[str, pathlib.Path], data: bytes, **kwargs)¶ Write data to a temporary file and copy it to dst.
The installation is done using
install_file()
.Parameters: - dest – The destination of the content.
- data – The data to write to write into the file.
Changed in version 1.16.0: Now a non-staticmethod
-
kill_process
(proc: typing.Union[int, psutil.Process])¶ Kill a process.
Force kill a process by sending a SIGKILL or call TerminateProcess.
Parameters: proc – The process. Could be the process PID or an instance of psutil.Process
.New in version 1.15.0.
-
kill_process_tree
(proc: typing.Union[int, psutil.Process], timeout: float = 5.0) → typing.List[psutil.Process]¶ Kill a process tree by sending SIGTERM/CTRL_BREAKy_EVENT first, and then by pushing a SIGKILL/Terminate on all children.
Parameters: - proc – The process. Could be the process PID or an
instance of
psutil.Process
. - timeout – Timeout to wait for the process to finish (in seconds).
Returns: List of processes still alive.
New in version 1.15.0.
- proc – The process. Could be the process PID or an
instance of
-
logger
= None¶ The logger for the tool.
-
main
(options=None)¶ Run the tool.
If options is None, it will obtained from the command line arguments. Otherwise, it must be either a namespace object or a dictionary.
-
parser
= None¶ The current parser for this tool.
See
add_commands()
for more details.
-
static
print_env
()¶ Print the list of environment variables used and their values.
The list of variables to return is taken from
ENVIRONMENT_VARIABLES
.
-
pyrun
(*args, **kwargs)¶ Run a python script using the current python version.
This is roughly equivalent to:
run("python", *args, **kwargs)
-
static
remove_readonly
(func, path, excinfo)¶ Helper for
rmtree()
to help remove read-only files on Windows.
-
static
rmtree
(directory: pathlib.Path, ignore_errors: bool = False, onerror=None)¶ Equivalent to
shutil.rmtree()
but aware of symlinks on Windows.
-
run
(*args, check=True, cwd=None, **kwargs)¶ Wrapper around
subprocess.run()
that passes all arguments in args and sets the default value of check to True.For convenience, all arguments are converted to string (using
str
).Changed in version 1.15.0: It’s now a method instead of staticmethod.
-
run_base_command
(command, options)¶
-
run_command
(command, options)¶ Run command with those options.
You must override this method.
Parameters: - command – The name of the command to run.
- options – A
argparse.Namespace
object with the options pass in arguments.
-
run_daemon
(*args: str, **kwargs)¶ Run the process in background.
Parameters: - args – The command to run.
- stdout – The output file for stdout.
- stderr – The output file for stderr.
- cwd – The current working directory.
- env – The environment to use.
- pidfile – The pidfile to save the PID of the process.
-
run_elevated
(*args, **kwargs)¶ Run the command using elevated privileges on Windows.
-
run_elevated_win32
(*args, **kwargs)¶ Run the command using elevated privileges on Windows.
-
run_powershell
(*cmds: str, interactive: bool = False, noprofile: bool = False, **kwargs)¶ Run cmds as a powershell script.
Parameters: - cmds – A list of powershell commands to execute.
- interactive – If the command is interactive.
- noprofile – Don’t load a profile.
- kwargs – Other keyword arguments to pass to the parser for this
run()
.
-
safe_print
(text: str, fileobj=<colorama.ansitowin32.StreamWrapper object>, errors='backslashreplace')¶ Print a value safely to
fileobj
.fileobj
must have anencoding
member as well as abuffer
member with awrite
method that accept bytes.Parameters: - text – The text to print.
- fileobj – The fileobj to print to.
- errors – The error handling strategy. See
str.encode()
for the possible values.
-
static
safe_unlink
(filename: typing.Union[str, pathlib.Path])¶ Unlink a file only if it exists.
Changed in version 1.12.0: Now allow a
pathlib.Path
too as argument.
-
send_signal
(proc: typing.Union[int, psutil.Process], sig: int = None)¶ Send a signal to a process.
Parameters: - proc – The process. Could be the process PID or an
instance of
psutil.Process
. - sig – The signal to send. Default to
KILL_SIGNAL
.
New in version 1.15.0.
- proc – The process. Could be the process PID or an
instance of
-
static
setbasescript
(path: str)¶ Set
CURDIR
to path, and setROOTDIR
to its parent, if not already set.If you want to set the
ROOTDIR
to a different path, you must call setrootdir first.
-
static
setdefault
(name: str, value: str)¶ Set an environment variable named name to value if not already set and returns its value.
-
shrun
(cmdline: str, shell=True, check=True, **kwargs)¶ Wrapper around
subprocess.run()
that pass the cmdline directly, set the default value of check and shell to True.Changed in version 1.15.0: It’s now a method instead of staticmethod.
-
subparsers
= None¶ The subparsers object from the argparse module used for all commands.
See
add_commands()
for more details.
-
which
(exe, path=None)¶ Return the full path of the executable that would be run with exe.
If path is include, it will be used for the check. Otherwise, the
BINDIR
is checked first.Raises: ExecutableNotInPathError
if the file doesn’t exist.
-
-
class
basetool.
BaseTool
¶ Implementation of
genvid.toolbox.BaseTool