Adjustments for initial 7.0 release

.readthedocs.yaml

@@ -10,6 +10,5 @@ build:
     python: "3.11"
   commands:
   - pip install --upgrade pip
-  - pip install -r requirements.txt
-  - pip install -r docs-requirements.txt
-  - sphinx-build -b html docs _readthedocs/html/
+  - pip install uv
+  - uv run sphinx-build -b html docs _readthedocs/html/

CONTRIBUTING.md

@@ -34,6 +34,21 @@ And then uninstall using pip: -
 
     pip uninstall im-squonk2-client -y
 
+With a suitable Squonk installation you should be able to run the basic test module,
+which exercises a number of API methods. You will need to define a number of variables,
+but one done the test is expected to work: -
+
+    export SQUONK2_DMAPI_URL=https://data-manager-test.example.com/data-manager-api
+    export SQUONK2_KEYCLOAK_URL=https://keycloak-test.example.com/auth
+    export SQUONK2_KEYCLOAK_REALM=squonk
+    export SQUONK2_KEYCLOAK_DM_CLIENT_ID=data-manager-api-test
+    export SQUONK2_KEYCLOAK_USER=dmit-user-admin
+    export SQUONK2_KEYCLOAK_USER_PASSWORD=password1234
+
+    uv run test.py
+
+Feel free to extend the test module as you add API methods.
+
 ---
 
 [ruff]: https://docs.astral.sh/ruff

README.rst

@@ -23,6 +23,25 @@ Data Manager, Account Server and UI REST interfaces. The functions provide
 access to some of the key API methods, implemented initially to support
 execution of Jobs from a Fragalysis stack `backend`_.
 
+API compatibility matrix
+------------------------
+The following table displays recent Python Client releases and the corresponding
+Squonk2 component API versions (Account Server, Data Manager, User Interface)
+that are compatible with them, starting with client ``6.x``.
+
+======  ======  ======  ======  =========
+Client  AS      DM      UI      Supported
+======  ======  ======  ======  =========
+7.x     4.x     5.x     6.x     ✅
+6.x     4.x     4.x     6.x     ✖️
+======  ======  ======  ======  =========
+
+As an example, the above table illustrates th§at full compatibility with DM ``5.x``
+will require client version ``7``. Client version ``6``, although it remains published,
+is no longer supported.
+
+The Python client is only supported for component installation versions we manage.
+
 Simplified Authentication
 =========================
 The following Squonk2 Authentication functions are available: -
@@ -38,45 +57,69 @@ The following Squonk2 Data Manager API functions are available: -
 
 - ``DmApi.ping()``
 
+- ``DmApi.acknowledge_service_error()``
 - ``DmApi.add_project_editor()``
 - ``DmApi.add_project_observer()``
+- ``DmApi.apply_workflow_version()``
 - ``DmApi.create_project()``
+- ``DmApi.create_project_path()``
+- ``DmApi.create_workflow()``
 - ``DmApi.delete_instance()``
 - ``DmApi.delete_instance_token()``
 - ``DmApi.delete_project()``
+- ``DmApi.delete_project_path()``
+- ``DmApi.delete_service_error()``
 - ``DmApi.delete_unmanaged_project_files()``
+- ``DmApi.delete_workflow()``
+- ``DmApi.delete_running_workflow()``
 - ``DmApi.dry_run_job_instance()``
 - ``DmApi.get_account_server_namespace()``
 - ``DmApi.get_account_server_registration()``
+- ``DmApi.get_application()``
+- ``DmApi.get_applications()``
 - ``DmApi.get_available_instances()``
 - ``DmApi.get_available_datasets()``
 - ``DmApi.get_available_jobs()``
 - ``DmApi.get_available_projects()``
 - ``DmApi.get_available_tasks()``
+- ``DmApi.get_dataset_for_digest()``
 - ``DmApi.get_job()``
 - ``DmApi.get_job_definition_schema_version()``
+- ``DmApi.get_job_exchange_rate()``
 - ``DmApi.get_job_exchange_rates()``
 - ``DmApi.get_job_by_version()``
 - ``DmApi.get_input_handler()``
 - ``DmApi.get_instance()``
 - ``DmApi.get_mode()``
 - ``DmApi.get_project()``
 - ``DmApi.get_project_instances()``
+- ``DmApi.get_running_workflow()``
+- ``DmApi.get_running_workflows()``
+- ``DmApi.get_running_workflow_steps()``
 - ``DmApi.get_service_errors()``
 - ``DmApi.get_task()``
 - ``DmApi.get_tasks()``
 - ``DmApi.get_unmanaged_project_file()``
 - ``DmApi.get_unmanaged_project_file_with_token()``
+- ``DmApi.get_user_inventory()``
 - ``DmApi.get_version()``
+- ``DmApi.get_workflows()``
+- ``DmApi.get_workflow()``
+- ``DmApi.get_workflow_definition()``
 - ``DmApi.get_workflow_engine_version()``
 - ``DmApi.list_project_files()``
+- ``DmApi.move_project_path()``
 - ``DmApi.put_unmanaged_project_files()``
 - ``DmApi.put_job_manifest()``
 - ``DmApi.remove_project_editor()``
 - ``DmApi.remove_project_observer()``
+- ``DmApi.run_workflow()``
 - ``DmApi.set_admin_state()``
 - ``DmApi.set_job_exchange_rates()``
 - ``DmApi.start_job_instance()``
+- ``DmApi.stop_running_workflow()``
+- ``DmApi.update_project()``
+- ``DmApi.update_workflow()``
 
 A ``dataclass`` defined in ``api`` is used as the return value for many of the methods: -
 
@@ -197,7 +240,7 @@ e.g. ``export SQUONK2_ENVIRONMENTS_FILE=~/my-env'``
 
     ---
 
-    # An example Squeck environments file.
+    # An example environments file.
     #
     # It provides all the connection details for one or more Squonk2 environments.
     # It is expected to be found in the user's home directory

examples/test-workflow.yaml

@@ -0,0 +1,12 @@
+---
+kind: DataManagerWorkflow
+kind-version: "2025.2"
+name: python-client-example
+description: >-
+  The simplest of workflow files used by the test framework in our Python client.
+steps:
+- name: coin
+  specification:
+    collection: im-test
+    job: coin-test
+    version: "1.0.0"

pyproject.toml

@@ -30,24 +30,26 @@ maintainers = [
 requires-python = ">=3.11"
 dependencies = [
   "authlib>=1.0.1,<2.0",
-  "munch>=4.0.0,<5.0",
-  "pyyaml>=5.2,<7.0",
-  "requests>=2.22.0",
-  "wrapt>=1.14.1,< 2.0",
+  "munch>=4.0.0,<5",
+  "pyyaml>=5.2,<7",
+  "requests>=2.22.0,<3",
+  "wrapt>=2.0.0,<3",
 ]
 
 [project.urls]
 Repository = "https://github.com/InformaticsMatters/squonk2-python-client.git"
 
 [dependency-groups]
 dev = [
+    "packaging>=26.0",
     "pre-commit>=4.5.1",
     "pyroma>=5.0.1",
     "ruff>=0.15.6",
     "sphinx>=9.0.4",
     "sphinx-rtd-theme>=3.1.0",
     "sphinx-toolbox>=4.1.2",
     "ty>=0.0.23",
+    "typer>=0.24.1",
 ]
 
 [tool.ruff]

src/squonk2/as_api.py

@@ -10,7 +10,6 @@
 
 import contextlib
 from datetime import date
-from enum import Enum
 import logging
 import os
 from pathlib import Path
@@ -24,32 +23,7 @@
 import requests
 
 from .api import ApiRv
-
-
-class EventStreamFormat(Enum):
-    """Enumeration of EventStream formats"""
-
-    JSON_STRING = 1
-    PROTOCOL_STRING = 2
-
-
-class AssetScopeEnum(Enum):
-    """Enumeration of Asset scopes"""
-
-    USER = 1
-    PRODUCT = 2
-    UNIT = 3
-    ORGANISATION = 4
-    GLOBAL = 5
-
-
-class DefaultProductPrivacyEnum(Enum):
-    """Enumeration of Default product Privacy"""
-
-    ALWAYS_PRIVATE = 1
-    ALWAYS_PUBLIC = 2
-    DEFAULT_PRIVATE = 3
-    DEFAULT_PUBLIC = 4
+from .enumerations import DefaultProductPrivacyEnum, EventStreamFormat, ScopeEnum
 
 
 # The Account Server API URL environment variable,
@@ -455,7 +429,7 @@ def create_asset(
         *,
         name: str,
         description: str,
-        scope: AssetScopeEnum,
+        scope: ScopeEnum,
         content_string: Optional[str] = None,
         content_file: Optional[Path] = None,
         scope_id: Optional[str] = None,