Developing your own plugin¶

This guide will walk you through writing a rez plugin.

Warning

This section is under constructions. The instructions provided might not be accurate or up-to-date. We welcome contributions!

Structure¶

If you decide to register your plugin using the entry-points method, you are free to structure your plugin however you like.

If you decide to implement your plugins using the rezplugins namespace package, please refer to rezplugins structure to learn about the file structure that you will need to follow.

Registering subcommands¶

Optionally, plugins can provide new rez subcommands.

To register a plugin and expose a new subcommand, the plugin module:

MUST have a module-level docstring (used as the command help)
MUST provide a setup_parser() function
MUST provide a command() function
MUST provide a register_plugin() function
SHOULD have a module-level attribute command_behavior

For example, a plugin named foo and this is the foo.py in the plugin type root directory:

foo.py¶

"""The docstring for command help, this is required."""
import argparse

command_behavior = {
    "hidden": False,   # optional: bool
    "arg_mode": None,  # optional: None, "passthrough", "grouped"
}


def setup_parser(parser: argparse.ArgumentParser):
    parser.add_argument("--hello", action="store_true")


def command(
    opts: argparse.Namespace,
    parser: argparse.ArgumentParser,
    extra_arg_groups: list[list[str]],
):
    if opts.hello:
        print("world")


def register_plugin():
    """This function is your plugin entry point. Rez will call this function."""

    # import here to avoid circular imports.
    from rez.command import Command

    class CommandFoo(Command):
        # This is where you declare the settings the plugin accepts.
        schema_dict = {
            "str_option": str,
            "int_option": int,
        }

        @classmethod
        def name(cls):
            return "foo"

    return CommandFoo

Install plugins¶

Copy directly to rez install folder

To make your plugin available to rez, you can install it directly under src/rezplugins (that’s called a namespace package).
Add the source path to REZ_PLUGIN_PATH

Add the source path to the REZ_PLUGIN_PATH environment variable in order to make your plugin available to rez.
Add entry points to pyproject.toml

To make your plugin available to rez, you can also create an entry points section in your pyproject.toml file, that will allow you to install your plugin with pip install command.
pyproject.toml¶
```
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"

 [project]
 name = "foo"
 version = "0.1.0"

 [project.entry-points."rez.plugins"]
 foo_cmd = "foo"
```

Create a setup.py

To make your plugin available to rez, you can also create a setup.py file, that will allow you to install your plugin with pip install command.

setup.py¶

 from setuptools import setup, find_packages

 setup(
     name="foo",
     version="0.1.0",
     package_dir={
         "foo": "foo"
     },
     packages=find_packages(where="."),
     entry_points={
         'rez.plugins': [
             'foo_cmd = foo',
         ]
     }
 )