qmi

Toplevel package of the QMI framework.

qmi.context() → QMI_Context

Return the current QMI_Context instance.

This function may only be called when there is an active QMI context (i.e. after calling qmi.start()).

Raises:

QMI_NoActiveContextException – If there is no active context.

qmi.start(context_name: str, config_file: str | None = None, init_logging: bool = True, console_loglevel: str | None = None, context_cfg: dict | None = None) → None

Create and start a global QMI_Context instance.

This function should be called exactly once by the top-level code of the application.

This function performs a number of initialization steps:

  • read the QMI configuration file;

  • initialize logging;

  • create and start a global QMI context.

The context name is a short string, without spaces or strange characters. This name will be used to refer to this context from other processes, as well as for displaying and logging.

The context name should be unique within the workgroup (i.e. among all Python processes that work together via QMI.) If this context acts as a server for other contexts to connect to, its name must be unique. Otherwise, if this context only acts as a client, a duplicate context name is allowed but not recommended.

If config_file is provided, it should be a path to a valid QMI configuration file. The referenced file will be used to load the configuration from. If config_file is None and the environment variable QMI_CONFIG is set, the configuration will be loaded from the file that the environment variable points to. If QMI_CONFIG is not set, an empty configuration is used.

The configuration created can be edited by providing a dictionary as an optional input. See config_defs.CfgContext class for possible dict keys and respective values and types that are allowed. Wrong (type) of keys and/or values will raise an exception.

Parameters:

  • context_name – Name of the QMI context.

  • config_file – Optional path to the QMI configuration file.

  • init_logging – Optional flag; set False to skip logging initialization.

  • console_loglevel – Optionally override console_loglevel from config file.

  • context_cfg – Optionally insert or override context(s) in config.contexts

qmi.stop() → None

Stop and destroy the QMI_Context instance.

This function should be called exactly once when the application exits.

Raises:

QMI_NoActiveContextException – If there is no active context.

qmi.info() → str

Return human-readable information about the context.

qmi.make_rpc_object(rpc_object_name: str, rpc_object_class: Type[QMI_RpcObject], *args: Any, **kwargs: Any) → Any

Create an instance of a QMI_RpcObject subclass and make it accessible via RPC.

The actual object instance will be created in a separate background thread. To access the object, you can call its methods via RPC. Note that using the returned proxy in a thread might require casting it first: proxy = cast(proxy, rpc_object_class)(qmi.context(), rpc_object_name).

Parameters:

  • object_name – Unique name for the new object instance. This name will also be used to access the object via RPC.

  • object_class – Class that implements this object (must be a subclass of QMI_RpcObject).

  • args – Optional arguments for the object class constructor.

Returns:

An RPC proxy that provides access to the new object instance.

qmi.make_task(task_name: str, task_class: ~typing.Type[~qmi.core.task.QMI_Task], *args: ~typing.Any, task_runner: ~typing.Type[~qmi.core.task.QMI_TaskRunner] = <class 'qmi.core.task.QMI_TaskRunner'>, **kwargs: ~typing.Any) → Any

Create an instance of a QMI_Task subclass and make it accessible via RPC.

The actual task instance will be created in a separate thread. A QMI_TaskRunner will be created to manage the task thread. The task can be accessed by calling the methods of the task runner via RPC.

Note that the task is not yet started. To start the task, perform an explicit call to the start() method of the returned task.

Parameters:

  • task_name – Unique name for the new task instance. This name will also be used to access the task runner via RPC.

  • task_class – Class that implements this task (must be a subclass of QMI_Task).

  • task_runner – Class that implements the managing of the task (must be a subclass of QMI_Taskrunner)

  • args – Optional arguments for the task class constructor.

Returns:

An RPC proxy that provides access to the new task.

qmi.make_instrument(instrument_name: str, instrument_class: Type[QMI_Instrument], *args: Any, **kwargs: Any) → Any

Create an instance of a QMI_Instrument subclass and make it accessible via RPC.

The actual instrument instance will be created in a separate background thread. To access the instrument, you can call its methods via RPC.

Parameters:

  • instrument_name – Unique name for the new instrument instance. This name will also be used to access the instrument via RPC.

  • instrument_class – Class that implements this instrument (must be a subclass of QMI_Instrument).

  • args – Optional arguments for the instrument class constructor.

Returns:

An RPC proxy that provides access to the new instrument instance.

qmi.list_rpc_objects(rpc_object_baseclass=None) → List

Show a list of RPC objects in the local context and peer contexts.

qmi.show_rpc_objects(rpc_object_baseclass=None) → None

Show a list of RPC objects in the local context and peer contexts.

qmi.show_instruments() → None

Show a list of instruments in the local context and peer contexts.

qmi.show_tasks() → None

Show a list of tasks in the local context and peer contexts.

qmi.show_contexts() → None

Show a list of currently connected contexts (including the local context).

qmi.show_network_contexts() → None

Show a lists of context on the network (connected and not connected).

qmi.get_rpc_object(rpc_object_name: str, auto_connect: bool = False, host_port: str | None = None) → Any

Return a proxy for the specified object.

The object may exist either in the local context, or in a peer context.

Parameters:

  • object_name – Object name, formatted as "<context_name>.<object_name>".

  • auto_connect – if True, connect automatically to the object peer.

  • host_port – Optional host:port string pattern to guide the auto_connect.

Returns:

A proxy for the specified object.

qmi.get_instrument(instrument_name: str, auto_connect: bool = False, host_port: str | None = None) → Any

Return a proxy for the specified instrument.

The instrument may exist either in the local context, or in a peer context.

Parameters:

  • instrument_name – Instrument name, formatted as "<context_name>.<instrument_name>".

  • auto_connect – if True, connect automatically to the instrument peer.

  • host_port – Optional host:port string pattern to guide the auto_connect.

Returns:

A proxy for the specified instrument.

qmi.get_task(task_name: str, auto_connect: bool = False, host_port: str | None = None) → Any

Return a proxy for the specified task.

The task may exist either in the local context, or in a peer context.

Parameters:

  • task_name – Task name, formatted as "<context_name>.<task_name>".

  • auto_connect – if True, connect automatically to the task peer.

  • host_port – Optional host:port string pattern to guide the auto_connect.

Returns:

A proxy for the specified task.

qmi.get_configured_contexts() → Dict[str, CfgContext]

Return a dictionary of active QMI contexts.

Returns:

An OrderedDict object of all active QMI contexts.