# relay-sdk-python

**Repository Path**: mirrors_puppetlabs/relay-sdk-python

## Basic Information

- **Project Name**: relay-sdk-python
- **Description**: Python SDK for integrating with Relay
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2020-08-18
- **Last Updated**: 2026-04-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

Relay Python SDK
================

Installation
------------

The SDK is available to install via `pip`:

.. code-block:: console

  pip install relay-sdk

If you use the `relaysh/core:latest-python <https://hub.docker.com/r/relaysh/core/tags>`_ container image as your base
image, it'll be pre-installed.

Usage
-----
The main purpose of the SDK is to provide helpers for interacting with Relay's
metadata service. Each container that runs in Relay has access to this service,
which allows the container to read and write key-value data, emit events, and
generate logs.

Accessing Data from the step spec
---------------------------------

The `Interface class <./reference.html#module-relay_sdk.interface>`_ is the primary way to interact with the service.
Import it and instantiate an object, then call methods on that object to access metadata,
which comes from the ``spec`` section of the step and global Connection information.
The ``Dynamic`` class provides syntactic sugar for getting data like connection credentials, 
workflow-specific parameters, and secrets. It represents nested data structures as dot-separated
method accessors.

.. code-block:: python

  from relay_sdk import Interface, Dynamic as D

  relay = Interface()
  azuresecret = relay.get(D.azure.connection.secret) # using Dynamic
  azureclient = relay.get('azure["connection"]["clientID"]') # same as above
  secret = relay.get(D.mysecret)
  relay.outputs.set("outputkey","This will be the value of outputkey")

Running Workflows
-----------------

The `Workflow class <./reference.html#module-relay_sdk.workflows>`_ offers the method ``run``
to run a workflow.

Use the following to run the workflow ``my_workflow`` with parameter ``param_name`` and value ``param_value``:

.. code-block:: python

  from relay_sdk import Interface

  relay = Interface()
  relay.workflows.run('my_workflow', parameters={'param_name':'param_value'})

Webhook Triggers
----------------

The `WebhookServer class <./reference.html#module-relay_sdk.webhook>`_ provides a
helper that sets up a webserver to handle incoming requests for Trigger actions. 

This example, from the `Docker Hub integration <https://github.com/relay-integrations/relay-dockerhub/>`_, makes use of
the Interface class to access the ``events.emit`` method, which will cause
the workflow associated with this trigger to be run with the inline mapping
of workflow parameters to values extracted from the webhook payload.

The WebhookServer class can run any WSGI_ or ASGI_ application passed to it. The
integrations the Relay team develops internally use the Quart_ web app framework.

.. _WSGI: https://www.python.org/dev/peps/pep-3333/
.. _ASGI: https://asgi.readthedocs.io/en/latest/specs/main.html
.. _Quart: https://pgjones.gitlab.io/quart/index.html

.. code-block:: python

  from relay_sdk import Interface, WebhookServer
  from quart import Quart, request, jsonify, make_response

  relay = Interface()
  app = Quart('image-pushed')

  @app.route('/', methods=['POST'])
  async def handler():
      event_payload = await request.get_json()

      if event_payload is None:
          return await make_response(jsonify(message='not a valid Docker Hub event'), 400)

      pd = event_payload['push_data']
      rd = event_payload['repository']

      relay.events.emit({
          'pushedAt': pd['pushed_at'],
          'pusher': pd['pusher'],
          'tag': pd['tag'],
          'name': rd['repo_name']
      })

      return await make_response(jsonify(message='success'), 200)


  if __name__ == '__main__':
      WebhookServer(app).serve_forever()