rez-python-api

Rez Python API — ResolvedContext construction and inspection, Package/Variant objects, programmatic resolves, .rxt context serialisation and deserialisation, running commands inside a context, and the module entry points (rez.resolved_context, rez.packages, rez.config, rez.pip, rez.suite, rez.bundle_context). Use when the user wants to drive rez from Python instead of the CLI, or asks what a context object actually holds. Covers Rez 3.4.0.

One-sentence summary: ResolvedContext is the whole product — build one from a list of request strings, read the result off success, resolved_packages and get_environ(), persist it with save() / load(), and only open a shell through execute_shell() when you really need one.

Skill scope: embedding rez in Python. For the CLI equivalents see rez-cli; for solver internals see rez-resolve; for a context used as a deliverable artifact see rez-suites-bundles.

Before you embed rez

Two warnings straight from upstream docs/source/api.rst, and both change the design of a tool:

• There are no compatibility guarantees between rez versions. Pin the rez you import, the same way the CLI lanes in this repository pin REZ_VERSION.
• Config is read once, at first import. The Python API cannot reread configuration files or switch to a different REZ_CONFIG_FILE afterwards. A tool that has to change config mid-run must shell out to the CLI instead.

Confirm what you are actually about to import before you trust any of the code below:

bash

rez-status

Module entry points

Module	What it holds
rez.resolved_context	ResolvedContext — a resolve, and everything you do with one
rez.packages	Package, Variant, iter_packages, get_package, get_variant, get_latest_package_from_string
rez.config	config — the merged, live settings object
rez.resolver, rez.solver	Resolver, ResolverStatus, the solver itself
rez.suite	Suite — see rez-suites-bundles
rez.bundle_context	bundle_context — see rez-suites-bundles
rez.pip	pip_install_package — see rez-pip-integration
rez.developer_package	build a package from source in-process
rez.package_repository, rez.package_resources	repositories and the resources they hand out
rez.version	Version, VersionRange, Requirement, RequirementList, VersionError
rez.exceptions	every rez error type; all of them derive from RezError
rez.wrapper	the module behind the main console script

Constructing a context

python

from rez.resolved_context import ResolvedContext

# Requests are plain strings, exactly what you would pass to rez-env.
context = ResolvedContext(["foo-1", "bar"])

if not context.success:
    raise SystemExit(context.failure_description)

ResolvedContext(requests, ...) takes the request list positionally. The arguments worth knowing:

Argument	Meaning
verbosity	0, 1 or 2 — the same levels rez-env -v gives you
timestamp	epoch time; ignore packages released after it
building / testing	resolve as if for rez-build / rez-test
caching	None defers to the resolve_caching setting; False bypasses caches
package_paths	override packages_path for this resolve only
package_filter	a PackageFilterList; rez.package_filter.no_filter removes filtering
add_implicit_packages	append the implicit_packages (default True)
max_fails / time_limit	stop after N failures / after N seconds

Set verbosity=1 before reaching for a debugger: the solver trace is the same one rez-env -v prints.

Reading the result

python

context.status                    # ResolverStatus.solved | .failed | .aborted | .pending
context.success                   # True when status is solved
context.failure_description       # why it failed, when it did
context.requested_packages()      # [Requirement, ...] — the request; implicits only if include_implicit=True
context.resolved_packages         # [Variant, ...] — what the solver picked
context.resolved_ephemerals       # resolved ephemeral (implicit-ish) packages
context.get_resolve_as_exact_requests()   # ['foo==1.1.0', ...] — pin the resolve down
context.get_environ()             # dict: the environment the context would produce
context.get_tools()               # {tool_name: (Variant, [alias, ...])}
context.which("foo")              # absolute path to a tool, or None
context.get_resolved_package("foo")       # the Variant, or None
context.print_info(source_order=True)     # the rez-context --so view, on stdout

resolved_packages yields Variant objects, not Package objects. A Package is a family; a Variant is one resolved member of it, with .name, .version, .qualified_name, .root, .requires, .tools and .data on it. Reach for get_resolved_package(name) when you want one package out of a resolve, and get_environ() when you want the environment without running anything.

Context files (.rxt)

A context serialises to a .rxt file, which is how a resolve becomes something you can hand to another process, another machine, or another day:

python

context.save("context.rxt")                # write it
same = ResolvedContext.load("context.rxt") # read it back

# Or keep it in memory:
from io import StringIO
buf = StringIO()
context.write_to_buffer(buf)
buf.seek(0)
again = ResolvedContext.read_from_buffer(buf)

# Or move it through your own dict/JSON pipeline:
data = context.to_dict()
rebuilt = ResolvedContext.from_dict(data)

save() / load() and write_to_buffer() / read_from_buffer() round-trip the resolve, not the environment — loading is cheap, and no package payload is re-read. to_dict() carries the metadata (status, package_requests, resolved_packages, failure_description, serialize_version, rez_version, ...) rather than a stable public schema; treat it as rez's own format, not as an API you own.

validate() re-checks the context and raises ResolvedContextError when it no longer holds; call it before trusting a context that has been sitting on disk.

Running things inside a context

python

# One command, non-interactive, with the context's environment:
proc = context.execute_command(["foo", "--version"])
print(proc.returncode)

# The environment as shell source, without starting a shell:
code = context.get_shell_code()

# An interactive shell — blocks, so only do this in a real terminal:
context.execute_shell(block=True)

Prefer execute_command() and get_environ() in automation. execute_shell() inherits the terminal, so it is the wrong call in a service or a test; get_shell_code() takes a style of OutputStyle.file (writable into a script) or OutputStyle.eval (sourceable in one shot).

Packages and variants

python

from rez.packages import iter_packages, get_package, get_latest_package_from_string

for package in iter_packages("foo"):          # every version of one family
    print(package.version)

package = get_package("foo", "1.1.0")         # one exact package, or None
latest = get_latest_package_from_string("foo")

get_latest_package_from_string accepts the same spellings a request does, so it is also the cheapest way to turn a user-supplied string into a concrete package. iter_packages walks the search path; both take paths= when you need to point them at a specific repository.

Configuration

python

from rez.config import config

config.packages_path
config.local_packages_path

config is the merged settings object, so an attribute read is the answer to "what took effect", not "what is in the file". It is read at import — see the warning at the top.

Errors

Every rez exception derives from RezError (rez.exceptions), so one except RezError catches the library. The ones you are most likely to handle:

Exception	Raised by
ResolveError	a resolve that cannot be performed
PackageNotFoundError / PackageFamilyNotFoundError	a package that is not there
PackageRequestError	a malformed request string
ResolvedContextError	validate() on a context that no longer holds
SuiteError	suite operations — see rez-suites-bundles
ContextBundleError	bundling — see rez-suites-bundles

Cross-check against the CLI

When an API result looks wrong, reproduce it with the CLI before you debug your own code — the CLI is the reference implementation and it reads the config fresh:

bash

rez-env foo -o context.rxt --no-cache   # ResolvedContext(..., caching=False)
rez-context context.rxt --so            # context.print_info(source_order=True)

rez-context --so prints exactly the requested packages / resolved packages split that context.print_info(source_order=True) prints, and -v on rez-env is the same trace you get from verbosity=1.

Gotchas

Symptom	Cause
Config changes ignored	rez was already imported; the API cannot reread config. Use the CLI
resolved_packages order surprises you	it is solver order; only print_info() sorts, and source_order=True skips that sort
Attribute missing after an upgrade	no cross-version API guarantees — pin rez
A resolve differs from rez-env	compare package_paths, add_implicit_packages and caching
execute_shell() hangs in CI	it wants a terminal; use execute_command()

Agent workflow

1. Import rez once, at the top of the process; never rely on rereading config afterwards.
2. Build one ResolvedContext, then read success and failure_description before anything else.
3. Inspect with resolved_packages / get_environ() / get_tools() instead of opening a shell.
4. Persist with save() when another process needs the resolve; validate() it before trusting it.
5. When the API and the CLI disagree, believe the CLI and diff the arguments above.