Metadata-Version: 2.2
Name: itchi
Version: 9.21.315.1
Summary: TASKING itchi
Author: TASKING Germany GmbH
Project-URL: Homepage, https://www.tasking.com
Project-URL: Support, https://support.tasking.com/T
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: jinja2
Requires-Dist: pydantic
Requires-Dist: PySide6
Provides-Extra: dev
Requires-Dist: mypy; extra == "dev"

# iTCHi Developer Readme

This document explains how to start working with iTCHi. To get started use
Visual Studio Code and open `itchi.code-workspace`.

If you are planning to use PyCharm, nothing special has to be done, just specify correct
venv and you are good to go. Note that there are no pre-made PyCharm run configurations,
but tests can be executed directly.

Consult the
[TASKING Python development guidelines](https://docs.google.com/document/d/1QZz1eke5sRy6dtNIWFOgIJwtmpwJQo_Z7ZqZ35VOyCo/edit?usp=sharing),
to make sure your code is compliant with the company policies.

## Getting Started With iTCHi

### Prepare the Python Virtual Environment

You can use existing venv or, even better, create a brand-new instance of venv for this project.
Using separate venv will ensure that there is no clashing of packages, and all necessary requirements
are specified in this project, making it self-contained.
Make sure that you are using the most recent version of python that is used in TASKING development.

Creating venv can be done using:

`<path to python interpreter> -m venv <desired venv location>`

To use this venv, we need to **activate it**. The location of activate script is os dependent.
On Linux it is `source <venv root dir>/bin/activate` and
on Windows `<venv root dir>/Scripts/activate.<ps1, bat, ...>`.

Once the venv is activated for the first time, it is recommended to upgrade pip by running
`python -m pip install --upgrade pip`.

### Installing the iTCHi Package

Once the venv is created, we need to install iTCHi package. If you plan do modify iTCHi sources,
make sure that you install iTCHi in the editable mode using `-e` flag for pip.

Installing iTCHi is simple:

- Activate venv
- Make sure that the `ISYSTEM_APPS` environment variable is configured.
- Navigate into the iTCHi root directory (where `pyproject.toml` is located)
- iTCHi requires the `isys_setup` tools; install them:
    - `pip wheel -w dist ..\..\..\Utils\isys_setup`
- Then, install iTCHi itself:
    - `pip install -e . --find-links dist`

## Launching iTCHi

Once iTCHi package is installed in the venv, we can launch it using `python -m itchi.itchi_cli`
or call `itchi-cli<.exe>` directly, since pip created an executable and added it into the PATH
on venv activation. Because we installed iTCHi in venv, we can call this command from anywhere
when iTCHi venv is active.

There is also a gui version `itchi-gui`, which imports cli version under the hood.

## Dependencies

iTCHi requires some third party packages, which are listed in `pyproject.toml`.
They are automatically installed once iTCHi is installed.
If new dependency is needed, it can be added to the `pyproject.toml` section `dependencies`.

## Tests

All tests are located in the `tests` directory. If new tests are created, make sure that you are not importing
the iTCHi components relative to the tests, but rather import it as installed package (no leading dots should
be present in the imports!). This will ensure that the tests are testing what will be deployed and not what we have
in the editable mode.

If some custom files are needed, specify them relative to the test file, for example:

```py
import os
file_of_interest = os.path.normpath(os.path.join(os.path.dirname(__file__),
                                                 'file_of_interest.png'))
```

This will ensure that test can be executed from arbitrary location, and we do not need to change current working directory.

Run `pytest .` in the itchi/tests directory to execute all tests. See pytest manual for more info how to execute them.

## fitIDEA Examples

The directory `examples/fitIDEA/testVectors` contain fitIDEA Profiler Unit Test files.
These YAML files contain a specific stimulus vector consisting of writes to variables
and executed functions, and an output timeline. With this approach, Profiler XMLs generated by
iTCHi can be tested in the winIDEA Analyzer itself.

To run the test vectors:

1. [Setup fitIDEA](https://docs.google.com/document/d/1k7MKQz4XBU7G-63X11Wpqt5PA-JtgLX1ymX_rqz1Jc8/edit#heading=h.wr3h1ixs14e4)
2. Open `examples/fitIDEA/sample.xjrf` in winIDEA.
3. Open a YAML file from the `testVectors` directory.
4. Run the YAML file like a Python script with `F6` or `ctrl+F6`.

## Adding a New Command

To add a new command, make sure to add it at the following locations:

1. The command parser in `src/itchi/itchi_cli.py`.
2. The launch configuration in `itchi.code-workspace` (for easier development).
3. The regression tests in `examples/test_examples`.
4. The documentation in `docs/readme.md`.
