.. _scripting:

Scripting
=========

The server portion of |project| is provided as a Python_ module that can be used to script every aspect of the application.

.. _Python: https://python.org

Setting up your Python environment
----------------------------------

`Visual Studio Code`_ is the recommended development environment for |project|.
In addition, Microsoft's `Python extension`_ makes Python development a breeze.

To install the Python module, download the relevant `.whl.` file for your platform/Python version.
Then, install the wheel using ``pip``.

.. code:: shell

  python3 -m pip install VSPYX_FILENAME_GOES_HERE.whl

.. _Visual Studio Code: https://code.visualstudio.com/
.. _Python extension: https://marketplace.visualstudio.com/items?itemName=ms-python.python

Getting Started
---------------

To do anything meaningful with scripting you will need an instance of :py:class:`vspyx.Core.Application`.
By convention, an instance of this variable is usually named ``app``.

.. code:: python

  import vspyx

  app = vspyx.Core.Application.New()
  app.Initialize(loadAllModules=False)

When a script is running inside of |project| (for example, in the Text API console), a global variable ``app`` will already be defined.
A good habit is to check for this condition, so your script can both inside |project| and externally using the Python library.

.. code:: python

  import vspyx

  if 'app' not in globals():
        global app
        app = vspyx.Core.Application.New()
        app.Initialize(loadAllModules=False)

Most functionality in |project| is contained in discrete modules.
The ``loadAllModules`` argument to :py:func:`vspyx.Core.Application.Initialize` controls whether to load every available module.
When ``loadAllModules`` is false each module can be explicitly loaded through :py:func:`vspyx.Core.ModuleManager.GetModule`.

.. note::
  When explicitly loading a module, any dependent modules will be automatically loaded.

:py:class:`vspyx.VehicleSpy.Module` is a "glue" module ties together most other modules.
It provides the functionality present in the traditional |project| UI experience.

.. code:: python

  vehicle_spy = app.ModuleManager.GetModule("VehicleSpy")
  runtime = vehicle_spy.PrepareForStart()
  vehicle_spy.Start()

  # the instance is also cached as a property of app
  app.VehicleSpy.Stop()

Tutorials
----------

.. toctree::
   :maxdepth: 1

   tutorial/signalvalues
   tutorial/reporting
   tutorial/diagnostics
   tutorial/transmitting-can-frame
   tutorial/receiving-can-frame
   tutorial/soad-gateway
   tutorial/diagnostics-client
   tutorial/diagnostics-server