| Name | waylay-sdk JSON |
| Version |
2024.4.30
JSON |
| download |
| home_page | None |
| Summary | Waylay Python SDK. |
| upload_time | 2024-05-02 08:03:11 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | None |
| keywords |
waylay
sdk
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Waylay Python SDK
Python SDK for the Waylay Platform.
This `waylay-sdk` package is the main entrypoint to install the python SDK client for the [Waylay REST apis](https://docs.waylay.io/#/api/?id=openapi-docs).
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`](https://pypi.org/project/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](https://docs.waylay.io/#/api/sdk/python) for extensive documentation.
## Installation
This package requires a python runtime `3.9` or higher.
The basic client with api support for the [common services](#service-packages), can be installed with
```bash
pip install waylay-sdk
```
To additionally [typing](#service-packages) support for a given service, e.g. for the `alarms` service:
```bash
pip install waylay-sdk[types-alarms]
```
... or for all services:
```bash
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](https://docs.pydantic.dev/) 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](https://docs.waylay.io/#/api/?id=openapi-docs) of the service for exact specifications.
The Service plugs are _generated_ from their [openapi description](https://docs.waylay.io/#/api/?id=openapi-docs).
#### 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`](https://pypi.org/project/waylay-sdk-alarms) | `/alarms/v1` | [doc](https://docs.waylay.io/#/api/alarms/) [openapi](https://docs.waylay.io/openapi/public/redocly/alarms.html) | [`waylay-sdk-alarms-types`](https://pypi.org/project/waylay-sdk-alarms-types/) |
| `data` | [`waylay-sdk-data`](https://pypi.org/project/waylay-sdk-data) | `/data/v1` | [doc](https://docs.waylay.io/#/api/broker/) [openapi](https://docs.waylay.io/openapi/public/redocly/data.html) | [`waylay-sdk-data-types`](https://pypi.org/project/waylay-sdk-data-types/) |
| `registry` | [`waylay-sdk-registry`](https://pypi.org/project/waylay-sdk-registry) | `/registry/v2` | [doc](https://docs.waylay.io/#/api/registry/) [openapi](https://docs.waylay.io/openapi/public/redocly/registry.html) | [`waylay-sdk-registry-types`](https://pypi.org/project/waylay-sdk-registry-types/) |
| `resources` | [`waylay-resources-alarms`](https://pypi.org/project/waylay-sdk-resources) | `/resources/v1` | [doc](https://docs.waylay.io/#/api/resources/) [openapi](https://docs.waylay.io/openapi/public/resources/alarms.html) | [`waylay-sdk-resources-types`](https://pypi.org/project/waylay-sdk-resources-types/) |
| `rules` | [`waylay-sdk-rules`](https://pypi.org/project/waylay-sdk-rules) | `/rules/v1` | [doc](https://docs.waylay.io/#/api/rules/) [openapi](https://docs.waylay.io/openapi/public/redocly/rules.html) | [`waylay-sdk-rules-types`](https://pypi.org/project/waylay-sdk-rules-types/) |
| `storage` | [`waylay-sdk-storage`](https://pypi.org/project/waylay-sdk-storage) | `/storage/v1` | [doc](https://docs.waylay.io/#/api/storage/) [openapi](https://docs.waylay.io/openapi/public/redocly/storage.html) | [`waylay-sdk-storage-types`](https://pypi.org/project/waylay-sdk-storage-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
```python
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
```python
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](console.waylay.io) at _>Settings>Authentication keys_.
```python
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)
Raw data
{
"_id": null,
"home_page": null,
"name": "waylay-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "waylay, sdk",
"author": null,
"author_email": "Waylay <info@waylay.io>",
"download_url": "https://files.pythonhosted.org/packages/70/18/b3a67ed4e18aeafc83c29d61fbc9a5a5fe6e7e77b1baff630dd18c72c809/waylay_sdk-2024.4.30.tar.gz",
"platform": null,
"description": "# Waylay Python SDK\n\nPython SDK for the Waylay Platform.\n\nThis `waylay-sdk` package is the main entrypoint to install the python SDK client for the [Waylay REST apis](https://docs.waylay.io/#/api/?id=openapi-docs).\n\nIt includes api support for the most relevant services, as extensions for the `waylay-sdk-core` base SDK client.\n\nAlternatively:\n* use the [`waylay-sdk-core`](https://pypi.org/project/waylay-sdk-core) package for a minimal SDK client\n* use any of the `waylay-sdk-{service}` packages to install an SDK client that has api support for the selected service(s) only.\n\n\nSee [Waylay Docs](https://docs.waylay.io/#/api/sdk/python) for extensive documentation.\n\n## Installation\n\nThis package requires a python runtime `3.9` or higher.\n\nThe basic client with api support for the [common services](#service-packages), can be installed with\n```bash\npip install waylay-sdk\n```\n\nTo additionally [typing](#service-packages) support for a given service, e.g. for the `alarms` service:\n```bash\npip install waylay-sdk[types-alarms]\n```\n... or for all services:\n```bash\npip install waylay-sdk[types]\n```\n\n## Service packages\n\nSupport for a specific Waylay REST api comes as a separate _service package_.\nEach _service_ provides two packages:\n* 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)\n* a _types_ package `waylay-<service>-sdk-types` that provides [pydantic](https://docs.pydantic.dev/) models to represent JSON request and responses.\n\nThe _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.\nThis makes it easier to interact with the API as a developer. \nBut as the underlying REST api evolves, the _types_ package might require regular dependency updates.\n\nUse the _types_ package for interactive cases (python notebooks), or solutions that are regularly tested and maintained. \n\nWhen not installed, the SDK client does not interfere with the json representations of requests and responses, and you should check the [API documentation](https://docs.waylay.io/#/api/?id=openapi-docs) of the service for exact specifications.\n\nThe Service plugs are _generated_ from their [openapi description](https://docs.waylay.io/#/api/?id=openapi-docs).\n\n#### Included dependencies\n\nThis release of `waylay-sdk` includes the following _api_ and (optional) _types_ packages\n\n| name | package | api endpoint | docs | types package \n| ------- | ------------------ | ------- | --| --|\n| `alarms` | [`waylay-sdk-alarms`](https://pypi.org/project/waylay-sdk-alarms) | `/alarms/v1` | [doc](https://docs.waylay.io/#/api/alarms/) [openapi](https://docs.waylay.io/openapi/public/redocly/alarms.html) | [`waylay-sdk-alarms-types`](https://pypi.org/project/waylay-sdk-alarms-types/) |\n| `data` | [`waylay-sdk-data`](https://pypi.org/project/waylay-sdk-data) | `/data/v1` | [doc](https://docs.waylay.io/#/api/broker/) [openapi](https://docs.waylay.io/openapi/public/redocly/data.html) | [`waylay-sdk-data-types`](https://pypi.org/project/waylay-sdk-data-types/) |\n| `registry` | [`waylay-sdk-registry`](https://pypi.org/project/waylay-sdk-registry) | `/registry/v2` | [doc](https://docs.waylay.io/#/api/registry/) [openapi](https://docs.waylay.io/openapi/public/redocly/registry.html) | [`waylay-sdk-registry-types`](https://pypi.org/project/waylay-sdk-registry-types/) |\n| `resources` | [`waylay-resources-alarms`](https://pypi.org/project/waylay-sdk-resources) | `/resources/v1` | [doc](https://docs.waylay.io/#/api/resources/) [openapi](https://docs.waylay.io/openapi/public/resources/alarms.html) | [`waylay-sdk-resources-types`](https://pypi.org/project/waylay-sdk-resources-types/) |\n| `rules` | [`waylay-sdk-rules`](https://pypi.org/project/waylay-sdk-rules) | `/rules/v1` | [doc](https://docs.waylay.io/#/api/rules/) [openapi](https://docs.waylay.io/openapi/public/redocly/rules.html) | [`waylay-sdk-rules-types`](https://pypi.org/project/waylay-sdk-rules-types/) |\n| `storage` | [`waylay-sdk-storage`](https://pypi.org/project/waylay-sdk-storage) | `/storage/v1` | [doc](https://docs.waylay.io/#/api/storage/) [openapi](https://docs.waylay.io/openapi/public/redocly/storage.html) | [`waylay-sdk-storage-types`](https://pypi.org/project/waylay-sdk-storage-types/) |\n\n\n\n## Basic usage\n\n### In webscripts and plugins\n\nThe SDK client can be used in the _python_ webscripts and plugins of the Waylay platform.\n\nIn that case, the webscript or plugin _runtime_ will configure and authenticate a client, and \nprovide it as a `waylay` parameter to the _webscript_ or _plugin_ callback function.\n\nYou just need to state the `waylay-sdk` dependency when authoring the _webscript_ or _plugin_.\n\n\n#### webscript example\n```python\nasync def execute(request: Request, waylay: WaylayClient):\n # list templates with the query as specified in the request body\n template_query = request.json()\n templates = await waylay.rules.templates.list(query=template_query)\n return templates\n```\n\n#### plug example\n```python\nfrom csv import DictReader\nfrom io import StringIO\nasync def execute(path: str, waylay: WaylayClient):\n \"\"\"Return the CSV data from a file in assets storage.\"\"\"\n # use the _List Objects_ operation, using the `path` plug property\n sign_resp = await waylay.storage.objects.list('assets', path, query={\"sign\": \"GET\"})\n content_url = sign_resp._links.get_object.href\n # fetch the csv data with the generic rest client, disable waylay auth for this signed url\n csv_data = await waylay.api_client.request('GET', content_url, auth=None)\n # parse as csv and return as a (state, rawData) tuple\n return ('OK', data=[\n record for record in DictReader(StringIO(csv_data))\n ])\n```\n\n### Interactive Authentication\nWhen used outside the Waylay platform (e.g. in a _python notebook_) the client requires you to provide\n* the gateway endpoint: `api.waylay.io` for Enterprise users,\n* an API key-secret pair: see [Waylay Console](console.waylay.io) at _>Settings>Authentication keys_.\n\n```python\nfrom waylay.sdk import WaylayClient\n\n# this will interactively request the gateway and credentials on first usage.\nclient = WaylayClient.from_profile()\n\n# list the available service packages\nclient.services\n\n# use the generic api client to see the status page of the 'registry' service.\nresp = await client.api_client.request('GET', '/registry/v2')\n```\n\nCredentials and endpoints are stored in a local _profile_ file (you can have multiple such profiles).\nOther authentication methods are available (JWToken, pass apiKey/Secret directly)\n",
"bugtrack_url": null,
"license": null,
"summary": "Waylay Python SDK.",
"version": "2024.4.30",
"project_urls": {
"Documentation": "https://docs.waylay.io/#/api/sdk/python",
"Homepage": "https://www.waylay.io/",
"Repository": "https://github.com/waylayio/waylay-py-services.git"
},
"split_keywords": [
"waylay",
" sdk"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8956e37f420d38d1f270872a72a9db881b13d386592135df4963cd53db12cc20",
"md5": "b49041a179b4ef173019ec1afb14f3d9",
"sha256": "9385b601318361649a6d90168b91a589da884dcc9beb4b1b63d78ecb55a01b4a"
},
"downloads": -1,
"filename": "waylay_sdk-2024.4.30-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b49041a179b4ef173019ec1afb14f3d9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 4352,
"upload_time": "2024-05-02T08:03:08",
"upload_time_iso_8601": "2024-05-02T08:03:08.809151Z",
"url": "https://files.pythonhosted.org/packages/89/56/e37f420d38d1f270872a72a9db881b13d386592135df4963cd53db12cc20/waylay_sdk-2024.4.30-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7018b3a67ed4e18aeafc83c29d61fbc9a5a5fe6e7e77b1baff630dd18c72c809",
"md5": "7b5c5985208ae93e90f13aa169503631",
"sha256": "8137a249e3f0c05235c49bfcbb6b3f9593acfa2e2101a6eb6d6cc2f7c7f9a860"
},
"downloads": -1,
"filename": "waylay_sdk-2024.4.30.tar.gz",
"has_sig": false,
"md5_digest": "7b5c5985208ae93e90f13aa169503631",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 4676,
"upload_time": "2024-05-02T08:03:11",
"upload_time_iso_8601": "2024-05-02T08:03:11.079807Z",
"url": "https://files.pythonhosted.org/packages/70/18/b3a67ed4e18aeafc83c29d61fbc9a5a5fe6e7e77b1baff630dd18c72c809/waylay_sdk-2024.4.30.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-02 08:03:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "waylayio",
"github_project": "waylay-py-services",
"github_not_found": true,
"lcname": "waylay-sdk"
}
