qarnot 2.19.0__tar.gz → 2.20.1__tar.gz

{qarnot-2.19.0/qarnot.egg-info → qarnot-2.20.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qarnot
-Version: 2.19.0
+Version: 2.20.1
 Summary: Qarnot Computing SDK
 Home-page: https://computing.qarnot.com
 Author: Qarnot computing

{qarnot-2.19.0 → qarnot-2.20.1}/qarnot/__init__.py

@@ -62,6 +62,7 @@ def get_url(key, **kwargs):
         'task update': '/tasks/{uuid}',  # GET->result; DELETE -> abort, PATCH -> update resources
         'task snapshot': '/tasks/{uuid}/snapshot/periodic',  # POST -> snapshots
         'task instant': '/tasks/{uuid}/snapshot',  # POST -> get a snapshot
+        'task instant status': '/tasks/{uuid}/snapshot/{snapshotId}',  # GET -> get a snapshot status
         'task stdout': '/tasks/{uuid}/stdout',  # GET -> task stdout
         'task stderr': '/tasks/{uuid}/stderr',  # GET -> task stderr
         'task instance stdout': '/tasks/{uuid}/stdout/{instanceId}',  # GET -> task instance stdout

{qarnot-2.19.0 → qarnot-2.20.1}/qarnot/_version.py

@@ -8,11 +8,11 @@ import json
 
 version_json = '''
 {
- "date": "2025-09-04T17:06:17+0200",
+ "date": "2026-02-06T11:26:35+0100",
  "dirty": false,
  "error": null,
- "full-revisionid": "2436d80006a87be548b2235b12f0a6f041ef66c1",
- "version": "v2.19.0"
+ "full-revisionid": "a21d5058a77a68da123d95dd64550400fafb2bd2",
+ "version": "v2.20.1"
 }
 '''  # END VERSION_JSON
 

qarnot-2.20.1/qarnot/snapshot.py

@@ -0,0 +1,244 @@
+"""Module to handle snapshot"""
+
+# Copyright 2017 Qarnot computing
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from datetime import datetime
+from typing import Optional, Dict, Any, Union
+
+
+class SnapshotConfiguration():
+    """Configuration used for a task snapshot"""
+
+    _whitelist: Optional[str] = None
+    _blacklist: Optional[str] = None
+    _bucket_name: Optional[str] = None
+    _bucket_prefix: Optional[str] = None
+
+    def __init__(self,
+                 whitelist: Optional[str] = None,
+                 blacklist: Optional[str] = None,
+                 bucket_name: Optional[str] = None,
+                 bucket_prefix: Optional[str] = None):
+        """The SnapshotConfiguration constructor.
+
+        :param str whitelist: Whitelist filter for the snapshot.
+        :param str blacklist: Blacklist filter for the snapshot.
+        :param str bucket_name: Name of the bucket in which to upload the snapshot.
+        :param str bucket_prefix: Prefix added to the files uploaded for the snapshot.
+        :returns: The created :class:`~qarnot.snapshot.SnapshotConfiguration`.
+        """
+        self._whitelist = whitelist
+        self._blacklist = blacklist
+        self._bucket_name = bucket_name
+        self._bucket_prefix = bucket_prefix
+
+    def to_json(self) -> Dict[str, Optional[Union[str, int]]]:
+        """Get a SnapshotConfiguration ready to be json packed.
+
+        :return: the json representation of a snapshot configuration.
+        :rtype: Dict[str, Optional[str|int]]
+        """
+        return {
+            "whitelist": self._whitelist,
+            "blacklist": self._blacklist,
+            "bucket": self._bucket_name,
+            "bucketPrefix": self._bucket_prefix
+        }
+
+    @classmethod
+    def from_json(cls, json: Dict[str, Optional[str]]):
+        """Create a SnapshotConfiguration from a json representation
+
+        :param json: the json to use to create the SnapshotConfiguration object.
+        :type json: `Dict[str, Optional[str]]`
+        :returns: The created :class:`~qarnot.snapshot.SnapshotConfiguration`.
+        """
+        if json is None:
+            return None
+
+        whitelist = json.get("whitelist")
+        blacklist = json.get("blacklist")
+        bucket_name = json.get("bucket")
+        bucket_prefix = json.get("bucketPrefix")
+
+        return SnapshotConfiguration(whitelist, blacklist, bucket_name, bucket_prefix)
+
+
+class PeriodicSnapshotConfiguration(SnapshotConfiguration):
+    """Configuration used for a task periodic snapshot"""
+    _interval: int = None
+
+    def __init__(self,
+                 interval: int,
+                 whitelist: Optional[str] = None,
+                 blacklist: Optional[str] = None,
+                 bucket_name: Optional[str] = None,
+                 bucket_prefix: Optional[str] = None):
+        """The PeriodicSnapshotConfiguration constructor.
+
+        :param int interval: Interval (in seconds) between two periodic snapshots.
+        :param str whitelist: Whitelist filter for the snapshot.
+        :param str blacklist: Blacklist filter for the snapshot.
+        :param str bucket_name: Bucket where to upload the snapshot.
+        :param str bucket_prefix: Prefix added to the files uploaded for the snapshot.
+        :returns: The created :class:`~qarnot.snapshot.SnapshotConfiguration`.
+        """
+        super().__init__(whitelist, blacklist, bucket_name, bucket_prefix)
+        self._interval = interval
+
+    def to_json(self) -> Dict[str, Optional[Union[str, int]]]:
+        """Get a PeriodicSnapshotConfiguration ready to be json packed.
+
+        :return: the json representation of a periodic snapshot configuration.
+        :rtype: Dict[str, Optional[str|int]]
+        """
+        json: Dict[str, Optional[Union[str, int]]] = super().to_json()
+        json["interval"] = int(self._interval)
+        return json
+
+
+class SnapshotStatus():
+    """Represents a Snapshot of a task."""
+    status: str = None
+    is_completed: bool = False
+
+    @classmethod
+    def from_string(cls, status: str):
+        """Create a snapshot status from string.
+
+        :returns: The created :class:`~qarnot.snapshot.SnapshotStatus`.
+        """
+
+        if status is None:
+            return TriggeredStatus()
+
+        status = str(status)
+
+        if status.lower() == TriggeredStatus.status.lower():
+            return TriggeredStatus()
+        elif status.lower() == InProgressStatus.status.lower():
+            return InProgressStatus()
+        elif status.lower() == SuccessStatus.status.lower():
+            return SuccessStatus()
+        elif status.lower() == FailedStatus.status.lower():
+            return FailedStatus()
+        else:
+            return TriggeredStatus()
+
+    def __str__(self) -> str:
+        return "snapshot status {}.".format(self.status)
+
+    def __repr__(self) -> str:
+        return str(self.status)
+
+
+class TriggeredStatus(SnapshotStatus):
+    """Represents a snapshot triggered status """
+    status: str = "Triggered"
+    is_completed: bool = False
+
+    def __init__(self):
+        """ Create a new snapshot triggered status."""
+
+
+class InProgressStatus(SnapshotStatus):
+    """Represents a snapshot in progress status"""
+    status: str = "InProgress"
+    is_completed: bool = False
+
+    def __init__(self):
+        """ Create a new snapshot in progress status."""
+
+
+class SuccessStatus(SnapshotStatus):
+    """Represents a snapshot success status"""
+    status: str = "Success"
+    is_completed: bool = True
+
+    def __init__(self):
+        """ Create a new snapshot success status."""
+
+
+class FailedStatus(SnapshotStatus):
+    """Represents snapshot failed status"""
+    status: str = "Failure"
+    is_completed: bool = True
+
+    def __init__(self):
+        """ Create a new snapshot failed status."""
+
+
+class Snapshot():
+    """Represents a Snapshot of a task."""
+    _id: str = None
+    _task_uuid: str = None
+    _trigger_date: datetime = None
+    _last_update_date: Optional[datetime] = None
+    _snapshot_config: SnapshotConfiguration = None
+    _status: SnapshotStatus = None
+    _size_to_upload: Optional[int] = None
+    _transferred_size: Optional[int] = None
+
+    def __init__(self,
+                 uid: str = None,
+                 task_uuid: str = None,
+                 trigger_date: datetime = None,
+                 last_update_date: Optional[datetime] = None,
+                 snapshot_config: SnapshotConfiguration = None,
+                 status: SnapshotStatus = None,
+                 size_to_upload: Optional[int] = None,
+                 transferred_size: Optional[int] = None):
+        """The Snapshot constructor.
+
+        :param str uid: identifier of the snapshot.
+        :param str task_uuid: identifier of the task hat have been snapshoted.
+        :param datetime trigger_date: the date (utc) when the snapshot was requested.
+        :param datetime last_update_date: date (utc) of the last update of the current state of the snapshot.
+        :param `~qarnot.snapshot.SnapshotConfiguration` snapshot_config: the filter and output configuration of the snapshot.
+        :param `~qarnot.snapshot.SnapshotStatus` status: Current progress status of the snapshot.
+        :param int size_to_upload: total size (in bytes) expected to upload for the snapshot.
+        :param int transferred_size: current size (in bytes) of the upload for the snapshot.
+        :returns: The created :class:`~qarnot.snapshot.Snapshot`.
+        """
+        self._id = uid
+        self._task_uuid = task_uuid
+        self._trigger_date = trigger_date
+        self._last_update_date = last_update_date
+        self._snapshot_config = snapshot_config
+        self._status = status
+        self._size_to_upload = size_to_upload
+        self._transferred_size = transferred_size
+
+    @classmethod
+    def from_json(cls, json: Dict[str, Any]):
+        """Create a Snapshot from a json representation
+
+        :param json: the json to use to create the Snapshot object.
+        :type json: `Dict[str, Any]`
+        :returns: The created :class:`~qarnot.snapshot.Snapshot`.
+        """
+        if json is None:
+            return None
+
+        uid = json.get("id")
+        task_uuid = json.get("taskUuid")
+        trigger_date = json.get("triggerDate")
+        last_update_date = json.get("lastUpdateDate")
+        snapshot_config = SnapshotConfiguration.from_json(json.get("snapshotConfig"))
+        status = SnapshotStatus.from_string(json.get("status"))
+        size_to_upload = json.get("sizeToUpload")
+        transferred_size = json.get("transferredSize")
+
+        return Snapshot(uid, task_uuid, trigger_date, last_update_date, snapshot_config, status, size_to_upload, transferred_size)

{qarnot-2.19.0 → qarnot-2.20.1}/qarnot/task.py

@@ -31,6 +31,7 @@ from .status import Status
 from .hardware_constraint import HardwareConstraint
 from .forced_constant import ForcedConstant
 from .scheduling_type import SchedulingType
+from .snapshot import SnapshotConfiguration, PeriodicSnapshotConfiguration, Snapshot
 from .privileges import Privileges
 from .bucket import Bucket
 from .pool import Pool
@@ -663,7 +664,7 @@ class Task(object):
 
         return self.state
 
-    def snapshot(self, interval: int) -> None:
+    def snapshot(self, interval: int, whitelist: Optional[str] = None, blacklist: Optional[str] = None, bucket: BucketType = None, bucket_prefix: Optional[str] = None) -> None:
         """Start snapshooting results.
         If called, this task's results will be periodically
         updated, instead of only being available at the end.
@@ -672,6 +673,10 @@ class Task(object):
         the task is submitted.
 
         :param int interval: the interval in seconds at which to take snapshots
+        :param str whitelist: whitelist filter for the snapshot.
+        :param str blacklist: blacklist filter for the snapshot.
+        :param ~qarnot.bucket.Bucket bucket: bucket to upload the snapshot.
+        :param str bucket_prefix: prefix added to the files uploaded for the snapshot.
 
         :raises ~qarnot.exceptions.QarnotGenericException: API general error, see message for details
         :raises ~qarnot.exceptions.UnauthorizedException: invalid credentials
@@ -685,8 +690,10 @@ class Task(object):
         if self._uuid is None:
             self._snapshots = interval
             return
+
+        snapshot_config = PeriodicSnapshotConfiguration(interval, whitelist, blacklist, bucket, bucket_prefix)
         resp = self._connection._post(get_url('task snapshot', uuid=self._uuid),
-                                      json={"interval": interval})
+                                      json=snapshot_config.to_json())
 
         if resp.status_code == 400:
             raise ValueError(interval)
@@ -699,8 +706,13 @@ class Task(object):
 
         self._snapshots = True
 
-    def instant(self) -> None:
-        """Make a snapshot of the current task.
+    def instant(self, whitelist: Optional[str] = None, blacklist: Optional[str] = None, bucket: BucketType = None, bucket_prefix: Optional[str] = None) -> str:
+        """Make an instant snapshot of the current task.
+
+        :param str whitelist: Whitelist filter for the snapshot.
+        :param str blacklist: Blacklist filter for the snapshot.
+        :param ~qarnot.bucket.Bucket bucket: bucket where to upload the snapshot.
+        :param str bucket_prefix: Prefix added to the files uploaded for the snapshot.
 
         :raises ~qarnot.exceptions.QarnotGenericException: API general error, see message for details
         :raises ~qarnot.exceptions.UnauthorizedException: invalid credentials
@@ -710,10 +722,13 @@ class Task(object):
         .. note:: To get the temporary results, call :meth:`download_results`.
         """
         if self._uuid is None:
-            return
+            return None
+
+        bucket_name = (bucket.uuid if bucket is not None else None)
+        snapshot_config = SnapshotConfiguration(whitelist, blacklist, bucket_name, bucket_prefix)
 
         resp = self._connection._post(get_url('task instant', uuid=self._uuid),
-                                      json=None)
+                                      json=snapshot_config.to_json())
 
         if resp.status_code == 404:
             raise MissingTaskException(_util.get_error_message_from_http_response(resp))
@@ -722,6 +737,80 @@ class Task(object):
         raise_on_error(resp)
 
         self.update(True)
+        return resp.json().get("id")
+
+    def snapshot_status(self, snapshot_id: str) -> Snapshot:
+        """Get the status of a specific instant snapshot.
+
+        :param str snapshot_id: id of the instant snapshot we want the status.
+
+        :raises ~qarnot.exceptions.QarnotGenericException: API general error, see message for details
+        :raises ~qarnot.exceptions.UnauthorizedException: invalid credentials
+        :raises ~qarnot.exceptions.UnauthorizedException: invalid operation on non running task
+        :raises ~qarnot.exceptions.MissingTaskException: task does not exist
+
+        .. note:: To get the temporary results, call :meth:`download_results`.
+        """
+        if self._uuid is None:
+            return None
+
+        resp = self._connection._get(get_url('task instant status', uuid=self._uuid, snapshotId=snapshot_id),
+                                     json=None)
+
+        if resp.status_code == 404:
+            raise MissingTaskException(_util.get_error_message_from_http_response(resp))
+        elif resp.status_code == 403:
+            raise UnauthorizedException(_util.get_error_message_from_http_response(resp))
+        raise_on_error(resp)
+
+        return Snapshot.from_json(resp.json())
+
+    def wait_snapshot(self, snapshot_id: str, timeout: float = None, follow_status: bool = False) -> bool:
+        """Wait for the task snapshot to complete.
+
+        :param float timeout: maximum time (in seconds) to wait before returning
+           (None => no timeout)
+
+        :rtype: :class:`bool`
+        :returns: Is the snapshot finished
+
+        :raises ~qarnot.exceptions.QarnotGenericException: API general error, see message for details
+        :raises ~qarnot.exceptions.UnauthorizedException: invalid credentials
+        :raises ~qarnot.exceptions.MissingTaskException: task does not represent a valid
+          one
+        """
+
+        start = time.time()
+        if self._uuid is None:
+            self.update(True)
+            return False
+
+        if snapshot_id is None or snapshot_id == "":
+            return False
+
+        nap = min(10, timeout) if timeout is not None else 10
+
+        last_status = None
+        snapshot_status = self.snapshot_status(snapshot_id=snapshot_id)
+        if snapshot_status is None:
+            return False
+
+        while snapshot_status is None or not snapshot_status._status.is_completed:
+            time.sleep(nap)
+            snapshot_status = self.snapshot_status(snapshot_id)
+            if follow_status:
+                if snapshot_status._status.status != last_status:
+                    last_status = snapshot_status._status.status
+                    self._connection.logger.info("** Snapshot %s Status| %s" % (snapshot_id, last_status))
+
+            if timeout is not None:
+                elapsed = time.time() - start
+                if timeout <= elapsed:
+                    self.update()
+                    return False
+                else:
+                    nap = min(10, timeout - elapsed)
+        return True
 
     @property
     def state(self):

{qarnot-2.19.0 → qarnot-2.20.1/qarnot.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qarnot
-Version: 2.19.0
+Version: 2.20.1
 Summary: Qarnot Computing SDK
 Home-page: https://computing.qarnot.com
 Author: Qarnot computing

{qarnot-2.19.0 → qarnot-2.20.1}/qarnot.egg-info/SOURCES.txt

@@ -62,6 +62,7 @@ qarnot/privileges.py
 qarnot/retry_settings.py
 qarnot/scheduling_type.py
 qarnot/secrets.py
+qarnot/snapshot.py
 qarnot/status.py
 qarnot/storage.py
 qarnot/task.py
@@ -81,6 +82,7 @@ test/test_paginate.py
 test/test_pool.py
 test/test_retry.py
 test/test_secrets.py
+test/test_snapshot_status.py
 test/test_status.py
 test/test_task.py
 test/test_util.py

qarnot-2.20.1/requirements.txt

@@ -0,0 +1,6 @@
+requests==2.32.5
+boto3==1.42.34
+wheel==0.46.3
+deprecation==2.1.0
+simplejson==3.20.2
+setuptools==80.10.2

qarnot-2.20.1/test/test_snapshot_status.py

@@ -0,0 +1,74 @@
+import pytest
+
+from qarnot.snapshot import Snapshot, TriggeredStatus, InProgressStatus, SuccessStatus, FailedStatus
+
+from .mock_snapshot_status import default_json_status
+
+class TestStatusProperties:
+    @pytest.mark.parametrize("property_name, expected_value", [
+        ("_id", default_json_status["id"]),
+        ("_task_uuid", default_json_status["taskUuid"]),
+        ("_trigger_date", default_json_status["triggerDate"]),
+        ("_last_update_date", default_json_status["lastUpdateDate"]),
+        ("_size_to_upload", default_json_status["sizeToUpload"]),
+        ("_transferred_size", default_json_status["transferredSize"]),
+    ])
+    def test_create_snapshot_status_from_json_hydrate_property_values(self, property_name,  expected_value):
+        snapshot_from_json = Snapshot.from_json(default_json_status)
+        assert getattr(snapshot_from_json, property_name) == expected_value
+
+    @pytest.mark.parametrize("property_names, expected_value", [
+        (["_snapshot_config", "_whitelist"], default_json_status["snapshotConfig"]["whitelist"]),
+        (["_snapshot_config", "_blacklist"], default_json_status["snapshotConfig"]["blacklist"]),
+        (["_snapshot_config", "_bucket_name"], default_json_status["snapshotConfig"]["bucket"]),
+        (["_snapshot_config", "_bucket_prefix"], default_json_status["snapshotConfig"]["bucketPrefix"]),
+    ])
+    def test_create_snapshot_status_from_json_hydrate_configuration_subproperty_values(self, property_names,  expected_value):
+        snapshot_from_json = Snapshot.from_json(default_json_status)
+        value = getattr(snapshot_from_json, property_names[0])
+        for property_name in property_names[1:]:
+            if type(property_name) is int:
+                value = value[property_name]
+            else:
+                value = getattr(value, property_name)
+        assert value == expected_value
+    
+    @pytest.mark.parametrize("json_value, expected_status_type", [
+        ("triggered", TriggeredStatus),
+        ("Triggered", TriggeredStatus),
+        ("inProgress", InProgressStatus),
+        ("InProgress", InProgressStatus),
+        ("success", SuccessStatus),
+        ("failure", FailedStatus)])
+    def test_snapshot_status_correctly_deserialized(self, json_value, expected_status_type: type):
+        json = { "status": json_value }
+        snapshot_from_json = Snapshot.from_json(json)
+        assert snapshot_from_json._status is not None
+        assert type(snapshot_from_json._status) == expected_status_type
+
+    def test_snapshot_status_with_null_values_does_not_throw_at_deserialization(self):
+        json = {
+            "id": None,
+            "taskUuid": None,
+            "triggerDate": None,
+            "lastUpdateDate": None,
+            "snapshotConfig": None,
+            "status": None,
+            "sizeToUpload": None,
+            "transferredSize": None,
+        }
+        snapshot_from_json = Snapshot.from_json(json)
+        assert snapshot_from_json._status is not None
+        assert type(snapshot_from_json._status) == TriggeredStatus
+
+        json = {
+            "snapshotConfig":
+            {
+                "whitelist": None,
+                "blacklist": None,
+                "bucket": None,
+                "bucketPrefix": None
+            }
+        }
+        snapshot_from_json = Snapshot.from_json(json)
+        assert snapshot_from_json._snapshot_config is not None

qarnot-2.19.0/requirements.txt

@@ -1,6 +0,0 @@
-requests==2.32.5
-boto3==1.40.21
-wheel==0.45.1
-deprecation==2.1.0
-simplejson==3.20.1
-setuptools==80.9.0