qarnot 2.19.0__py3-none-any.whl → 2.20.1__py3-none-any.whl

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/_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/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/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.dist-info → qarnot-2.20.1.dist-info}/METADATA

@@ -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.dist-info → qarnot-2.20.1.dist-info}/RECORD

@@ -1,8 +1,8 @@
-qarnot/__init__.py,sha256=BCIFvWIe1EbzdZAMeKnyK9HYIqNHlSsbaaDMIL7VghA,5626
+qarnot/__init__.py,sha256=9YYIJJ1Y-PjWXnOBq7z04IocK_OskerJxc-2mOBI5qY,5728
 qarnot/_filter.py,sha256=J--0lOY2rverPEE3zrvuipYkOd9T_4HrW4eVNJqheac,10109
 qarnot/_retry.py,sha256=4QdtI5Y_Jshja8zDxhx_g17dzABCIUGXQsjcPl65u7g,890
 qarnot/_util.py,sha256=fmAq55CmfDTTB7yaOLspayC3Mvre7SCzp0YwWsnwpDA,5673
-qarnot/_version.py,sha256=cs1IDGNzxS3VmGc68RuKml3o2BY_Hw0Eo2b6p2eCVwI,499
+qarnot/_version.py,sha256=tYo4IXXQVfmjbR_GHcGEdgj4ocZabWCvPK6yI4dAjKM,499
 qarnot/advanced_bucket.py,sha256=dfhHOz0foJfEQoaCdGiS_-28w4Y6rq36ZloPgoEQiLE,7927
 qarnot/bucket.py,sha256=aNuJqfYUm2YCQ0m8SBl384xspYkc9SJy6_G-FEKs8nk,24449
 qarnot/carbon_facts.py,sha256=E_tBMsa2byEMgKAEilIFRsCE6_T978Zl7-ZXk4--PPI,10292
@@ -22,11 +22,12 @@ qarnot/privileges.py,sha256=6j3n8q_RNdZ8bBPD9misHEpS0CbcQByqzxlOu8CS-rU,1896
 qarnot/retry_settings.py,sha256=Illobh-1U8hPdzkffJu5TFKM_NdzCNYS2j1teBljX94,2512
 qarnot/scheduling_type.py,sha256=j90APc1ji7xe2Z9OH9l81tjO12k0Wf9bSaG-_UCyeNI,2223
 qarnot/secrets.py,sha256=v6-1UNhCnnW71eJYMeqhcUYLHnsnONGi4Qa3aoiG9qc,12354
+qarnot/snapshot.py,sha256=S8YZDSlzngmBHjmditkZQdrHWiO0nozXbP8y_zMsrV4,9137
 qarnot/status.py,sha256=dCVsh9_ewIASZcreATbUd2qJ-cUMk0cRkyVLdrOot3Q,12348
 qarnot/storage.py,sha256=jAist_J_6yzmRrkF5jqYNG3mhEP_y7KqCdNv4dJcHuM,6929
-qarnot/task.py,sha256=uUfnF2BDq6X8jcGaVRDgK2emFWydwbH_b2QdwXnhtzc,77172
-qarnot-2.19.0.dist-info/licenses/LICENSE,sha256=tAkwu8-AdEyGxGoSvJ2gVmQdcicWw3j1ZZueVV74M-E,11357
-qarnot-2.19.0.dist-info/METADATA,sha256=rR-mDeDXMVjIRA3PuZbTs2bLt9TAAxPO_EDv9mSRAb0,2543
-qarnot-2.19.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-qarnot-2.19.0.dist-info/top_level.txt,sha256=acRyoLZNyf_kuGTwHQgfZv2MfdTcZstyNjBhOxFtHzU,7
-qarnot-2.19.0.dist-info/RECORD,,
+qarnot/task.py,sha256=LQYslV90T4rpo76sPUqG2IhpIMu19QJtI5Jp7jCvJCI,81443
+qarnot-2.20.1.dist-info/licenses/LICENSE,sha256=tAkwu8-AdEyGxGoSvJ2gVmQdcicWw3j1ZZueVV74M-E,11357
+qarnot-2.20.1.dist-info/METADATA,sha256=YjtHFPdEP7SHgv5zsdAMFNQmc4vvB-aU8RRUco-8xNk,2543
+qarnot-2.20.1.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+qarnot-2.20.1.dist-info/top_level.txt,sha256=acRyoLZNyf_kuGTwHQgfZv2MfdTcZstyNjBhOxFtHzU,7
+qarnot-2.20.1.dist-info/RECORD,,

{qarnot-2.19.0.dist-info → qarnot-2.20.1.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.9.0)
+Generator: setuptools (80.10.2)
 Root-Is-Purelib: true
 Tag: py3-none-any