qmi.core.context_singleton

Convenience functions to handle the singleton-instance of QMI_Context.

Most QMI applications will create a single instance of QMI_Context and use that context for all interactions with QMI. This module provides functions to make this way of working more convenient.

The public functions defined in this module, are also imported into the top-level qmi package. Applications can therefore call these functions directly, for example:

import qmi
qmi.start("my_context")
proxy = qmi.make_instrument("my_instrument", InstrumentClass, class_args)
qmi.stop()

Functions

`context`()	Return the current QMI_Context instance.
`create_config_from_file`(config_file)	Create configuration from a file.
`get_configured_contexts`()	Return a dictionary of active QMI contexts.
`get_instrument`(instrument_name[, ...])	Return a proxy for the specified instrument.
`get_rpc_object`(rpc_object_name[, ...])	Return a proxy for the specified object.
`get_task`(task_name[, auto_connect, host_port])	Return a proxy for the specified task.
`info`()	Return human-readable information about the context.
`list_rpc_objects`([rpc_object_baseclass])	Show a list of RPC objects in the local context and peer contexts.
`make_instrument`(instrument_name, ...)	Create an instance of a QMI_Instrument subclass and make it accessible via RPC.
`make_rpc_object`(rpc_object_name, ...)	Create an instance of a QMI_RpcObject subclass and make it accessible via RPC.
`make_task`(task_name, task_class, *args, ...)	Create an instance of a QMI_Task subclass and make it accessible via RPC.
`show_contexts`()	Show a list of currently connected contexts (including the local context).
`show_instruments`()	Show a list of instruments in the local context and peer contexts.
`show_network_contexts`()	Show a lists of context on the network (connected and not connected).
`show_rpc_objects`([rpc_object_baseclass])	Show a list of RPC objects in the local context and peer contexts.
`show_tasks`()	Show a list of tasks in the local context and peer contexts.
`start`(context_name[, config_file, ...])	Create and start a global QMI_Context instance.
`stop`()	Stop and destroy the QMI_Context instance.

qmi.core.context_singleton.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.core.context_singleton.start(context_name: str, config_file: str | None = '', init_logging: bool = True, console_loglevel: str | None = None, context_cfg: dict | None = None) → QMI_Context

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 an empty string and the environment variable QMI_CONFIG is set, the configuration will be loaded from the file that the environment variable points to. If config_file is None or if it is an empty string and 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.

Returns:

The global QMI_Context object.

qmi.core.context_singleton.create_config_from_file(config_file: str | None) → CfgQmi

Create configuration from a file.

Parameters:: config_file – Path of configuration file or None.
Returns:: Top-level QMI configuration structure.

qmi.core.context_singleton.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 QMI context present.

qmi.core.context_singleton.info() → str: Return human-readable information about the context.

qmi.core.context_singleton.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:

rpc_object_name – Unique name for the new object instance. This name will also be used to access the object via RPC.
rpc_object_class – Class that implements this object (must be a subclass of QMI_RpcObject).
args – Optional arguments for the object class constructor.
kwargs – Optional keyword arguments for the object class constructor.

Returns:

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

Raises:

QMI_NoActiveContextException – If there is no active QMI context present.

qmi.core.context_singleton.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 – A 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.
kwargs – Optional keyword arguments for the instrument class constructor.

Returns:

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

Raises:

QMI_NoActiveContextException – If there is no active QMI context present.

qmi.core.context_singleton.make_task(task_name: str, task_class: type[~qmi.core.task.QMI_Task], *args: ~typing.Any, task_runner: 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).
args – Optional arguments for the task class constructor.
task_runner – Class that implements the managing of the task (must be a subclass of QMI_Taskrunner)
kwargs – Optional keyword arguments for the task class constructor.

Returns:

An RPC proxy that provides access to the new task.

Raises:

QMI_NoActiveContextException – If there is no active QMI context present.

qmi.core.context_singleton.list_rpc_objects(rpc_object_baseclass=None) → list: Show a list of RPC objects in the local context and peer contexts.

qmi.core.context_singleton.show_rpc_objects(rpc_object_baseclass=None) → None: Show a list of RPC objects in the local context and peer contexts.

qmi.core.context_singleton.show_instruments() → None: Show a list of instruments in the local context and peer contexts.

qmi.core.context_singleton.show_tasks() → None: Show a list of tasks in the local context and peer contexts.

qmi.core.context_singleton.show_contexts() → None: Show a list of currently connected contexts (including the local context).

qmi.core.context_singleton.show_network_contexts() → None: Show a lists of context on the network (connected and not connected).

qmi.core.context_singleton.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:

rpc_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.

Raises:

QMI_NoActiveContextException – If there is no active QMI context present.

qmi.core.context_singleton.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.

Raises:

QMI_NoActiveContextException – If there is no active QMI context present.

qmi.core.context_singleton.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.

Raises:

QMI_NoActiveContextException – If there is no active QMI context present.

qmi.core.context_singleton.get_configured_contexts() → dict[str, CfgContext]

Return a dictionary of active QMI contexts.

Returns:: An OrderedDict object of all active QMI contexts.
Raises:: QMI_NoActiveContextException – If there is no active QMI context present.