Plugin interface#

Interface definitions for implementing a local product launcher.

A plugin for the Local Product Launcher must implement the LauncherProtocol class and register it.

class ansys.tools.local_product_launcher.interface.DataclassProtocol(*args, **kwargs)#: Provides the Protocol class for Python dataclasses.

class ansys.tools.local_product_launcher.interface.LauncherProtocol(*, config)#

Interface for managing a local product instance.

A plugin to the Local Product Launcher must implement the interface defined in this class.

To check for compatibility, it is recommended to derive from this class, for example MyLauncher(LauncherProtocol[MyConfigModel]), and check the resulting code with mypy.

The __init__ method should accept exactly one keyword-only parameter: config. Note that this is not enforced by mypy.

Parameters:: config (TypeVar(LAUNCHER_CONFIG_T, bound= DataclassProtocol)) – Configuration options used to start the product. This parameter must be an instance of CONFIG_MODEL.

CONFIG_MODEL: type[TypeVar(LAUNCHER_CONFIG_T, bound= DataclassProtocol)]#

Defines the configuration options for the launcher.

The configuration options which this launcher accepts, specified as a dataclass. Note that the default and metadata[METADATA_KEY_DOC] of the fields are used in the configuration CLI, if available.

SERVER_SPEC: dict[str, ServerType]#

Defines the server types that are started.

Examples

This code defines a server that is accessible via a URL at the "MAIN" key and a server accessible via gRPC at the "FILE_TRANSFER" key.

SERVER_SPEC = {
    "MAIN": ServerType.GENERIC,
    "FILE_TRANSFER": ServerType.GRPC
}

The ProductInstance.urls attribute then has keys {"MAIN", "FILE_TRANSFER"}, whereas the ProductInstance.channels attribute has only the key "FILE_TRANSFER".

check(*, timeout=None)#

Check if the product instance is responding to requests.

Parameters:: timeout (Optional[float], default: None) – Timeout in seconds for the check. The timeout should be interpreted as a hint to the implementation. It is not required to return within the given time, but the check must return within a finite time, meaning it must not hang indefinitely.
Return type:: bool
Returns:: Whether the product instance is responding.

start()#

Start the product instance.

Return type:: None

stop(*, timeout=None)#

Stop the product instance.

Parameters:: timeout (Optional[float], default: None) – Time after which the instance can be forcefully stopped. The timeout should be interpreted as a hint to the implementation. It is not required to trigger a force-shutdown, but the stop must return within a finite time.
Return type:: None

property urls: dict[str, str]#

Dictionary of URLs that the server is listening on.

The keys of the returned dictionary must correspond to the keys defined in the LauncherProtocol.SERVER_SPEC attribute.

ansys.tools.local_product_launcher.interface.METADATA_KEY_DOC = 'launcher_doc'#: Key used in the dataclasses.Field metadata for the option description.

ansys.tools.local_product_launcher.interface.METADATA_KEY_NOPROMPT = 'launcher_noprompt'#: Key used in the dataclasses.Field metadata to skip prompting for the option by default.

class ansys.tools.local_product_launcher.interface.ServerType(value, names=None, *values, module=None, qualname=None, type=None, start=1, boundary=None)#

Defines which protocols the server supports.

The ServerType class is used as values in the LauncherProtocol.SERVER_SPEC attribute to define the capabilities of the servers started with a given product and launch method.

GENERIC = 1#

Generic server, which responds at a given URL and port.

The generic server type can be used for any server. It does not include information about which protocol should be used.

GRPC = 2#

Server that can be accessed via gRPC.

Servers of this type are accessible via the ProductInstance.channels attribute.