Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: update python api client #193

Open
wants to merge 12 commits into
base: main
Choose a base branch
from
15 changes: 15 additions & 0 deletions python/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@

Release Versions:

- [3.0.0](#300)
- [2.1.0](#210)
- [2.0.0](#200)
- [1.2.1](#121)
Expand All @@ -11,6 +12,20 @@ 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. It supports additional methods to
query the Core, API server and protocol versions and the sub-versions of installed packages through license metadata.

This release removes the previously deprecated method `wait_for_predicate` which has been replaced by the specific
`wait_for_component_predicate` or `wait_for_controller_predicate` methods.

Similarly, it marks the `call_service` method as deprecated in this version and introduces the `call_component_service`
and `call_controller_service` methods as preferred alternatives.

This release also introduces two new methods to manage sequences: `manage_sequence` to start, restart or abort a named
sequence and `wait_for_sequence` to wait until a sequence is inactive, active or aborted.

## 2.1.0

- Support hardware and controller states and predicates in `wait_for` functions (#156)
Expand Down
88 changes: 63 additions & 25 deletions python/README.md
Original file line number Diff line number Diff line change
@@ -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()
Expand All @@ -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()
Expand All @@ -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())
```
2 changes: 1 addition & 1 deletion python/pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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]" },
]
Expand Down
Loading