tgzr.hosts.harmony 0.0.2

Toonboom Harmony integration in tgzr.

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:

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:

[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!