.. _ref_python_wrapper:

.. currentmodule:: ansys.scadeone.core.svc.pywrapper

Python wrapper
==============

The Python wrapper is a PyScadeOne service that allows running a Scade One model in Python.

It works by generating a Python proxy for each root operator defined in the code generation job. This generation
can be performed using
:ref:`the PythonWrapper class <ref_python_wrapper_class_use>` or
:ref:`the Python wrapper command line <ref_python_wrapper_command_line>`. An example of use is given in
the :ref:`ref_python_wrapper_example` section.

Code generation job must be executed before using the Python wrapper service.

.. _ref_python_proxy:

Python proxy
------------

The Python proxy is a Python module containing a class that represents the root operators selected in the code
generation job.

This class has the following properties:

- inputs: the list of input variables
- outputs: the list of output variables

and the following methods:

- cycle: call the cycle function
- reset: call the reset function

The module also contains the sensors used by the root operator. The sensors are defined in
a global variable `sensors`.


Once the module is generated, it can be used in a Python script to execute a root operator,
providing the input values and getting the output ones:

.. code:: python

    # Import the generated Python proxy module
    import <proxy_name>

    # Create an instance of a root operator
    root_operator = <proxy_name>.<root_operator_name>()

    # Set the input variables
    root_operator.inputs.<input_variable_name> = <input_value>

    # Set the sensors
    sensors = <proxy_name>.sensors
    sensors.<sensor_name> = <sensor_value>

    # Execute the cycle function
    root_operator.cycle()

    # It could be executed multiple times
    root_operator.cycle(5) # the cycle function will be executed 5 times

    # Get the output variables
    output = root_operator.outputs.<output_variable_name>

    # Print the output value
    print(output)

    # Reset the operator
    root_operator.reset()

.. _ref_python_wrapper_class_use:

The :py:class:`PythonWrapper` class use
---------------------------------------

.. currentmodule:: ansys.scadeone.core.svc.pywrapper.python_wrapper

The Python proxy can be generated using the :py:class:`PythonWrapper` class as follows:

.. code:: python

    from ansys.scadeone.core.svc.pywrapper import PythonWrapper

    # Before using `PythonWrapper`, code generation job must be executed

    install_dir = <s_one_install>
    project_path = <scade_one_project_path>
    job_name = <codegen_job_name>
    proxy_name = <proxy_name>
    target_path = <target_path>

    app = ScadeOne(install_dir)
    project = app.load_project(project_path)

    # Create a PythonWrapper instance
    wrapper = PythonWrapper(project, job_name, proxy_name, target_path)
    wrapper.generate()

.. _ref_python_wrapper_command_line:

Python wrapper command line
---------------------------

The Python wrapper can also be generated using the PyScadeOne command line, by selecting the `wrapper` command.
All expected arguments can be passed through this command. A complete list of arguments is given by `\-\-help`.

.. code:: sh

    pyscadeone pycodewrap --help

.. code::

    usage: pyscadeone pycodewrap [-h] --install-dir INSTALL_DIR -j JOB [-o OUTPUT]
                             [--target-dir TARGET_DIR]
                             project

    positional arguments:
      project               Scade One project

    options:
      -h, --help            show this help message and exit
      --install-dir INSTALL_DIR
                            Scade One installation directory
      -j JOB, --job JOB     Generated Code job name
      -o OUTPUT, --output OUTPUT
                            Name of the Python wrapper module. By default, the
                            name is `root_wrapper`
      --target-dir TARGET_DIR
                            Wrapper directory. By default, a
                            directory with the wrapper name is created in the
                            current directory.

.. _ref_python_wrapper_doc:

Python wrapper class documentation
----------------------------------

This section gives the documenation of the :py:class:`PythonWrapper` class.

.. currentmodule:: ansys.scadeone.core.svc.pywrapper

.. autoclass:: PythonWrapper
    :class-doc-from: init
    :member-order: bysource

Limitations
-----------

The Python wrapper service only supports:

- root operators listed in the code generation job
- sensors
- types:
    - scalar types for sensors
    - scalar, structure, enum (without pragma enum_val) and array types for inputs and outputs.
      The array and structure types can only be defined by scalar types.
    - char type is not supported
    - imported types are not supported

Only default code generation using separate inputs and outputs is supported. Other code generation options (such as root
interface as global variables) are not supported.