Module commandutils

check_file_presence(input_file, descriptor='input_file', exception_raised=<class 'easyterm.commandlineopt.NoTracebackError'>)

Check if file exists. If it doesn’t, raises a IOError exception

Parameters:

input_file (str) – string of file to check, any relative or absolute path
descriptor (str) – used for meaningful error message if file is absent
exception_raised (class) – Exception class to be raised

Returns:

None

Return type:

None

checksum_of_file(filename)

Gets checksum of content of a file, using program ‘sum’

Parameters:: filename (str) – file to be read
Returns:: (sum1, sum2) – checksum of file
Return type:: (int, int)

mask_chars(astring)

Replace potentially problematic characters in a string so that it can be used as filename.

All characters which are not alphanumeric (e.g. :/?@#$_) are replaced to ‘{chN}’, where N is their ASCII code. Also, spaces are converted to underscores. Note that underscores originally present in input string are converted to {ch95}.

You may do the reverse (get back the original unmasked string) using function unmask_chars.

Parameters:: astring (str) – input string to be masked
Returns:: mstring – string with potentially problematic characters masked
Return type:: str

Examples

>>> mask_chars('some species name')
'some_species_name'

>>> mask_chars('string containing /')
'string_containing_{ch47}'

>>> mask_chars('lots of #strange $characters here to @mask !')
'lots_of_{ch35}strange_{ch36}characters_here_to_{ch64}mask_{ch33}'

See also

unmask_chars

md5sum_of_file(filename, chunksize=4096)

Gets md5sum of content of a file

Parameters:: filename (str) – file to be read
Returns:: md5sum – md5sum of file
Return type:: str

random_folder(parent_folder='./', mkdir=True)

Generate a random folder name, create it inside parent_folder, and return the path to it

Parameters:

parent_folder (str) – folder inside which the random_folder is desired
mkdir (bool) – whether the random folder should be created (by default: True)

Returns:

rnd_folder – path to newly created random folder (whose name will look like 57eb3f2416bc4c5d9d34a17751c97362)

Return type:

str

run_cmd(cmd, err_crash=True, **keyargs)

Utility function to run bash commands.

This function wraps subprocess.run for its most common usage (according to the easyterm developer, anyhow). You can provide any of subprocess.run options to modify its behaviour.

The input is the string of the command you would run in a terminal. It returns a class subprocess.CompletedProcess instance with attributes returncode, stdout (coded as text, joining stdout and stderr).

Parameters:

cmd (str | list) – command, just as you would run in a terminal, or list of command and arguments
err_crash (bool, optional) – if err_crash==True (default) and the process fails (exitcode!=0), an exception is raised including an informative message.
**kwargs – keyword arguments that will be passed to subprocess.run

Returns:

proc – completed process, with attributes returncode, stdout, and others (see subprocess.run)

Return type:

subprocess.CompletedProcess

Note

By default, stdout and stderr are joined in the stdout property of the returned object. To separate them instead, use stderr=subprocess.PIPE

unmask_chars(mstring)

Reverses function mask_chars.

Substrings matching ‘{chN}’, where N is an integer, are converted to their original value before masking (the ascii character identified by that integer). Also, underscores are converted to spaces.

Parameters:: mstring (str) – masked input string to be unmasked
Returns:: ustring – unmasked string, i.e. the original input fed to mask_chars in the first place.
Return type:: str

Examples

>>> unmask_chars('some_simple_string')
'some simple string'

>>> unmask_chars('lots_of_{ch35}strange_{ch36}characters_here_to_{ch64}mask_{ch33}')
'lots of #strange $characters here to @mask !'