From 31d7450fc84d958180ed8d022f7acaa6feefc9d0 Mon Sep 17 00:00:00 2001 From: Enrico Eberhard <32450951+eeberhard@users.noreply.github.com> Date: Tue, 4 Feb 2025 10:23:58 +0100 Subject: [PATCH] release(client): v3.1.0 (#213) --- python/CHANGELOG.md | 12 +++++-- python/README.md | 82 +++++++++++++++++++++++++++++++++++-------- python/pyproject.toml | 2 +- 3 files changed, 77 insertions(+), 19 deletions(-) diff --git a/python/CHANGELOG.md b/python/CHANGELOG.md index 9f2701b..b6a0213 100644 --- a/python/CHANGELOG.md +++ b/python/CHANGELOG.md @@ -2,6 +2,7 @@ Release Versions: +- [3.1.0](#310) - [3.0.0](#300) - [2.1.0](#210) - [2.0.0](#200) @@ -12,10 +13,15 @@ Release Versions: - [1.0.1](#101) - [1.0.0](#100) -## Upcoming changes +## 3.1.0 -- feat(python): add support for the upcoming auth update (#207) -- fix(api): avoid auth warnings when using older versions of Core (#211) +Version 3.1.0 of the AICA API client is compatible with AICA Core v4.3.0. This version introduces authentication and +access scopes to the API server. An API key with appropriate scopes is required to access the respective endpoints and +functionalities. + +### Features + +- Add support for the upcoming auth update (#207) ## 3.0.0 diff --git a/python/README.md b/python/README.md index 0563d0d..26055f1 100644 --- a/python/README.md +++ b/python/README.md @@ -1,18 +1,27 @@ # Python AICA API Client -The AICA API client module provides simple functions for interacting with the API of the AICA Core. - ```shell pip install aica-api ``` -The client can be used to easily make API calls as shown below: +The AICA API client module provides simple functions for interacting with the AICA Core through a REST API. -```python3 +Refer to https://docs.aica.tech for more information about the AICA System. + +## Basic usage + +```python from aica_api.client import AICA aica = AICA() +if aica.check(): + print(f"Connected to AICA Core version {aica.core_version()}") +``` + +The client object can be used to easily make API calls to monitor or control AICA Core. For example: + +```python3 aica.set_application('my_application.yaml') aica.start_application() @@ -25,10 +34,6 @@ aica.stop_application() To check the status of predicates and conditions, the following blocking methods can be employed: ```python3 -from aica_api.client import AICA - -aica = AICA() - if aica.wait_for_condition('timer_1_active', timeout=10.0): print('Condition is true!') else: @@ -40,6 +45,49 @@ else: print('Timed out before predicate was true') ``` +Refer to the available methods of the `AICA` client class for more advanced usage. + +## Network configuration + +By default, the API server of AICA Core is available on the default address `localhost:8080`. Depending on the network +configuration, the URL or port number of the AICA Core instance may be different. + +For example, when using AICA Launcher on macOS, the API is bound to a different, randomly generated port to avoid +conflict with reserved ports. Use the "Open in browser" button from Launcher to open AICA Studio in the browser and copy +the port from the url. + +```python +from aica_api.client import AICA + +# connect to a non-default port on the local network +aica = AICA(port=55000) + +# or connect to a different host address entirely +aica = AICA(url='192.168.0.1', port=55005) +``` + +## Authentication with an API key + +For connecting to AICA Core v4.3.0 and later, an API key is required for authentication. + +API keys can be generated in AICA Studio with configurable access scopes. Note that available scopes are limited to +those of the currently logged-in user. A generated API key is only shown once and should be kept secret. For example, it +may be exported as an environment variable. The following example key is shown for demonstrative purposes only: + +```shell +export AICA_API_KEY=64ce9e8f-aa46-4ba7-814f-f169c01c957e.RwoH6A1Ti5poNKSizoWrcBEYzh7AkB0kpMq1TR59t6os +``` + +The API key can then be provided to the constructor with the `api_key` keyword argument: + +```python +import os +from aica_api.client import AICA + +AICA_API_KEY = os.getenv('AICA_API_KEY') +aica = AICA(api_key=AICA_API_KEY) +``` + ## Compatability table The latest version of this AICA API client will generally support the latest AICA Core version. @@ -49,7 +97,8 @@ Use the following compatability table to determine which client version to use. | AICA Core version | API protocol version | Matching Python client version | |-------------------|----------------------|--------------------------------| -| `4.x` | `v2` | `>= 3.0.0` | +| `>= 4.3` | `v2` | `>= 3.1.0` | +| `>= 4.0, < 4.3` | `v2` | `>= 3.0.0` | | `3.x` | `v2` | `>= 2.0.0` | | `2.x` | `v2` | `1.2.0` | | `<= 1.x` | `v1` | Unsupported | @@ -62,7 +111,7 @@ endpoints and functions respectively. If a function requires a feature that the support (as is the case when the Python client version is more up-to-date than the targeted AICA Core), then calling that function will return None with a warning. -### Changes between major server versions +### Changes to API behavior between AICA Core versions AICA Core versions `v1.x` and earlier were alpha and pre-alpha versions that are no longer supported. @@ -72,11 +121,14 @@ In AICA Core `v3.x`, live data streaming for predicates and conditions switched for data transfer. This constituted a breaking change to API clients, but the overall structure of the REST API remained the same, and so the API protocol version is still `v2`. -AICA Core versions `v4.x` and later keep the same protocol structure as before under the `v2` namespace. The primary -breaking change from the point of the API server and client is that the `/version` endpoint now returns the version of -AICA Core, rather than the specific version of the API server subpackage inside core. These have historically carried -the same major version, but in future the core version may have major updates without any breaking changes to the -actual API server version. +AICA Core versions `v4.0` through `v4.2` keep the same protocol structure as before under the `v2` namespace. The +primary breaking change from the point of the API server and client is that the `/version` endpoint now returns the +version of AICA Core, rather than the specific version of the API server subpackage inside core. These have historically +carried the same major version, but in future the core version may have major updates without any breaking changes to +the actual API server version. + +AICA Core versions `v4.3` and later introduce authentication and access scopes to the API server. An API key with +appropriate scopes is required to access the respective endpoints and functionalities. ### Checking compatibility diff --git a/python/pyproject.toml b/python/pyproject.toml index 809b374..a89ea34 100644 --- a/python/pyproject.toml +++ b/python/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "hatchling.build" [project] name = "aica_api" -version = "3.0.0" +version = "3.1.0" authors = [{ name = "Enrico Eberhard", email = "enrico@aica.tech" }] description = "A client utility for the AICA API" readme = "README.md"