feat: update python api client

python/CHANGELOG.md

@@ -2,6 +2,7 @@
 
 Release Versions:
 
+- [3.1.0](#300)
 - [2.1.0](#210)
 - [2.0.0](#200)
 - [1.2.1](#121)
@@ -11,6 +12,10 @@ Release Versions:
 - [1.0.1](#101)
 - [1.0.0](#100)
 
+## 3.0.0
+
+Version 3.0.0 of the AICA API client is compatible with the new AICA Core version 4.0.
+
 ## 2.1.0
 
 - Support hardware and controller states and predicates in `wait_for` functions (#156)

python/README.md

@@ -1,14 +1,14 @@
 # Python AICA API Client
 
-The AICA API client module provides simple functions for interacting with the AICA API.
+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:
 
-```python
+```python3
 from aica_api.client import AICA
 
 aica = AICA()
@@ -22,9 +22,9 @@ aica.unload_component('my_component')
 aica.stop_application()
 ```
 
-To check the status of component predicates and conditions, the following blocking methods can be employed:
+To check the status of predicates and conditions, the following blocking methods can be employed:
 
-```python
+```python3
 from aica_api.client import AICA
 
 aica = AICA()
@@ -34,45 +34,83 @@ if aica.wait_for_condition('timer_1_active', timeout=10.0):
 else:
     print('Timed out before condition was true')
 
-if aica.wait_for_predicate('timer_1', 'is_timed_out', timeout=10.0):
+if aica.wait_for_component_predicate('timer_1', 'is_timed_out', timeout=10.0):
     print('Predicate is true!')
 else:
     print('Timed out before predicate was true')
 ```
 
 ## Compatability table
 
-The latest version of the AICA API client will generally support the latest API server version in the AICA framework.
-Major changes to the API client or server versions indicate breaking changes and are not backwards compatible. To
-interact with older versions of the AICA framework, it may be necessary to install older versions of the client.
+The latest version of this AICA API client will generally support the latest AICA Core version.
+Major version changes to the API client or to AICA Core indicate breaking changes and are not always backwards
+compatible. To interact with older versions of AICA Core, it may be necessary to install older versions of the client.
 Use the following compatability table to determine which client version to use.
 
-| API server version | Matching Python client version  |
-|--------------------|---------------------------------|
-| `3.x`              | `>= 2.0.0`                      |
-| `2.x`              | `1.2.0`                         |
-| `<= 1.x`           | Unsupported                     |
+| AICA Core version | API protocol version | Matching Python client version |
+|-------------------|----------------------|--------------------------------|
+| `4.x`             | `v2`                 | `>= 3.0.0`                     |
+| `3.x`             | `v2`                 | `>= 2.0.0`                     |
+| `2.x`             | `v2`                 | `1.2.0`                        |
+| `<= 1.x`          | `v1`                 | Unsupported                    |
 
-Between major version changes, minor updates to the API server version and Python client versions may introduce new
-endpoints and functions respectively. If a function requires a feature that the detected API server version does not yet
-support (as is the case when the Python client version is more up-to-date than the targeted API server), then calling
+The API protocol version is a namespace for the endpoints. Endpoints under the `v2` protocol have a `/v2/...` prefix in
+the URL. A change to the protocol version indicates a fundamental change to the API structure or behavior.
+
+Between major version changes, minor updates to the AICA Core version and Python client versions may introduce new
+endpoints and functions respectively. If a function requires a feature that the detected AICA Core version does not yet
+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.
 
-Recent client versions also support the following functions to check the client version and API compatability.
+### Changes between major server versions
+
+AICA Core versions `v1.x` and earlier were alpha and pre-alpha versions that are no longer supported.
+
+AICA Core version `v2.x` was a beta version that introduced a new API structure under the `v2` protocol namespace.
+
+In AICA Core `v3.x`, live data streaming for predicates and conditions switched from using raw websockets to Socket.IO
+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.
+
+### Checking compatibility
 
-```python
+Recent client versions include a `check()` method to assess the client version and API compatability.
+
+```python3
 from aica_api.client import AICA
 
 aica = AICA()
 
-# get the current API server version
-print(aica.api_version())
-# get the current client version
-print(aica.client_version())
-
 # check compatability between the client version and API version
 if aica.check():
-    print('Versions are compatible')
+    print('Client and server versions are compatible')
 else:
-    print('Versions are incompatible')
+    print('Client and server versions are incompatible')
+```
+
+The latest client versions also include the following functions to check the configuration details manually.
+
+```python3
+from aica_api.client import AICA
+
+aica = AICA()
+
+# get the current version of this client
+print(aica.client_version())
+
+# get the current version of AICA Core (e.g. "4.0.0")
+print(aica.core_version())
+
+# get the current API protocol version (e.g. "v2")
+print(aica.protocol())
+
+# get the specific version of the API server running in AICA Core (e.g. "4.0.1")
+# (generally only needed for debugging purposes)
+print(aica.api_version())
 ```

python/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "aica_api"
-version = "2.1.0"
+version = "3.0.0"
 authors = [
   { name="Enrico Eberhard", email="[email protected]" },
 ]