Developer setup¶

This guide will explain how to set up your environment in order to contribute to PyTVPaint.

Requirements¶

Python 3.9 or greater are the supported versions for PyTVPaint.
We use Hatch which is the packaging and dependency management tool. It handles your dev virtualenv with your working dependencies.

PyTVPaint¶

First clone the repository:

❯ git clone [https://github.com/brunchstudio/pytvpaint.git](https://github.com/brunchstudio/pytvpaint.git)

# or if you use SSH auth
❯ git clone git@github.com:brunchstudio/pytvpaint.git

then cd into the repo directory

❯ cd /path/to/the/repo

Install Hatch if needed:

❯ pip install hatch

Info

You may create the env and install the dependencies in a virtualenv with Hatch if you want to, but it is not necessary for hatch as it creates the environment on its own when needed:

❯ hatch env create # create the venv
❯ hatch shell # Enter the new venv shell

Note that this will install the library and default development dependencies. To install optional environments (to build the documentation, etc...) you can specify the environment name:

❯ hatch env create docs

Code formatting¶

We use Black to ensure that the code format is always the same. Black has strong defaults and is easy to use:

# Will format all the .py files in the current directory
❯ hatch run dev:black .

# To only check if the format is correct
❯ hatch run dev:black --check .

Or use the pyproject.toml shortcut :

# this is the same as running `black .`
❯ hatch run dev:format

Linting¶

We also use Ruff as a linter. It combines a lot of rules from other projects like Flake8, pyupgrade, pydocstyle, isort, etc...

❯ hatch run dev:ruff check .

# Will apply autofixes
❯ hatch run dev:ruff check --fix .

Or use the pyproject.toml shortcut :

# this is the same as running `ruff check --fix .`
❯ hatch run dev:lint

Type checking¶

Mypy is the go-to static type checker for Python. It ensures that variables and functions are used correctly and can catch refactor errors when editing the codebase.

❯ hatch run dev:mypy .

Or use the pyproject.toml shortcut :

# this is the same as running `mypy .`
❯ hatch run dev:typecheck

You can also use this shortcut to run all the steps above combined by running:

# This will run format then lint then typecheck.
❯ hatch run dev:all

Info

We currently exclude untyped calls for Fileseq and websocket-client in pyproject.toml with untyped_calls_exclude

Documentation¶

The documentation is built using Zensical which is a static site generator that uses Markdown as the source format.

You can either run the development server or build the entire documentation:

# Will serve the doc on [http://127.0.0.1:8000](http://127.0.0.1:8000) with hot reload
❯ hatch run docs:serve

# Build the doc as static files
❯ hatch run docs:build

The Python API documentation is auto-generated from the docstrings in the code by using Zensical. We use the Google style for docstrings.

For example:

def tv_request(msg: str, confirm_text: str = "Yes", cancel_text: str = "No") -> bool:
    """Open a confirmation prompt with a message.

    Args:
        msg: the message to display
        confirm_text: the confirm button text. Defaults to "Yes".
        cancel_text: the cancel button text. Defaults to "No".

    Returns:
        bool: True if clicked on "Yes"
    """
    return bool(int(send_cmd("tv_Request", msg, confirm_text, cancel_text)))

Unit tests¶

For the unit tests, we use Pytest. Fixtures are located in the conftest.py file.

To run the tests you'll need an open TVPaint instance with the tvpaint-rpc plugin installed.

To run them, use the following commands:

# run all the tests
❯ hatch run test:pytest

# Run with verbosity enabled (use PYTVPAINT_LOG_LEVEL to DEBUG) to see George commands
❯ hatch run test:pytest -v -s

# Only run specific tests with pattern matching
❯ hatch run test:pytest -k test_tv_clip

# See the coverage statistics with pytest-cov
❯ hatch run test:pytest --cov=pytvpaint