release(client): v3.1.0 (#213)

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
 

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
 

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 = "[email protected]" }]
 description = "A client utility for the AICA API"
 readme = "README.md"