itchi 9.21.390.1
TASKING itchi
Requires Python: >=3.10

# iTCHi Developer Readme

iTCHi is a helper tool closely tied to TASKING's
[winIDEA](https://www.tasking.com/products/winidea).

The purpose of iTCHi is to generate a valid configuration for winIDEA via
the so-called *winIDEA OS Description XML* file and to generate
instrumentation where necessary.

## Setup IDE

To work on iTCHi using Visual Studio Code, you can use the provided
workspace `itchi.code-workspace`.

If you are planning to use PyCharm, nothing special has to be done, just
specify the correct venv and you are good to go. Note that there are no
pre-made PyCharm run configurations, but tests can be executed directly.

## Setup Virtual Environment

You can use an existing venv or, even better, create a brand-new venv for
this project. Using a 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 a 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 the 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`.

## Install the iTCHi Package

Once the venv is created, you need to install the iTCHi package. If you
plan to modify iTCHi sources, make sure that you install iTCHi in editable
mode using the `-e` flag for pip.

Installing iTCHi is simple:

- Activate then venv
- Navigate into the iTCHi root directory (where `pyproject.toml` is located)
- Install it using `python -m pip install -e .` to install it in editable
  mode.
- If a wheel should be created, call `python -m pip wheel --no-deps .`

Note that if you want the actual version stored in \_\_version\_\_, you have
to define the `WINIDEA_BUILD_VERSION` environment variable prior to building
wheels.


## Launching iTCHi

Once the iTCHi package is installed in the venv, you can launch it using
`python -m itchi.itchi_cli` or call `itchi-cli<.exe>` directly, since pip
created an executable and added it to the PATH on venv activation. Because
you installed iTCHi in venv, you can call this command from anywhere when
the iTCHi venv is active.

There is also a GUI version `itchi-gui`, which imports the CLI version
under the hood.

## 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 them as installed packages (no leading dots should
be present in the imports!). This will ensure that the tests are testing
what will be deployed and not what is in 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 tests can be executed from arbitrary locations, and
you do not need to change the current working directory.

Run `pytest .` in the itchi/tests directory to execute all tests. See the
pytest manual for more info on how to execute them.

## 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`

## Setup venv and development via `uv`

If you would like to work on iTCHi using `uv`, initialize the virtual
environment by running `uv sync --extra dev`.

You can then run the tests via `uv run pytest`, format the code via
`uv run ruff format` and check for type errors via `uv run ty check`.

To run the CLI interface use `uv run itchi-cli` or to spawn the GUI use
`uv run itchi-gui`.