Metadata-Version: 2.4
Name: tgzr.hosts.harmony
Version: 0.0.2
Summary: Toonboom Harmony integration in tgzr.
Project-URL: Documentation, https://github.com/open-tgzr/tgzr.hosts.harmony#readme
Project-URL: Issues, https://github.com/open-tgzr/tgzr.hosts.harmony/issues
Project-URL: Source, https://github.com/open-tgzr/tgzr.hosts.harmony
Author-email: Dee <dee.sometech@gmail.com>
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.9
Requires-Dist: pydantic-settings>=2.11.0
Requires-Dist: pydantic>=2.12.5
Requires-Dist: rich>=14.2.0
Requires-Dist: tgzr-package-management>=0.0.4
Description-Content-Type: text/markdown

# tgzr.hosts.harmony
Toonboom Harmony integration in tgzr

# Installation

## 1 - Create a python 3.9 venv

With uv:
```
uv venv -p 3.9 my_venv
```

Without uv, you need to install a python 3.9 and then use it to do:
```
python -m venv my_venv
```

## 2 - activate the venv

Windows:
```
my_venv\Scripts\activate
```

Others:
```
source my_venv/bin/activate
``` 

## 3 - install tgzr.hosts.harmony

With uv:
```
uv pip install -U tgzr.hosts.harmony
```

Without uv:
```
pip install -U tgzr.hosts.harmony
``` 

# Usage

With the virtualenv activated, enter:
```
harmony
```

The default path to find harmony is `"C:/Program Files (x86)/Toon Boom Animation/Toon Boom Harmony 25 Premium"` (The folder containing "win64/bin/HarmonyPremium.exe")

If your harmony is not installed in the default path, you can specify a custom one 
using an environment variable:
```
tgzr_hosts_harmony_install_path='c:/my_custom_install_folder_/'
```

or using a ".env" file:
```.env
tgzr_hosts_harmony_install_path='c:/my_custom_install_folder_/'
```

# Install a plugin 

Activate the virtualenv containing `tgzr.hosts.harmony`, and install the plugin there:

With uv:
```
uv pip install my-awesome-plugin
```

Without uv:
```
pip install my-awesome-plugin
```

# Create a plugin

## 1 - Create a new package

To create a plugin you need to create a python package.
An easy way is to use `uv`:

```
cd my-dev-folder
uv init -p 3.9 --package my-harmony-plugin
```

You will then have this structure:

```
my-harmony-plugin/
├── .git
├── .gitignore
├── pyproject.toml
├── .python-version
├── README.md
└── src
    └── my_harmony_plugin
        └── __init__.py
```

## 2 - Implement the plugin

In `my-harmony-plugin/src/my_harmony_plugin/__init__.py`, you can define your plugin.
A HarmonyPlugin must inherit the HarmonyPlugin class from `tgzr.hosts.harmony.plugin`:

```
from tgzr.hosts.harmony.plugin import HarmonyPlugin

class MyHarmonyPlugin(HarmonyPlugin):

    def prepare_env(self, env: dict[str, str]):
        '''Implement this if your plugin wants to set env vars'''

    def install(self):
        '''Implement this if your plugin wants to do something at harmony startup.'''
        print(f"Installing {self.plugin_id()}")

    def install_gui(self):
        '''Implement this if your plugin wants to do something at harmony GUI startup.'''
        print(f"Installing GUI {self.plugin_id()}")
```

You can add more python files there and import them in __init__.py if needed.
You can even import other packages / other plugins if you declare them as project dependencies in `pyproject.toml`.

## 3 - Declare the plugin

For you plugin to be discoverable when installed, you need to decare it as an "entry point" in your `pyproject.toml`.
The entry point group name must be "tgzr.hosts.harmony.plugin", and the entry point must lead to a subclass of HarmonyPlugin.

In our example, these would be the lines to add to `pyproject.toml`:

```pyproject.toml

[project.entry-points."tgzr.hosts.harmony.plugin"]
my_plugin = "my_harmony_plugin:MyHarmonyPlugin"

``` 

## 4 - Test your plugin

While developing, you will want to be able to see your changes in the code without building and installing the package every time.

To achieve that, you need to install your package in "editable" mode.\
From the root of your project, enter:
```
pip install -e .
```

You can now run `harmony` or `uv run harmony` and your plugin will be loaded \o/

## 4 - build the plugin package

With uv:
```
uv build
```

This will create a `dist` folder in your project and add a .tar.gz + a .whl file in it.

If you want to give your plugin to a friend, give them the .whl file and tell them
to run `pip install dist/my_harmony_plugin-[...].whl`

## 4 - publish the plugin package

If you want the whole world to be able to use your plugin, you can publish it to PyPI.

(you will need to create an account and a access token)

With `uv`
```
uv publish -t <your-token> dist/* 
```

> Note:
>
> You dont need to publish to PyPI to share your plugin. You can also
> host the file in a gitlab/github/... project and install it from there.
> (search "pip install package from github" for details)
>

Have fun!