User guide¶

Installing packages¶

To install a single package, you can run rez pip2 example. Similarly to pip, multiple packages can be passed, like rez pip2 example1 example2.

On top of that, you can also use the -r/--requirement command line argument to install packages from a requirements file. The behavior is exaclty the same as with pip, so you can use it multiple times to install from multiple requriement files.

The -c/--constraint argument is also available and can also be used multiple times.

Note

By default, rez-pip will install packages in your configured local_packages_path. To install in your release_packages_path, use the --release command line argument.

Selecting the python version¶

rez pip2 will look for python packages that are available based on your rez configuration. By default, it will use all available versions.

By using --python-version, you can select which version of python to use for the requested packages. You can use the same version specifier syntax that rez supports (>=3, 3.7|3.9, etc) or you can also use latest.

Note

Your rez package that contains python needs to be named python. It will not work if your package is named differently.

Installing packages into a custom location¶

In some situations, you might need to install packages in a custom location. In such cases, you can use the -p/--prefix command line argument.

Passing arguments to pip directly¶

Passing command line arguments to pip can be achieved by using --. All arguments specified after -- will be forwarded to pip. For example, rez pip2 example -- --index-url https://example.com/simple will result in a pip command that looks like pip install example --index-url https://example.com/simple.

Changing log level¶

The log level can be adjusted by using the -l/--log-level command line argument. Use --help to see the accepted values.

Configuring pip¶

Since pip is used under the hood, pip can be configured as usual. See the pip configuration documentation for more information on the subject. Alternatively, you can also pass custom command line arguments to pip.

Writing a plugin¶

As documented in Register a plugin, plugins must be registered using entry points. This also means that your plugin will have to be packaged using standard Python packaging tools.

Note

Even if you package it using standard Python packaging tools, you won’t need to distribute it to PyPI.

Our plugin will have the following file structure:

my_plugin/
├── pyproject.toml
└── src/
    └── my_plugin/
        └── __init__.py

In pyproject.toml, we will define our package and plugin entry point:

pyproject.toml¶

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

[project.entry-points."rez-pip"]
my_plugin = "my_plugin"

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

This is the absolute minimum required to create a plugin. For more details on how to package a python project, please refer to the official documentation.

Now that this is out of the way, let’s write our plugin.

src/my_plugin/__init__.py¶

import logging

import rez_pip.plugins
import rez.package_maker

_LOG = logging.getLogger(__name__)


@rez_pip.plugins.hookimpl
def metadata(package: rez.package_maker.PackageMaker) -> None
    _LOG.info(
        "Adding my_custom_attr to the package definition of %s %s",
        package.name,
        package.version,
    )
    package.my_custom_attr = "my_custom_value"

Tip

It is highly recommended to add logs to your plugins. You can use logging.getLogger() to get a pre-configured logger. Make sure to pass a unique name to the logger.

Your logs should clearly describe what your plugin is doing. If your plugin modifies something, then it should log that. If it is just reading something, then you might not need to log.

The plugin we defined in src/my_plugin/__init__.py registers a hook called metadata that modifies the package definition. More particularly, it adds an attribute called my_custom_attr to the package definition. Here we use a dummy attribute name just to illustrate the concept. But this is a common scenario.

For brevity, we only implement one hook. rez pip2 provides many other hooks that you can implement. Hooks are documented in Hooks.

Once this is done, you can test your plugin by installing it. For example, you can use pip install -e . to install it in editable mode.