API reference#

Welcome to PyPIM API documentation. Use the search feature or click the links in the navigation pane to view API documentation.

Entry point for the PIM Python client library.

ansys.platform.instancemanagement.connect(uri: str | None = None, headers: dict | None = None, security: ConnectionSecurity | None = None) → Client#

Create a PyPIM client from the environment or from parameters.

Precedence is parameter-first and all-or-nothing: when uri is provided, the configuration file is ignored in full and the client is built from uri / headers / security. Otherwise, when the environment is configured (is_configured() is True), the configuration file is used in full.

The environment configuration consists in setting the environment variable ANSYS_PLATFORM_INSTANCEMANAGEMENT_CONFIG to the path of the PyPIM configuration file. The configuration file is a simple JSON file containing the URI of the PIM API and the headers required to pass information.

The configuration file format is:

{
    "version": 1,
    "pim": {
        "uri": "dns:pim.svc.com:80",
        "headers": {
            "metadata-info": "value"
        },
        "tls": false
    }
}

A version 2 file replaces tls with a security block selecting the transport. See Security for the version 2 schema and for programmatic configuration with the security parameter below.

Parameters:

uristr, optional: PIM gRPC service URI. When provided, it takes precedence over the configuration file and all settings are taken from uri / headers / security.
headersdict, optional: Metadata headers. The default is None (no headers).
securityConnectionSecurity, optional: Transport security. The default is None (insecure).

Returns:

Client: PyPIM client, which is the main entry point to using this library.

Raises:

NotConfiguredError: There is neither a configuration file nor a uri parameter.
InvalidConfigurationError: The configuration is invalid.

Examples

>>> import ansys.platform.instancemanagement as pypim
>>> if pypim.is_configured():
>>>     client = pypim.connect()
>>> # use the client
>>>     client.close()

>>> import ansys.platform.instancemanagement as pypim
>>> if pypim.is_configured():
>>>     with pypim.connect() as client:
>>> # use client

Connect programmatically with mTLS (no configuration file):

>>> import ansys.platform.instancemanagement as pypim
>>> from ansys.platform.instancemanagement import ConnectionSecurity
>>> from ansys.tools.common.cyberchannel import CertificateFiles
>>> client = pypim.connect(
...     uri="dns:pim.svc.com:80",
...     headers={"identity": "james"},
...     security=ConnectionSecurity(
...         transport="mtls",
...         cert_files=CertificateFiles(
...             cert_file="client.crt", key_file="client.key", ca_file="ca.crt"
...         ),
...     ),
... )

ansys.platform.instancemanagement.is_configured() → bool#

Check if the environment is configured to use PyPIM.

Returns:

bool: True when the environment is configured to use PyPIM, False otherwise.

`Client`	Provides a high-level client object for interacting with the PIM API.
`Definition`	Provides a definition of a product that can be started using the PIM API.
`Instance`	Provides a remote instance of a product.
`Service`	Provides an entry point for communicating with a remote product.
`Configuration`	Configuration for the PIM client.
`ConnectionSecurity`	Security settings for the client's connection to the PIM server.
`SecuritySettings`	Represent a union type
`InsecureSettings`	Insecure gRPC channel (no TLS).
`MtlsSettings`	Mutual TLS settings.
`MtlsCertificatePaths`	Individual certificate and key file paths for mTLS.
`UdsSettings`	Unix Domain Socket connection settings.
`WnuaSettings`	Windows user-based authentication (Windows only).
`ServiceSecurity`	Protobuf-free view of the server-resolved security info.
`NotConfiguredError`	Indicates an attempt was made to use PyPIM without the mandatory configuration.
`InstanceNotReadyError`	Indicates an attempt was made to communicate with an instance that is not yet ready.
`UnsupportedServiceError`	Indicates an attempt to use an unsupported instance service.
`InvalidConfigurationError`	Indicates PyPIM is configured, but the configuration is invalid.
`UnsupportedProductError`	Indicates that the product or version is not supported by the remote server.