Merge branch 'dev' into feature/pagination

Author: kzscisoft

.pre-commit-config.yaml

@@ -23,7 +23,7 @@ repos:
         args: [--branch, main, --branch, dev]
       - id: check-added-large-files
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.9.9
+    rev: v0.11.2
     hooks:
       - id: ruff
         args: [ --fix, --exit-non-zero-on-fix, "--ignore=C901" ]

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Change log
 
+## Unreleased
+* Added sorting to server queries, users can now specify to sort by columns during data retrieval from the database.
+## [v2.0.1](https://github.com/simvue-io/client/releases/tag/v2.0.1) - 2025-03-24
+* Improvements to docstrings on methods, classes and functions.
 ## [v2.0.0](https://github.com/simvue-io/client/releases/tag/v2.0.0) - 2025-03-07
 * Add new example notebooks
 * Update and refactor examples to work with v2.0
@@ -51,28 +55,28 @@
 * Adds additional functionality and support for offline mode.
 * Support for Simvue servers `>=3`.
 
-## [v1.1.4](https://github.com/simvue-io/client/releases/tag/v1.1.4) - 2024-12-11
+## [v1.1.4](https://github.com/simvue-io/python-api/releases/tag/v1.1.4) - 2024-12-11
 
 * Remove incorrect identifier reference for latest Simvue servers during reconnection.
 * Fixed missing online mode selection when retrieving configuration for `Client` class.
 
-## [v1.1.3](https://github.com/simvue-io/client/releases/tag/v1.1.3) - 2024-12-09
+## [v1.1.3](https://github.com/simvue-io/python-api/releases/tag/v1.1.3) - 2024-12-09
 
 * Fixed bug with `requirements.txt` metadata read.
 * Added Simvue server version check.
 * Remove checking of server version in offline mode and add default run mode to configuration options.
 * Fix offline mode class initialisation, and propagation of configuration.
 
-## [v1.1.2](https://github.com/simvue-io/client/releases/tag/v1.1.2) - 2024-11-06
+## [v1.1.2](https://github.com/simvue-io/python-api/releases/tag/v1.1.2) - 2024-11-06
 
 * Fix bug in offline mode directory retrieval.
 
-## [v1.1.1](https://github.com/simvue-io/client/releases/tag/v1.1.1) - 2024-10-22
+## [v1.1.1](https://github.com/simvue-io/python-api/releases/tag/v1.1.1) - 2024-10-22
 
 * Add missing `offline.cache` key to TOML config.
 * Fix repetition of server URL validation for each call to configuration.
 
-## [v1.1.0](https://github.com/simvue-io/client/releases/tag/v1.1.0) - 2024-10-21
+## [v1.1.0](https://github.com/simvue-io/python-api/releases/tag/v1.1.0) - 2024-10-21
 
 * Add option to specify a callback executed when an alert is triggered for a run.
 * Allow retrieval of all alerts when no constraints are specified.
@@ -83,35 +87,35 @@
 * Indicate the source used for token and URL.
 * Migrate to `simvue.toml` from `simvue.ini`, allowing more defaults to be set during runs.
 
-## [v1.0.6](https://github.com/simvue-io/client/releases/tag/v1.0.6) - 2024-10-10
+## [v1.0.6](https://github.com/simvue-io/python-api/releases/tag/v1.0.6) - 2024-10-10
 
 * Fix incorrect usage of `retry` when attempting connections to the server.
 
-## [v1.0.5](https://github.com/simvue-io/client/releases/tag/v1.0.5) - 2024-10-09
+## [v1.0.5](https://github.com/simvue-io/python-api/releases/tag/v1.0.5) - 2024-10-09
 
 * Ensure all functionality is deactivated when mode is set to `disabled`.
 * When an exception is thrown an event is sent to Simvue displaying the traceback.
 * If `add_process` is used and an exception is thrown, `.err` and `.out` files are still uploaded.
 
-## [v1.0.4](https://github.com/simvue-io/client/releases/tag/v1.0.4) - 2024-09-24
+## [v1.0.4](https://github.com/simvue-io/python-api/releases/tag/v1.0.4) - 2024-09-24
 
 * Set resource metrics to be recorded by default.
 
-## [v1.0.3](https://github.com/simvue-io/client/releases/tag/v1.0.3) - 2024-09-23
+## [v1.0.3](https://github.com/simvue-io/python-api/releases/tag/v1.0.3) - 2024-09-23
 
 * Fix issue of hanging threads when exception raised by script using the API.
 
-## [v1.0.2](https://github.com/simvue-io/client/releases/tag/v1.0.2) - 2024-08-21
+## [v1.0.2](https://github.com/simvue-io/python-api/releases/tag/v1.0.2) - 2024-08-21
 
 * Fix incorrect HTTP status code in `Client` when checking if object exists.
 * Fix issue with `running=False` when launching a `Run` caused by incorrect system metadata being sent to the server.
 
-## [v1.0.1](https://github.com/simvue-io/client/releases/tag/v1.0.1) - 2024-07-16
+## [v1.0.1](https://github.com/simvue-io/python-api/releases/tag/v1.0.1) - 2024-07-16
 
 * Fix to `add_process` with list of strings as arguments, the executable no longer returns the string `"None"`.
 * Fix callbacks and triggers for `add_process` being executed only on `Run` class termination, not on process completion.
 
-## [v1.0.0](https://github.com/simvue-io/client/releases/tag/v1.0.0) - 2024-06-14
+## [v1.0.0](https://github.com/simvue-io/python-api/releases/tag/v1.0.0) - 2024-06-14
 
 * Refactor and re-write of codebase to align with latest developments in version 2 of the Simvue server.
 * Added `Executor` to Simvue runs allowing users to start shell based processes as part of a run and handle termination of these.
@@ -121,119 +125,119 @@
 * Fixed issue whereby metrics would still have to wait for the next iteration of dispatch before being sent to the server, even if the queue was not full.
 * Added support for `'user'` alerts.
 
-## [v0.14.3](https://github.com/simvue-io/client/releases/tag/v0.14.3) - 2023-06-29
+## [v0.14.3](https://github.com/simvue-io/python-api/releases/tag/v0.14.3) - 2023-06-29
 
 * Ensure import of the `requests` module is only done if actually used.
 
-## [v0.14.0](https://github.com/simvue-io/client/releases/tag/v0.14.0) - 2023-04-04
+## [v0.14.0](https://github.com/simvue-io/python-api/releases/tag/v0.14.0) - 2023-04-04
 
 * Added a method to the `Client` class for retrieving events.
 
-## [v0.13.3](https://github.com/simvue-io/client/releases/tag/v0.13.3) - 2023-04-04
+## [v0.13.3](https://github.com/simvue-io/python-api/releases/tag/v0.13.3) - 2023-04-04
 
 * Allow files (`input` and `code` only) to be saved for runs in the `created` state.
 * Allow metadata and tags to be updated for runs in the `created` state.
 
-## [v0.13.2](https://github.com/simvue-io/client/releases/tag/v0.13.2) - 2023-04-04
+## [v0.13.2](https://github.com/simvue-io/python-api/releases/tag/v0.13.2) - 2023-04-04
 
 * Added `plot_metrics` method to the `Client` class to simplify plotting metrics.
 * (Bug fix) `reconnect` works without a uuid being specified when `offline` mode isn't being used.
 * (Bug fix) Restrict version of Pydantic to prevent v2 from accidentally being used.
 
-## [v0.13.1](https://github.com/simvue-io/client/releases/tag/v0.13.1) - 2023-03-28
+## [v0.13.1](https://github.com/simvue-io/python-api/releases/tag/v0.13.1) - 2023-03-28
 
 * Set `sample_by` to 0 by default (no sampling) in `get_metrics_multiple`.
 
-## [v0.13.0](https://github.com/simvue-io/client/releases/tag/v0.13.0) - 2023-03-28
+## [v0.13.0](https://github.com/simvue-io/python-api/releases/tag/v0.13.0) - 2023-03-28
 
 * Added methods to the `Client` class for retrieving metrics.
 * CPU architecture and processor obtained on Apple hardware.
 * Client now reports to server when files have been successfully uploaded.
 * `User-Agent` header now included in HTTP requests.
 
-## [v0.12.0](https://github.com/simvue-io/client/releases/tag/v0.12.0) - 2023-03-13
+## [v0.12.0](https://github.com/simvue-io/python-api/releases/tag/v0.12.0) - 2023-03-13
 
 * Add methods to the `Client` class for deleting runs and folders.
 * Confusing messages about `process no longer exists` or `NVML Shared Library Not Found` no longer displayed.
 
-## [v0.11.4](https://github.com/simvue-io/client/releases/tag/v0.11.4) - 2023-03-13
+## [v0.11.4](https://github.com/simvue-io/python-api/releases/tag/v0.11.4) - 2023-03-13
 
 * (Bug fix) Ensure `simvue_sender` can be run when installed from PyPI.
 * (Bug fix) Runs created in `offline` mode using a context manager weren't automatically closed.
 
-## [v0.11.3](https://github.com/simvue-io/client/releases/tag/v0.11.3) - 2023-03-07
+## [v0.11.3](https://github.com/simvue-io/python-api/releases/tag/v0.11.3) - 2023-03-07
 
 * Added logging messages for debugging when debug level set to `debug`.
 
-## [v0.11.2](https://github.com/simvue-io/client/releases/tag/v0.11.2) - 2023-03-06
+## [v0.11.2](https://github.com/simvue-io/python-api/releases/tag/v0.11.2) - 2023-03-06
 
 * Raise exceptions in `Client` class methods if run does not exist or artifact does not exist.
 * (Bug fix) `list_artifacts` optional category restriction now works.
 
-## [v0.11.1](https://github.com/simvue-io/client/releases/tag/v0.11.1) - 2023-03-05
+## [v0.11.1](https://github.com/simvue-io/python-api/releases/tag/v0.11.1) - 2023-03-05
 
 * Support different runs having different metadata in `get_runs` dataframe output.
 * (Bug fix) Error message when creating a duplicate run is now more clear.
 * (Bug fix) Correction to stopping the worker thread in situations where the run never started.
 
-## [v0.11.0](https://github.com/simvue-io/client/releases/tag/v0.11.0) - 2023-03-04
+## [v0.11.0](https://github.com/simvue-io/python-api/releases/tag/v0.11.0) - 2023-03-04
 
 * Support optional dataframe output from `get_runs`.
 
-## [v0.10.1](https://github.com/simvue-io/client/releases/tag/v0.10.1) - 2023-03-03
+## [v0.10.1](https://github.com/simvue-io/python-api/releases/tag/v0.10.1) - 2023-03-03
 
 * The worker process now no longer gives a long delay when a run has finished (now at most ~1 second).
 * The worker process ends when the `Run()` context ends or `close` is called, rather than only when the main process exits.
 
-## [v0.10.0](https://github.com/simvue-io/client/releases/tag/v0.10.0) - 2023-02-07
+## [v0.10.0](https://github.com/simvue-io/python-api/releases/tag/v0.10.0) - 2023-02-07
 
 * The `client` class can now be used to retrieve runs.
 
-## [v0.9.1](https://github.com/simvue-io/client/releases/tag/v0.9.1) - 2023-01-25
+## [v0.9.1](https://github.com/simvue-io/python-api/releases/tag/v0.9.1) - 2023-01-25
 
 * (Bug fix) Retries in POST/PUTs to REST APIs didn't happen.
 * Warn users if `allow_pickle=True` is required.
 
-## [v0.9.0](https://github.com/simvue-io/client/releases/tag/v0.9.0) - 2023-01-25
+## [v0.9.0](https://github.com/simvue-io/python-api/releases/tag/v0.9.0) - 2023-01-25
 
 * Set status to `failed` or `terminated` if the context manager is used and there is an exception.
 
-## [v0.8.0](https://github.com/simvue-io/client/releases/tag/v0.8.0) - 2023-01-23
+## [v0.8.0](https://github.com/simvue-io/python-api/releases/tag/v0.8.0) - 2023-01-23
 
 * Support NumPy arrays, PyTorch tensors, Matplotlib and Plotly plots and picklable Python objects as artifacts.
 * (Bug fix) Events in offline mode didn't work.
 
-## [v0.7.2](https://github.com/simvue-io/client/releases/tag/v0.7.2) - 2023-01-08
+## [v0.7.2](https://github.com/simvue-io/python-api/releases/tag/v0.7.2) - 2023-01-08
 
 * Pydantic model is used for input validation.
 * Support NaN, -inf and inf in metadata and metrics.
 
-## [v0.7.0](https://github.com/simvue-io/client/releases/tag/v0.7.0) - 2022-12-05
+## [v0.7.0](https://github.com/simvue-io/python-api/releases/tag/v0.7.0) - 2022-12-05
 
 * Collect CPU, GPU and memory resource metrics.
 * Automatically delete temporary files used in offline mode once runs have entered a terminal state.
 * Warn users if their access token has expired.
 * Remove dependency on the randomname module, instead handle name generation server side.
 
-## [v0.6.0](https://github.com/simvue-io/client/releases/tag/v0.6.0) - 2022-11-07
+## [v0.6.0](https://github.com/simvue-io/python-api/releases/tag/v0.6.0) - 2022-11-07
 
 * `offline` and `disabled` options replaced with single `mode` flag.
 
-## [v0.5.0](https://github.com/simvue-io/client/releases/tag/v0.5.0) - 2022-11-03
+## [v0.5.0](https://github.com/simvue-io/python-api/releases/tag/v0.5.0) - 2022-11-03
 
 * Added option to disable all monitoring.
 
-## [v0.4.0](https://github.com/simvue-io/client/releases/tag/v0.4.0) - 2022-11-03
+## [v0.4.0](https://github.com/simvue-io/python-api/releases/tag/v0.4.0) - 2022-11-03
 
 * Offline mode added, enabling tracking of simulations running on worker nodes without outgoing network access.
 * Argument to `init` enabling runs to be left in the `created` state changed from `status="created"` to `running=True`.
 * Improvements to error handling.
 
-## [v0.3.0](https://github.com/simvue-io/client/releases/tag/v0.3.0) - 2022-10-31
+## [v0.3.0](https://github.com/simvue-io/python-api/releases/tag/v0.3.0) - 2022-10-31
 
 * Update `add_alert` method to support either metrics or events based alerts.
 
-## [v0.2.0](https://github.com/simvue-io/client/releases/tag/v0.2.0) - 2022-10-26
+## [v0.2.0](https://github.com/simvue-io/python-api/releases/tag/v0.2.0) - 2022-10-26
 
 * The previous `Simvue` class has been split into `Run` and `Client`. When creating a run use the new `Run` class rather than `Simvue`.
 

CITATION.cff

@@ -42,9 +42,9 @@ keywords:
   - alerting
   - simulation
 license: Apache-2.0
-commit: 88bdd861e01153a2853191c0a8d1bb64dfabe296
-version: 2.0.0
-date-released: '2025-03-07'
+commit: 5084f9c17ae4b7f77e188f5aa8a51ebd3f790c9e
+version: 2.0.1
+date-released: '2025-03-24'
 references:
 - title: mlco2/codecarbon
   version: v2.8.2

notebooks/non_python_example.ipynb

@@ -34,7 +34,7 @@
    "metadata": {},
    "source": [
     "### Install dependencies\n",
-    "While you can use Simvue and Multiparser individually to achieve the tracking and monitoring of Non-Python files, we recommend using the `simvue-integrations` package which wraps these both together into a handy `WrappedRun` class. Install this if you have not done so already:"
+    "While you can use Simvue and Multiparser individually to achieve the tracking and monitoring of Non-Python files, we recommend using the `simvue-connector` package which wraps these both together into a handy `WrappedRun` class. Install this if you have not done so already:"
    ]
   },
   {
@@ -43,7 +43,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "!pip install git+https://github.com/simvue-io/integrations.git"
+    "!pip install simvue-connector"
    ]
   },
   {
@@ -94,7 +94,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from simvue_integrations.connectors.generic import WrappedRun\n",
+    "from simvue_connector.connector import WrappedRun\n",
     "import multiparser.parsing.tail as mp_tail_parser\n",
     "import time\n",
     "import pathlib\n",

simvue/api/objects/alert/base.py

@@ -8,11 +8,12 @@
 
 import http
 import pydantic
+import datetime
 import typing
 from simvue.api.objects.base import SimvueObject, staging_check, write_only
 from simvue.api.request import get as sv_get, get_json_from_response
 from simvue.api.url import URL
-from simvue.models import NAME_REGEX
+from simvue.models import NAME_REGEX, DATETIME_FORMAT
 
 
 class AlertBase(SimvueObject):
@@ -125,6 +126,20 @@ def abort(self) -> bool:
         """Retrieve if alert can abort simulations"""
         return self._get_attribute("abort")
 
+    @property
+    @staging_check
+    def delay(self) -> int:
+        """Retrieve delay value for this alert"""
+        return self._get_attribute("delay")
+
+    @property
+    def created(self) -> datetime.datetime | None:
+        """Retrieve created datetime for the alert"""
+        _created: str | None = self._get_attribute("created")
+        return (
+            datetime.datetime.strptime(_created, DATETIME_FORMAT) if _created else None
+        )
+
     @abort.setter
     @write_only
     @pydantic.validate_call

simvue/api/objects/alert/fetch.py

@@ -8,10 +8,12 @@
 
 import typing
 import http
+import json
 
 import pydantic
 
 from simvue.api.objects.alert.user import UserAlert
+from simvue.api.objects.base import Sort
 from simvue.api.request import get_json_from_response
 from simvue.api.request import get as sv_get
 from .events import EventsAlert
@@ -21,6 +23,15 @@
 AlertType = EventsAlert | UserAlert | MetricsThresholdAlert | MetricsRangeAlert
 
 
+class AlertSort(Sort):
+    @pydantic.field_validator("column")
+    @classmethod
+    def check_column(cls, column: str) -> str:
+        if column and column not in ("name", "created"):
+            raise ValueError(f"Invalid sort column for alerts '{column}'")
+        return column
+
+
 class Alert:
     """Generic Simvue alert retrieval class"""
 
@@ -50,11 +61,13 @@ def __new__(cls, identifier: str, **kwargs) -> AlertType:
         raise RuntimeError(f"Unknown source type '{_alert_pre.source}'")
 
     @classmethod
+    @pydantic.validate_call
     def get(
         cls,
         offline: bool = False,
         count: int | None = None,
         offset: int | None = None,
+        sorting: list[AlertSort] | None = None,
         **kwargs,
     ) -> typing.Generator[tuple[str, AlertType], None, None]:
         """Fetch all alerts from the server for the current user.
@@ -65,6 +78,8 @@ def get(
             limit the number of results, default of None returns all.
         offset : int, optional
             start index for returned results, default of None starts at 0.
+        sorting : list[dict] | None, optional
+            list of sorting definitions in the form {'column': str, 'descending': bool}
 
         Yields
         ------
@@ -80,11 +95,15 @@ def get(
 
         _class_instance = AlertBase(_local=True, _read_only=True)
         _url = f"{_class_instance._base_url}"
+        _params: dict[str, int | str] = {"start": offset, "count": count}
+
+        if sorting:
+            _params["sorting"] = json.dumps([sort.to_params() for sort in sorting])
 
         _response = sv_get(
             _url,
             headers=_class_instance._headers,
-            params={"start": offset, "count": count} | kwargs,
+            params=_params | kwargs,
         )
 
         _label: str = _class_instance.__class__.__name__.lower()