waylay-sdk 2024.8.2

Waylay Python SDK.

Waylay Python SDK

Python SDK for the Waylay Platform.

This waylay-sdk umbrella package is the main entrypoint to install the python SDK client for the Waylay REST apis.

It includes api support for the most relevant services, as extensions for the waylay-sdk-core base SDK client.

Alternatively:

• use the waylay-sdk-core package for a minimal SDK client
• use any of the waylay-sdk-{service} packages to install an SDK client that has api support for the selected service(s) only.

See Waylay Docs for extensive documentation.

Installation

This package requires a python runtime 3.9 or higher.

The basic client with api support for the common services, can be installed with

pip install waylay-sdk

To additionally typing support for a given service, e.g. for the alarms service:

pip install waylay-sdk[types-alarms]

... or for all services:

pip install waylay-sdk[types]

Service packages

Support for a specific Waylay REST api comes as a separate service package. Each service provides two packages:

• an api package waylay-<service>-sdk that describes all resources and actions for that service. JSON request and responses are represented as basic python data (dict, list, primitives)
• a types package waylay-<service>-sdk-types that provides pydantic models to represent JSON request and responses.

The types package is optional. When installed, its pydantic models are used to serialize requests and deserialize responses. When used in a python IDE, code completion will help you navigate the attributes of request and responses. This makes it easier to interact with the API as a developer. But as the underlying REST api evolves, the types package might require regular dependency updates.

Use the types package for interactive cases (python notebooks), or solutions that are regularly tested and maintained.

When not installed, the SDK client does not interfere with the json representations of requests and responses, and you should check the API documentation of the service for exact specifications.

The Service plugs are generated from their openapi description.

Included dependencies

This release of waylay-sdk includes the following api and (optional) types packages

name	package	api endpoint	docs	types package
alarms	waylay-sdk-alarms	/alarms/v1	doc openapi	waylay-sdk-alarms-types
data	waylay-sdk-data	/data/v1	doc openapi	waylay-sdk-data-types
registry	waylay-sdk-registry	/registry/v2	doc openapi	waylay-sdk-registry-types
resources	waylay-resources-alarms	/resources/v1	doc openapi	waylay-sdk-resources-types
rules	waylay-sdk-rules	/rules/v1	doc openapi	waylay-sdk-rules-types
storage	waylay-sdk-storage	/storage/v1	doc openapi	waylay-sdk-storage-types
queries	waylay-sdk-queries	/queries/v1	doc openapi	waylay-sdk-queries-types

Basic usage

In webscripts and plugins

The SDK client can be used in the python webscripts and plugins of the Waylay platform.

In that case, the webscript or plugin runtime will configure and authenticate a client, and provide it as a waylay parameter to the webscript or plugin callback function.

You just need to state the waylay-sdk dependency when authoring the webscript or plugin.

webscript example

async def execute(request: Request, waylay: WaylayClient):
    # list templates with the query as specified in the request body
    template_query = request.json()
    templates = await waylay.rules.templates.list(query=template_query)
    return templates

plug example

from csv import DictReader
from io import StringIO
async def execute(path: str, waylay: WaylayClient):
    """Return the CSV data from a file in assets storage."""
    # use the _List Objects_ operation, using the `path` plug property
    sign_resp = await waylay.storage.objects.list('assets', path, query={"sign": "GET"})
    content_url = sign_resp._links.get_object.href
    # fetch the csv data with the generic rest client, disable waylay auth for this signed url
    csv_data = await waylay.api_client.request('GET', content_url, auth=None)
    # parse as csv and return as a (state, rawData) tuple
    return ('OK', data=[
        record for record in DictReader(StringIO(csv_data))
    ])

Interactive Authentication

When used outside the Waylay platform (e.g. in a python notebook) the client requires you to provide

• the gateway endpoint: api.waylay.io for Enterprise users,
• an API key-secret pair: see Waylay Console at >Settings>Authentication keys.

from waylay.sdk import WaylayClient

# this will interactively request the gateway and credentials on first usage.
client = WaylayClient.from_profile()

# list the available service packages
client.services

# use the generic api client to see the status page of the 'registry' service.
resp = await client.api_client.request('GET', '/registry/v2')

Credentials and endpoints are stored in a local profile file (you can have multiple such profiles). Other authentication methods are available (JWToken, pass apiKey/Secret directly)