pcvs.helpers.utils module

class pcvs.helpers.utils.Program(cmd=None)

Bases: object

Simple class to encapsulate process management.

This is better and should be preferred as importing subprocess everywhere.

property exception

Getter, raised exception (for any reason)

Returns

an Exception-derived object

Return type

Exception

property out

Getter to actual execution output.

Returns

stderr/stdout combined

Return type

str

property rc

Getter, effective return code.

Returns

return code

Return type

integer

run(input='', shell=False, timeout=0)

Run the given program and capture I/Os

Parameters

• input (str) – raw data to be used as stdin

• shell (boolean) – is the provided command to be run within a shell

• timeout (positive integer) – allowed time before automatically killing the process

Returns

zero if the process started successfully, non-zero otherwise.

Return type

integer

pcvs.helpers.utils.check_valid_program(p, succ=None, fail=None, raise_if_fail=True)

Check if p is a valid program, using the which function.

Parameters

• p (str) – program to check

• succ (optional) – function to call in case of success, defaults to None

• fail (optional) – function to call in case of failure, defaults to None

• raise_if_fail (bool, optional) – Raise an exception in case of failure, defaults to True

Raises

RunException.ProgramError – p is not a valid program

Returns

True if p is a program, False otherwise

Return type

bool

pcvs.helpers.utils.check_valid_scope(s)

Check if argument is a valid scope (local, user, global).

Parameters

s (str) – scope to check

Raises

CommonException.BadTokenError – the argument is not a valid scope

pcvs.helpers.utils.copy_file(src, dest)

Copy a source file into a destination directory.

Parameters

• src (str) – source file to copy.

• dest (str) – destination directory, may not exist yet.

pcvs.helpers.utils.create_home_dir()

Create a home directory

pcvs.helpers.utils.create_or_clean_path(prefix, dir=False)

Create a path or cleans it if it already exists.

Parameters

• prefix (os.path, str) – prefix of the path to create

• dir (bool, optional) – True if the path is a directory, defaults to False

pcvs.helpers.utils.cwd(path)

Change the working directory.

Parameters

path (os.path, str) – new working directory

pcvs.helpers.utils.extract_infos_from_token(s, pair='right', single='right', maxsplit=3)

Extract fields from tokens (a, b, c) from user’s string.

Parameters

• s (str) – the input string

• pair (str, optional) – padding side when only 2 tokens found, defaults to “right”

• single (str, optional) – padding side when only 1 token found, defaults to “right”

• maxsplit (int, optional) – maximum split number for s, defaults to 3

Returns

3-string-tuple: mapping (scope, kind, name), any of them may be null

Return type

tuple

pcvs.helpers.utils.find_buildir_from_prefix(path)

Find the build directory from the path prefix.

Parameters

path (os.path, str) – path to search the build directory from

Raises

CommonException.NotFoundError – the build directory is not found

Returns

the path of the build directory

Return type

os.path

pcvs.helpers.utils.get_lock_owner(f)

The lock file will contain the process ID owning the lock. This function returns it.

Parameters

f (str) – the original file to mutex

Returns

the process ID

Return type

int

pcvs.helpers.utils.get_lockfile_name(f)

From a file to mutex, return the file lock name associated with it.

For instance for /a/b.yml, the lock file name will be /a/.b.yml.lck

Parameters

f (str) – the file to mutex

pcvs.helpers.utils.is_locked(f)

Is the given file locked somewhere else ?

Parameters

f (str) – the file to test

Returns

a boolean indicating wether the lock is hold or not.

Return type

bool

pcvs.helpers.utils.lock_file(f, reentrant=False, timeout=None, force=True)

Try to lock a directory.

Parameters

• f (os.path) – name of lock

• reentrant (bool, optional) – True if this process may have locked this file before, defaults to False

• timeout (int (seconds), optional) – time before timeout, defaults to None

Raises

LockException.TimeoutError – timeout is reached before the directory is locked

Returns

True if the file is reached, False otherwise

Return type

bool

pcvs.helpers.utils.program_timeout(sig, frame)

Timeout handler, called when a SIGALRM is received.

Parameters

• sig (int) – signal number

• frame – the callee (unused)

Raises

CommonException.TimeoutError – timeout is reached

pcvs.helpers.utils.set_local_path(path)

Set the prefix for the local storage.

Parameters

path (os.path) – path of the local storage

pcvs.helpers.utils.start_autokill(timeout=None)

Initialize a new time to automatically stop the current process once time is expired.

Parameters

timeout (positive integer) – value in seconds before the autokill will be raised

pcvs.helpers.utils.storage_order()

Return scopes in order of searching.

Returns

a list of scopes

Return type

list

pcvs.helpers.utils.trylock_file(f, reentrant=False)

Try to lock a file (used in lock_file).

Parameters

• f (os.path) – name of lock

• reentrant (bool, optional) – True if this process may have locked this file before, defaults to False

Returns

True if the file is reached, False otherwise

Return type

bool

pcvs.helpers.utils.unlock_file(f)

Remove lock from a directory.

Parameters

f (os.path) – file locking the directory