Remote Objects

Remote method invocation from Python scripts to MHI application entities.

Remotable

class mhi.common.remote.Remotable(*, _ctx: Context | None = None, _ident: Dict[str, Any] | None = None)

Base class for Remote Method Invocation (RMI) enabled objects

property main: Application

A reference to the Application object that returned this Remotable object.

Application

class mhi.common.remote.Application(*, _ctx: Context | None = None, _ident: Dict[str, Any] | None = None)

A Remote Application object.

This object represents the running application. It implements the “context manager” protocol, allowing a Python script to automatically close the communication channel when the application object goes out of scope.

property silence: bool

When set to True, silence all popup dialogs, using the dialog’s “default” action.

is_alive() → bool

Tests whether the application process is still running, and the communication socket to the application is still open.

Returns:

True is the application communication channel is open, False otherwise.

Return type:

bool

quit() → None

Terminate the remote application.

Note: The local side of the socket connection to the remote application may not be closed. The client is responsible for explicitly closing the connection:

application.quit()
application.close_connection()

or by using a context manager:

with ... as application:
    # interact with the application
    #
    # application.close_connection() is automatically called
    # when the `with` statement block exits.

close_connection() → None

Terminate connection to remote application.

Note: The remote application will not be terminated. The “silence all dialog and message boxes” flag is cleared.

property version: str

Application Version

minimum_version(version: str | Version) → bool

Test if the remote application version is the given version or later.

Parameters:

version (str) – The version number to test against.

Returns:

True if the remote application version is greater than

or equal to version, False otherwise.

Return type:

bool

requires(version: str, msg: str = 'Feature') → None

Verify the remote application is the given version or later.

A NotImplementedError is raised if the remote application version is less than the required version.

Parameters:

version (str) – The required version number.

property is_embedded: bool

Return whether an internal Python environment is being used

server_address() → Tuple[str, int]

Return the host/port address for the application server, which may be used to open additional connections to the application.

Added in version 2.4.5.

secondary_connection(timeout=5) → Application

Open a secondary connection to the application server

map_call(items: Sequence[Remotable], method: str, *args, **kwargs)

Call the same RMI method on a list of components, without using a round-trip to the server for each component.

Added in version 2.4.5.

map_property(items: Sequence[Remotable], name: str)

Fetch the same RMI property from a list of components, without using a round-trip to the server for each component.

Added in version 2.4.5.

Decorators

@rmi

remote.rmi(*, fallback=False)

Remote Method Invocation

Applying this decorator to a method of a Remotable object causes the method invocation to be forwarded to the remote application object.

If the remote application object’s method does not exist and fallback is True, then the body of the decorated method is used as an client-side (and likely slower) implementation of the remote method. Otherwise, the body of the decorated method is ignored.

@rmi_property

class mhi.common.remote.rmi_property(fget=None, fset=None, doc=None, name=None, requires=None)

A property which is stored in a remote object

Apply this decorator to a property of a Remotable object causes the property access attempts to be forwarded to the remote application object.

Remote properties may never be deleted.

Context

class mhi.common.remote.Context

A Remote Context object

This class is responsible for communications between the Python script and the remote application objects.

Calls to rmi methods and access to rmi_properties are pickled, and sent over a communication channel. The results of these operations are received from the communication channel, depickled, and returned to the caller. Any exception generated by the remote operation is also transfered over the communication channel and raised locally.

classmethod server_address() → Tuple[str, int]

Return the first host/port address for the application server, which may be used to open additional connections to the application.

Added in version 2.4.5.

Changed in version 3.0.2: Returns the first address, if listening on more than one address. Multiple addresses are possible when both IPv4 and IPv6 are supported.

classmethod server_addresses() → List[Tuple[str, int]]

Return the host/port addresses for the application server, which may be used to open additional connections to the application.

Added in version 3.0.2.

lookup(cls: Type[_Remotable], **identity) → _Remotable | None

Retrieve a Remote Proxy object, if it can be found in the cache

forget(obj: Remotable)

Remove a Remote Proxy object from the cache

is_alive() → bool

Is a connection to the server still active?

close() → None

Close communication

call(rcvr: Remotable, method_name: str, *args, **kwargs)

Make a remote call to the application method

If the application returns an exception object, the exception is raised here.

The mhi.common.remote.rmi decorator is more convenient.

Added in version 2.5.0.

get_prop(rcvr: Remotable, attr_name: str) → Any

Fetch a remote property

If the application returns an exception object, the exception is raised here.

The mhi.common.remote.rmi_property decorator is more convenient.

Added in version 2.5.0.

set_prop(rcvr: Remotable, attr_name: str, value: Any)

Set a remote property

If the application returns an exception object, the exception is raised here.

The mhi.common.remote.rmi_property decorator is more convenient.

Added in version 2.5.0.

Socket Context

class mhi.common.remote.SocketContext(sock)

A context object with the communication channel implemented as a TCP/IP socket.

is_alive() → bool

Is a connection to the server still active?

close() → None

Close communication

Queue Context

class mhi.common.remote.QueueContext(server)

A context object with the communication channel implemented with a Queue

is_alive() → bool

Is a connection to the server still active?

close() → None

Close communication

reply(reply)

Accept a message reply, for client

Exceptions

class mhi.common.remote.RemoteException(message, *args)

Indication of an API error communicating with remote objects