Merge pull request #663 from simvue-io/feature/api-repro

Introduction of Lower Level API and Support for Simvue Server v3

Author: kzscisoft

.gitignore

@@ -147,3 +147,5 @@ offline/
 
 # Vagrant
 Vagrantfile
+
+.sourcery*

CHANGELOG.md

@@ -5,6 +5,10 @@
 * Add support for defining Simvue run defaults using `tool.simvue` in a project `pyproject.toml` file.
 * Drop support for INI based configuration files.
 * Retrieve all metric values if `max_points` is unspecified or set to `None`.
+* Add support for PyTorch in Python 3.13
+* Create lower level API for directly interacting with the Simvue RestAPI endpoints.
+* **Removes support for Python <3.10 due to dependency constraints.**
+* Separates `create_alert` into specific methods `create_event_alert` etc.
 ## [v1.1.4](https://github.com/simvue-io/client/releases/tag/v1.1.4) - 2024-12-11
 
 * Remove incorrect identifier reference for latest Simvue servers during reconnection.

README.md

@@ -76,14 +76,15 @@ if __name__ == "__main__":
         run.save_file('params.in', 'input')
 
         # Add an alert (the alert definition will be created if necessary)
-        run.create_alert(name='loss-too-high',   # Name
-                      source='metrics',       # Source
-                      rule='is above',        # Rule
-                      metric='loss',          # Metric
-                      frequency=1,            # Frequency
-                      window=1,               # Window
-                      threshold=10,           # Threshold
-                      notification='email')   # Notification type
+        run.create_metric_threshold_alert(
+              name='loss-too-high',   # Name
+              rule='is above',        # Rule
+              metric='loss',          # Metric
+              frequency=1,            # Frequency
+              window=1,               # Window
+              threshold=10,           # Threshold
+              notification='email'   # Notification type
+        )
 
         ...
 

examples/Geant4/geant4_simvue.py

@@ -27,7 +27,7 @@
 @click.option("--momentum", type=float, default=10)
 @click.option("--events", type=int, default=100)
 def geant4_simvue_example(
-    g4_binary: str, config: typing.Optional[str], ci: bool, momentum: float, events: int
+    g4_binary: str, config: str | None, ci: bool, momentum: float, events: int
 ) -> None:
     @mp_file_parse.file_parser
     def root_file_parser(

poetry.lock

@@ -1,13 +1,13 @@
-[tool.poetry]
+[project]
 name = "simvue"
-version = "1.1.4"
+version = "2.0.0a0"
 description = "Simulation tracking and monitoring"
-authors = ["Simvue Development Team <info@simvue.io>"]
+authors = [
+  {name = "Simvue Development Team", email = "info@simvue.io"}
+]
 license = "Apache v2"
+requires-python = ">=3.10,<3.14"
 readme = "README.md"
-homepage = "https://simvue.io"
-repository = "https://github.com/simvue-io/python-api"
-documentation = "https://docs.simvue.io"
 classifiers = [
     "Development Status :: 5 - Production/Stable",
     "Intended Audience :: Science/Research",
@@ -33,34 +33,37 @@ keywords = [
     "alerting",
     "metrics-gathering"
 ]
+dependencies = [
+  "requests (>=2.32.3,<3.0.0)",
+  "pydantic (>=2.10.6,<3.0.0)",
+  "tabulate (>=0.9.0,<0.10.0)",
+  "msgpack (>=1.1.0,<2.0.0)",
+  "pyjwt (>=2.10.1,<3.0.0)",
+  "pandas (>=2.2.3,<3.0.0)",
+  "toml (>=0.10.2,<0.11.0)",
+  "click (>=8.1.8,<9.0.0)",
+  "gitpython (>=3.1.44,<4.0.0)",
+  "humanfriendly (>=10.0,<11.0)",
+  "randomname (>=0.2.1,<0.3.0)",
+  "codecarbon (>=2.8.3,<3.0.0)",
+  "numpy (>=2.2.2,<3.0.0)",
+  "flatdict (>=4.0.1,<5.0.0)",
+  "semver (>=3.0.4,<4.0.0)",
+  "email-validator (>=2.2.0,<3.0.0)",
+  "psutil (>=6.1.1,<7.0.0)",
+  "tenacity (>=9.0.0,<10.0.0)",
+  "typing-extensions (>=4.12.2,<5.0.0) ; python_version < \"3.11\"",
+]
 
-[tool.poetry.dependencies]
-python = "^3.10,<3.14"
-dill = "^0.3.7"
-requests = "^2.31.0"
-msgpack = "^1.0.7"
-tenacity = ">=8.2.3,<10.0.0"
-PyJWT = "^2.8.0"
-psutil = ">=5.9.8,<7.0.0"
-pydantic = "^2.5.3"
-pandas = "^2.2.0"
-plotly = {version = ">=5.18,<7.0", optional = true}
-matplotlib = {version = "^3.8.2", optional = true}
-typing_extensions = { version = "^4.11.0", python = "<3.10" }
-toml = "^0.10.2"
-click = "^8.1.7"
-gitpython = "^3.1.43"
-humanfriendly = "^10.0"
-tabulate = "^0.9.0"
-randomname = "^0.2.1"
-codecarbon = "^2.7.1"
-numpy = "^2.1.2"
-semver = "^3.0.2"
+[project.urls]
+homepage = "https://simvue.io"
+repository = "https://github.com/simvue-io/python-api"
+documentation = "https://docs.simvue.io"
 
-[tool.poetry.extras]
-plot = ["matplotlib", "plotly"]
+[project.optional-dependencies]
+plot = ["plotly (>=6.0.0,<7.0.0)", "matplotlib (>=3.10.0,<4.0.0)"]
 
-[tool.poetry.scripts]
+[project.scripts]
 simvue_sender = "simvue.bin.sender:run"
 
 [tool.poetry.group.dev.dependencies]
@@ -72,16 +75,13 @@ pytest-mock = "^3.14.0"
 pytest-sugar = "^1.0.0"
 pytest-xdist = "^3.6.1"
 jinja2 = "^3.1.4"
+types-requests = "^2.32.0.20241016"
+interrogate = "^1.7.0"
 
 [build-system]
 requires = ["poetry-core"]
 build-backend = "poetry.core.masonry.api"
 
-[[tool.poetry.source]]
-name = "PyPI"
-priority = "primary"
-
-
 [tool.ruff]
 lint.extend-select = ["C901", "T201"]
 lint.mccabe.max-complexity = 11
@@ -93,6 +93,7 @@ testpaths = [
     "tests"
 ]
 markers = [
+    "codecarbon: tests for emission metrics",
     "client: tests of Simvue client",
     "converters: tests for Simvue object converters",
     "dispatch: test data dispatcher",
@@ -104,11 +105,17 @@ markers = [
     "api: tests of RestAPI functionality",
     "unix: tests for UNIX systems only",
     "metadata: tests of metadata gathering functions",
-    "proxies: tests for remote/offline Simvue proxies"
+    "proxies: tests for remote/offline Simvue proxies",
+    "online: tests for online functionality",
+    "offline: tests for offline functionality",
+    "local: tests of functionality which do not involve a server or writing to an offline cache file"
 ]
 
 [tool.interrogate]
 ignore-init-method = true
 fail-under = 95
 verbose = 1
 exclude = ["docs", "tests"]
+
+[tool.mypy]
+ignore_missing_imports = true

pyproject.toml

@@ -0,0 +1,8 @@
+"""
+Simvue API
+==========
+
+Module contains methods for interacting with a Simvue server
+including accessing/updating objects.
+
+"""

simvue/api/__init__.py

@@ -0,0 +1,35 @@
+"""
+Simvue API Objects
+==================
+
+The following module defines objects which provide exact representations
+of information accessible via the Simvue RestAPI, this provides a lower
+level interface towards the development of additional tools/frameworks.
+
+"""
+
+from .administrator import Tenant as Tenant, User as User
+from .alert import (
+    Alert as Alert,
+    EventsAlert as EventsAlert,
+    MetricsThresholdAlert as MetricsThresholdAlert,
+    MetricsRangeAlert as MetricsRangeAlert,
+    UserAlert as UserAlert,
+)
+from .storage import (
+    S3Storage as S3Storage,
+    FileStorage as FileStorage,
+    Storage as Storage,
+)
+from .artifact import (
+    FileArtifact as FileArtifact,
+    ObjectArtifact as ObjectArtifact,
+    Artifact as Artifact,
+)
+
+from .stats import Stats as Stats
+from .run import Run as Run
+from .tag import Tag as Tag
+from .folder import Folder as Folder, get_folder_from_path as get_folder_from_path
+from .events import Events as Events
+from .metrics import Metrics as Metrics

simvue/api/objects/__init__.py

@@ -0,0 +1,16 @@
+"""
+Simvue Admin Objects
+====================
+
+These are Simvue objects only accessible to an administrator of
+the server.
+
+"""
+
+from .tenant import Tenant as Tenant
+from .user import User as User
+
+__all__ = [
+    "Tenant",
+    "User",
+]

simvue/api/objects/administrator/__init__.py

@@ -0,0 +1,131 @@
+"""
+Simvue Tenants
+==============
+
+Contains a class for remotely connecting to Simvue tenants, or defining
+a new tenant given relevant arguments.
+
+"""
+
+try:
+    from typing import Self
+except ImportError:
+    from typing_extensions import Self
+import pydantic
+
+from simvue.api.objects.base import write_only, SimvueObject, staging_check
+
+
+class Tenant(SimvueObject):
+    """Class for interacting with a tenant instance on the server."""
+
+    @classmethod
+    @pydantic.validate_call
+    def new(
+        cls,
+        *,
+        name: str,
+        is_enabled: bool = True,
+        max_request_rate: int = 0,
+        max_runs: int = 0,
+        max_data_volume: int = 0,
+        offline: bool = False,
+    ) -> Self:
+        """Create a new tenant on the Simvue server.
+
+        Requires administrator privileges.
+
+        Parameters
+        ----------
+        name: str
+            the name for this tenant
+        is_enabled: bool, optional
+            whether to enable the tenant on creation, default is True
+        max_request_rate: int, optional
+            the maximum request rate allowed for this tenant, default is no limit.
+        max_runs: int, optional
+            the maximum number of runs allowed within this tenant, default is no limit.
+        max_data_volume: int, optional
+            the maximum volume of data allowed within this tenant, default is no limit.
+        offline: bool, optional
+            create in offline mode, default is False.
+
+        Returns
+        -------
+        Tenant
+            a tenant instance with staged changes
+
+        """
+        return Tenant(
+            name=name,
+            is_enabled=is_enabled,
+            max_request_rate=max_request_rate,
+            max_runs=max_runs,
+            max_data_volume=max_data_volume,
+            _read_only=False,
+            _offline=offline,
+        )
+
+    @property
+    def name(self) -> str:
+        """Retrieve the name of the tenant"""
+        return self._get_attribute("name")
+
+    @name.setter
+    @write_only
+    @pydantic.validate_call
+    def name(self, name: str) -> None:
+        """Change name of tenant"""
+        self._staging["name"] = name
+
+    @property
+    @staging_check
+    def is_enabled(self) -> bool:
+        """Retrieve if tenant is enabled"""
+        return self._get_attribute("is_enabled")
+
+    @is_enabled.setter
+    @write_only
+    @pydantic.validate_call
+    def is_enabled(self, is_enabled: bool) -> None:
+        """Enable/disable tenant"""
+        self._staging["is_enabled"] = is_enabled
+
+    @property
+    @staging_check
+    def max_request_rate(self) -> int:
+        """Retrieve the tenant's maximum request rate"""
+        return self._get_attribute("max_request_rate")
+
+    @max_request_rate.setter
+    @write_only
+    @pydantic.validate_call
+    def max_request_rate(self, max_request_rate: int) -> None:
+        """Update tenant's maximum request rate"""
+        self._staging["max_request_rate"] = max_request_rate
+
+    @property
+    @staging_check
+    def max_runs(self) -> int:
+        """Retrieve the tenant's maximum runs"""
+        return self._get_attribute("max_runs")
+
+    @max_runs.setter
+    @write_only
+    @pydantic.validate_call
+    def max_runs(self, max_runs: int) -> None:
+        """Update tenant's maximum runs"""
+        self._staging["max_runs"] = max_runs
+
+    @property
+    @staging_check
+    def max_data_volume(self) -> int:
+        """Retrieve the tenant's maximum data volume"""
+        return self._get_attribute("max_data_volume")
+
+    @max_data_volume.setter
+    @write_only
+    @pydantic.validate_call
+    def max_data_volume(self, max_data_volume: int) -> None:
+        """Update tenant's maximum data volume"""
+        self._staging["max_data_volume"] = max_data_volume