qmi.tools.proc

# QMI Process Manager

This tool can start, stop and query background QMI processes. Processes are identified by their context name, as specified in the QMI configuration file. Processes can run either on the local computer or on a remote, network-connected computer.

When installing QMI with pip, also an executable qmi_proc[.exe] is created and can be used from command line. Run on command line qmi_proc –help to see usage options for qmi_proc.

Functions

`get_context_status`(context_name)	Check whether context is responding via TCP.
`is_local_host`(host)	Return True if the host specification refers to the local computer.
`proc_server`(cfg)	Run the process manager in server mode.
`proc_start`(cfg, context_name, local)	Start one or more processes.
`proc_status`(cfg, context_name)	Show the status of one or more processes.
`proc_stop`(cfg, context_name, local)	Stop one or more running processes.
`run`()	Main routine of QMI process manager.
`select_context_by_name`(cfg, context_name)	Return input the context name in a list if it is valid.
`select_contexts`(cfg)	Return a list of all applicable context names.
`select_local_contexts`(cfg)	Return a list of all applicable local context names.
`show_progress_msg`(msg)	Print short progress message on screen.
`shutdown_context`(context_name, progressfn)	Send a shutdown request to the specified context.
`start_local_process`(context_name)	Start the specified process on the local computer.
`start_process`(context_name)	Start the specified process on a local or remote computer.
`stop_local_process`(context_name, pid)	Stop the specified process on the local computer.
`stop_process`(context_name, pid)	Stop the specified process on a local or remote computer.

Classes

`ProcessManagementClient`(host, context_name)	Client side of a remote process management server.
`ShutdownResult`(responding, pid, success)

Exceptions

ProcessException

Raised when a process management operation fails.

class qmi.tools.proc.ShutdownResult(responding, pid, success)

count(value, /): Return number of occurrences of value.

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

pid: int: Alias for field number 1

responding: bool: Alias for field number 0

success: bool: Alias for field number 2

exception qmi.tools.proc.ProcessException

Raised when a process management operation fails.

add_note(): Exception.add_note(note) – add a note to the exception

with_traceback(): Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class qmi.tools.proc.ProcessManagementClient(host: str, context_name: str)

Client side of a remote process management server.

close() → None: Close the remote server process.

start_process() → int: Request that the remote process management server start a new process.

stop_process(pid: int) → bool: Request that the remote process management server stop a running process.

qmi.tools.proc.is_local_host(host: str) → bool: Return True if the host specification refers to the local computer.

qmi.tools.proc.start_local_process(context_name: str) → int

Start the specified process on the local computer.

Parameters:: context_name – Context to be started.
Returns:: Process ID of the newly started process.
Raises:: ProcessException – If the process can not be started.

qmi.tools.proc.stop_local_process(context_name: str, pid: int) → bool

Stop the specified process on the local computer.

Parameters:

context_name – Context to be stopped.
pid – Process ID.

Returns:

If the process was stopped; False: If the process was not running.

Return type:

True

Raises:

ProcessException – If the process can not be stopped.

qmi.tools.proc.start_process(context_name: str) → int

Start the specified process on a local or remote computer.

Parameters:: context_name – Context to be started.
Returns:: Process ID of the newly started process.
Return type:: pid
Raises:: ProcessException – If the process can not be started.

qmi.tools.proc.stop_process(context_name: str, pid: int) → bool

Stop the specified process on a local or remote computer.

Parameters:

context_name – Context to be stopped.
pid – Process ID.

Returns:

If the process was stopped; False: If the process was not running.

Return type:

True

Raises:

ProcessException – If the process can not be stopped.

qmi.tools.proc.get_context_status(context_name: str) → tuple[int, str]

Check whether context is responding via TCP.

Parameters:

context_name – Name of the context to be tested.

Returns:

A tuple containing the process ID of the Python program containing the context, or -1 if the: context is not responding via TCP. And the QMI version number of the newly created context.

Return type:

(pip, ver)

Raises:

ProcessException – If an error occurs.

qmi.tools.proc.shutdown_context(context_name: str, progressfn: Callable[[str], None]) → ShutdownResult

Send a shutdown request to the specified context.

Send a soft shutdown request and wait until the context goes away. If that does not work, send a hard shutdown request and wait until the context goes away. If that does not work, give up and report failure.

Parameters:

context_name – Context to shut down.
progressfn – Callback function to report progress message.

Returns:

Instance with values responding, pid, success.

Return type:

ShutdownResult

Raises:

ProcessException – If an error occurs.

qmi.tools.proc.select_context_by_name(cfg: CfgQmi, context_name: str) → list[str]

Return input the context name in a list if it is valid.

Parameters:

cfg – The current QMI configuration.
context_name – The name of the context to validate.

Raises:

QMI_ApplicationException – If context name is not within known contexts or name is invalid.

Returns:

The input context name in a list.

Return type:

list

qmi.tools.proc.select_contexts(cfg: CfgQmi) → list[str]

Return a list of all applicable context names.

Parameters:: cfg – The current QMI configuration.
Raises:: QMI_ApplicationException – If no contexts are enabled in the configuration, or name is invalid.
Returns:: All context names as a list.
Return type:: context_names

qmi.tools.proc.select_local_contexts(cfg: CfgQmi) → list[str]

Return a list of all applicable local context names.

Parameters:: cfg – The current QMI configuration.
Raises:: QMI_ApplicationException – If no local contexts are enabled in the configuration, or name is invalid.
Returns:: Local context names as a list.

qmi.tools.proc.show_progress_msg(msg: str) → None: Print short progress message on screen.

qmi.tools.proc.proc_server(cfg: CfgQmi) → int

Run the process manager in server mode.

Parameters:

cfg – The current QMI configuration.

Raises:

ProcessException – If process is unknown or should not run on this host.
ValueError – By invalid command.

Returns:

(0 = success).

Return type:

Exit status

qmi.tools.proc.proc_start(cfg: CfgQmi, context_name: str | None, local: bool) → int

Start one or more processes.

Parameters:

cfg – The current QMI configuration.
context_name – Process to start, or None to start all configured processes.
local – Boolean flag to indicate if we only look at local processes (True) or all processes (False).

Raises:

ProcessException – By unexpected PID number in check.

Returns:

Exit status (0 = success).

qmi.tools.proc.proc_stop(cfg: CfgQmi, context_name: str | None, local: bool) → int

Stop one or more running processes.

Parameters:

cfg – The current QMI configuration.
context_name – Process to start, or None to stop all configured processes.
local – Boolean flag to indicate if we only look at local processes (True) or all processes (False).

Raises:

ProcessException – By unexpected error in stopping the process.

Returns:

Exit status (0 = success).

qmi.tools.proc.proc_status(cfg: CfgQmi, context_name: str | None) → int

Show the status of one or more processes.

Parameters:

cfg – The current QMI configuration.
context_name – Process to get status for, or None to get all configured processes.

Raises:

ProcessException – By unexpected error when checking the status.

Returns:

Exit status (0 = success).

qmi.tools.proc.run() → int

Main routine of QMI process manager.

Returns:: 0 in case of success; exit status in case of error.