The ``cyberchannel.py`` module
==============================

.. py:module:: ansys.tools.common.cyberchannel


Summary
-------








.. py:currentmodule:: cyberchannel
.. tab-set::







    .. tab-item:: Functions

        .. list-table::
          :header-rows: 0
          :widths: auto


          * - :py:obj:`~create_channel`
            - Create a gRPC channel based on the transport mode.


          * - :py:obj:`~verify_transport_mode`
            - Verify that the provided transport mode is valid.


          * - :py:obj:`~verify_uds_socket`
            - Verify that the UDS socket file has been created.

















Description
-----------

Module to create gRPC channels with different transport modes.

This module provides functions to create gRPC channels based on the specified
transport mode, including insecure, Unix Domain Sockets (UDS), Windows Named User
Authentication (WNUA), and Mutual TLS (mTLS).

Example
-------

.. code-block:: python

    channel = create_channel(
        host="localhost",
        port=50051,
        transport_mode="mtls",
        certs_dir="path/to/certs",
        grpc_options=[("grpc.max_receive_message_length", 50 * 1024 * 1024)],
    )
    stub = hello_pb2_grpc.GreeterStub(channel)







Module detail
-------------

.. py:function:: create_channel(transport_mode: str, host: str | None = None, port: int | str | None = None, uds_service: str | None = None, uds_dir: str | pathlib.Path | None = None, uds_id: str | None = None, uds_fullpath: str | pathlib.Path | None = None, certs_dir: str | pathlib.Path | None = None, cert_files: CertificateFiles | None = None, grpc_options: list[tuple[str, object]] | None = None) -> grpc.Channel

   Create a gRPC channel based on the transport mode.

   Parameters
   ----------
   transport_mode : str
       Transport mode selected by the user.
       Options are: "insecure", "uds", "wnua", "mtls"
   host : str | None
       Hostname or IP address of the server.
       By default `None` - however, if not using UDS transport mode,
       it will be requested.
   port : int | str | None
       Port in which the server is running.
       By default `None` - however, if not using UDS transport mode,
       it will be requested.
   uds_service : str | None
       Optional service name for the UDS socket.
       By default `None` - however, if UDS is selected, it will
       be requested.
   uds_dir : str | Path | None
       Directory to use for Unix Domain Sockets (UDS) transport mode.
       By default `None` and thus it will use the "~/.conn" folder.
   uds_id : str | None
       Optional ID to use for the UDS socket filename.
       By default `None` and thus it will use "<uds_service>.sock".
       Otherwise, the socket filename will be "<uds_service>-<uds_id>.sock".
   uds_fullpath : str | Path | None
       Full path to the UDS socket file.
       By default `None` and thus it will use the `uds_service`, `uds_dir` and `uds_id` parameters.
   certs_dir : str | Path | None
       Directory to use for TLS certificates.
       By default `None` and thus search for the "ANSYS_GRPC_CERTIFICATES" environment variable.
       If not found, it will use the "certs" folder assuming it is in the current working
       directory.
   cert_files: CertificateFiles | None = None
       Path to the client certificate file, client key file, and issuing certificate authority.
       By default `None`.
       If all three file paths are not all provided, use the certs_dir parameter.
   grpc_options: list[tuple[str, object]] | None
       gRPC channel options to pass when creating the channel.
       Each option is a tuple of the form ("option_name", value).
       By default `None` and thus no extra options are added.

   Returns
   -------
   grpc.Channel
       The created gRPC channel



.. py:function:: verify_transport_mode(transport_mode: str, mode: str | None = None) -> None

   Verify that the provided transport mode is valid.

   Parameters
   ----------
   transport_mode : str
       The transport mode to verify.
   mode : str | None
       Can be one of "all", "local" or "remote" to restrict the valid transport modes.
       By default `None` and thus all transport modes are accepted.

   Raises
   ------
   ValueError
       If the transport mode is not one of the accepted values.



.. py:function:: verify_uds_socket(uds_service: str | None = None, uds_dir: pathlib.Path | None = None, uds_id: str | None = None, uds_fullpath: str | pathlib.Path | None = None) -> bool

   Verify that the UDS socket file has been created.

   Parameters
   ----------
   uds_service : str | None
       Service name for the UDS socket.
   uds_dir : Path | None
       Directory where the UDS socket file is expected to be (optional).
       By default `None` and thus it will use the "~/.conn" folder.
   uds_id : str | None
       Unique identifier for the UDS socket (optional).
       By default `None` and thus it will use "<uds_service>.sock".
       Otherwise, the socket filename will be "<uds_service>-<uds_id>.sock".
   uds_fullpath : str | Path | None
       Full path to the UDS socket file.
       By default `None` and thus it will use the `uds_service`, `uds_dir` and `uds_id` parameters.

   Returns
   -------
   bool
       True if the UDS socket file exists, False otherwise.