Metadata-Version: 2.4
Name: ansys-platform-instancemanagement
Version: 1.2.0
Summary: A Python wrapper for Ansys platform instancemanagement
Author-email: "ANSYS, Inc." <pyansys.core@ansys.com>
Maintainer-email: "ANSYS, Inc." <pyansys.core@ansys.com>
Requires-Python: >=3.10,<4
Description-Content-Type: text/x-rst
License-Expression: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
License-File: LICENSE
Requires-Dist: importlib-metadata >=4.0
Requires-Dist: ansys-api-platform-instancemanagement~=1.2
Requires-Dist: ansys-tools-common ~= 0.5
Requires-Dist: ansys-api-platform-instancemanagement==1.2.0 ; extra == "doc"
Requires-Dist: ansys-sphinx-theme==1.9.0 ; extra == "doc"
Requires-Dist: ansys-tools-common==0.5.1 ; extra == "doc"
Requires-Dist: numpydoc==1.10.0 ; extra == "doc"
Requires-Dist: Sphinx==9.1.0 ; extra == "doc"
Requires-Dist: sphinx-copybutton==0.5.2 ; extra == "doc"
Requires-Dist: ansys-api-platform-instancemanagement==1.2.0 ; extra == "tests"
Requires-Dist: ansys-tools-common==0.5.1 ; extra == "tests"
Requires-Dist: grpcio-health-checking==1.78.0 ; extra == "tests"
Requires-Dist: grpcio-testing ; extra == "tests"
Requires-Dist: six~=1.16 ; extra == "tests"
Requires-Dist: pytest==9.1.1 ; extra == "tests"
Requires-Dist: pytest-cov==7.1.0 ; extra == "tests"
Project-URL: Discussions, https://github.com/ansys/pypim/discussions
Project-URL: Documentation, https://pypim.docs.pyansys.com/
Project-URL: Issues, https://github.com/ansys/pypim/issues
Project-URL: Releases, https://github.com/ansys/pypim/releases
Project-URL: Source, https://github.com/ansys/pypim
Provides-Extra: doc
Provides-Extra: tests

=====
PyPIM
=====
|pyansys| |PyPI| |codecov| |CI| |MIT| |black|

.. |pyansys| image:: https://img.shields.io/badge/Py-Ansys-ffc107.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAIAAACQkWg2AAABDklEQVQ4jWNgoDfg5mD8vE7q/3bpVyskbW0sMRUwofHD7Dh5OBkZGBgW7/3W2tZpa2tLQEOyOzeEsfumlK2tbVpaGj4N6jIs1lpsDAwMJ278sveMY2BgCA0NFRISwqkhyQ1q/Nyd3zg4OBgYGNjZ2ePi4rB5loGBhZnhxTLJ/9ulv26Q4uVk1NXV/f///////69du4Zdg78lx//t0v+3S88rFISInD59GqIH2esIJ8G9O2/XVwhjzpw5EAam1xkkBJn/bJX+v1365hxxuCAfH9+3b9/+////48cPuNehNsS7cDEzMTAwMMzb+Q2u4dOnT2vWrMHu9ZtzxP9vl/69RVpCkBlZ3N7enoDXBwEAAA+YYitOilMVAAAAAElFTkSuQmCC
   :target: https://docs.pyansys.com/
   :alt: PyAnsys

.. |PyPI| image:: https://img.shields.io/pypi/v/ansys-platform-instancemanagement
    :target: https://pypi.org/project/ansys-platform-instancemanagement/
    :alt: PyPI

.. |codecov| image:: https://codecov.io/gh/ansys/pypim/branch/main/graph/badge.svg
   :target: https://codecov.io/gh/ansys/pypim
   :alt: Code Coverage

.. |CI| image:: https://github.com/ansys/pypim/actions/workflows/ci_cd.yml/badge.svg
    :target: https://github.com/ansys/pypim/actions/workflows/ci_cd.yml
    :alt: GitHub Workflow Status (branch)

.. |MIT| image:: https://img.shields.io/badge/License-MIT-yellow.svg
   :target: https://opensource.org/licenses/MIT
   :alt: MIT License

.. |black| image:: https://img.shields.io/badge/code%20style-black-000000.svg?style=flat
  :target: https://github.com/psf/black
  :alt: black

`PyPIM <https://pypim.docs.pyansys.com>`_ exposes a Pythonic interface to
communicate with the Product Instance Management (PIM) API.

What is the PIM API?
============================================

The PIM API is a gRPC API, enabling both library and app developers to
start a product in a remote environment and communicate with its API.

The PIM API is intended to be as simple as possible to be adaptable in a variety of
network and software infrastructures. Using this API does not require any
knowledge of its infrastructure. You need only know which product to
start and which API the product exposes. The PIM API itself exposes very few
features and assumes that all the configuration is set on a server.

The PIM API is not intended to manage stateless services, to be a job management
system, or a fully featured service orchestration API. Its purpose is to expose
a minimum feature set for managing service-oriented apps.

Getting started
===============
To use PyPIM, you must have access to the PIM API.

.. note::
   The PIM API is a work in progress. Even though the API definition and the
   PyPIM client are published, the service itself is not publicly exposed.

PyPIM itself is pure Python and relies on `gRPC`_.

.. _`gRPC`: https://grpc.io/

Installation
------------

.. note::
   These instructions assume you are familiar
   with ``pip`` and the command line. If they are new to you, you should read
   the `Python Packaging User Guide Tutorial on pip <https://packaging.python.org/en/latest/tutorials/installing-packages/>`
   before proceeding.

The ``ansys-platform-instancemanagement`` package is tested for Python 3.10 through
Python 3.14 on Windows and Linux.

.. code-block::

    pip install ansys-platform-instancemanagement

Configuration
-------------

By default, PyPIM is configured externally instead of via code. Anywhere in the
local storage, create a configuration file with this format:

.. code-block:: json

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

Then, define the environment variable
``ANSYS_PLATFORM_INSTANCEMANAGEMENT_CONFIG`` to point to this configuration file.

Security
--------

By default, the connection to the PIM server is insecure. To use TLS, mutual
TLS (mTLS), a Unix Domain Socket (UDS), or Windows Named User Authentication
(WNUA) instead, either use a version 2 configuration file with a
``security`` block or pass the settings directly to ``connect()``:

.. code-block:: python

    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",
        security=ConnectionSecurity(
            transport="mtls",
            cert_files=CertificateFiles(
                cert_file="client.crt", key_file="client.key", ca_file="ca.crt"
            ),
        ),
    )

Product instances started with ``create_instance()`` can also request a
transport with the ``security_settings`` parameter, and the transport a
running instance actually uses is reported back on each of its services.
See `Security <https://pypim.docs.pyansys.com/version/dev/security.html>`_
in the PyPIM documentation for the full configuration file schema and all
supported transports.

Usage
-----
PyPIM is a single module called ``ansys.platform.instancemanagement``, shortened
to ``pypim``.

To start MAPDL and communicate with PyPIM, use this code:

.. code-block:: python

    import ansys.platform.instancemanagement as pypim
    from ansys.mapdl.core import Mapdl

    if pypim.is_configured():
        with pypim.connect() as pim:
            with pim.create_instance(
                product_name="mapdl", product_version="221"
            ) as instance:
                instance.wait_for_ready()
                channel = instance.build_grpc_channel(
                    options=[("grpc.max_receive_message_length", 8 * 1024**2)]
                )
                mapdl = Mapdl(channel=channel)
                mapdl.prep7()
                ...

You can also use PyPIM without the ``with`` statement, as shown in this code:

.. code-block:: python

    import ansys.platform.instancemanagement as pypim
    from ansys.mapdl.core import Mapdl

    if pypim.is_configured():
        pim = pypim.connect()
        instance = pim.create_instance(product_name="mapdl", product_version="221")
        channel = instance.build_grpc_channel(
            options=[("grpc.max_receive_message_length", 8 * 1024**2)]
        )
        mapdl = Mapdl(channel=channel)
        mapdl.prep7()
        ...
        instance.delete()
        pim.close()

Integration
-----------

PyPIM can be integrated in PyAnsys libraries to transparently switch to a remote
instance in a suitable environment. This process is described in `Integration <https://pypim.docs.pyansys.com/version/dev/integration.html>`_
in the PyPIM documentation.

For example, starting MAPDL with PyPIM is as simple as using this code:

.. code-block:: python

    from ansys.mapdl.core import launch_mapdl

    mapdl = launch_mapdl()


Ansys developer ecosystem resources
-----------------------------------

Ansys has an extensive developer ecosystem where you can find assistance for a variety of issues.

- `Developer Portal <https://developer.ansys.com/>`: Blog posts, documentation, and guide
- `Developer Forum <https://discuss.ansys.com/>`: Scripting and usage support for PyAnsys and other Ansys developer tools
- `Ansys Innovation Space <https://innovationspace.ansys.com/>`: Product support forum and training materials
- `GitHub <https://github.com/ansys/pypim>`: Development support, bug reporting, feature requests, and more.
- `Ansys Learning Hub <https://learninghub.ansys.com/>`: Training, courses and learning plans

