Skip to main content

relay-runtime

The official Python library for developing Relay applications and using Relay's public handler interfaces.

The package is optional for Relay's execution. Add it as a normal application dependency when your handlers import it. Its initial release publishes the HandlerContext structural Protocol; Relay's Python bootstrap constructs the actual context object for each invocation and passes it to the handler.

Install

With uv:

uv add relay-runtime

Or with pip:

pip install relay-runtime

The library supports Python 3.14 and newer.

Handler example

Relay calls a handler with the event as its first argument and the context as its second:

from relay_runtime.typing import HandlerContext


async def handler(event: dict, context: HandlerContext) -> None:
    print(
        f"request {context.request_id} "
        f"has {context.get_remaining_time_ms()}ms left"
    )

HandlerContext is a public typing.Protocol, not the concrete context implementation. Relay's Python bootstrap creates and supplies that actual per-invocation object. The current release provides HandlerContext; later releases may add application-development utilities.

Contract

HandlerContext provides:

Member Type Meaning
request_id str Stable identity for one logical invocation
attempt int 1-based attempt number
max_attempts int Configured total attempt budget
deadline datetime Absolute, timezone-aware cancellation instant
message_id str | None Source message identity when one exists
trace_id str | None W3C trace ID when tracing is enabled
app str Owning app name
handler str Handler identity
get_remaining_time_ms() int Milliseconds left, clamped at zero

max_attempts is the configured budget, not an upper bound on attempt: a configuration change can leave a claimed attempt above the current budget.

The package version is independent of the Relay release version. Future releases may add exports, and existing members keep their documented meaning.

Development

The package is managed with uv and uses a src layout with the uv_build backend.

cd packages/python
uv lock
uv sync --locked
uv run mypy
uv build
uv run pytest

uv.lock is committed so installs and checks resolve the same versions. The dev dependency group contains mypy and pytest only; neither is required by handlers or by the package at runtime.

License

GPL-3.0-or-later. See LICENSE.

Metadata

Release files for relay-runtime 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for relay-runtime 0.1.0
File Size Uploaded Provenance Actions
relay_runtime-0.1.0.tar.gz 3.2 kB With provenance Details for relay_runtime-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for relay-runtime 0.1.0
File Interpreter ABI Platform Actions
relay_runtime-0.1.0-py3-none-any.whl Python 3 none any Details for relay_runtime-0.1.0-py3-none-any.whl

Total release size: 8.0 kB

Release files / relay_runtime-0.1.0.tar.gz

Download URL relay_runtime-0.1.0.tar.gz
Size 3.2 kB
Tags Source
SHA-256 checksum
How to use checksums
abf138904dd3cef0f382cf8b942e8aadd2aaca84102988eae20ad1320d3d8679
BLAKE2b-256 checksum
How to use checksums
b0f964439056e3034762b3862eeacc73df3e3c6e8c547d2a9047cba464bc859e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Release files / relay_runtime-0.1.0-py3-none-any.whl

Download URL relay_runtime-0.1.0-py3-none-any.whl
Size 4.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4eb84ec585dafbfad0c7f46172f5fac6d3f69805a471d61c8289dae29e3c6f2b
BLAKE2b-256 checksum
How to use checksums
488939347688bffe191de5a166e854d5c2177a4e49d76a0a5bc14ad69123ee31
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Security for relay-runtime 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for relay_runtime-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page