qarnot 2.16.0__py3-none-any.whl → 2.18.0__py3-none-any.whl

qarnot/__init__.py

@@ -16,6 +16,7 @@
 # limitations under the License.
 
 
+from typing import Dict
 from .exceptions import QarnotGenericException, SecretConflictException, SecretNotFoundException, UnauthorizedException
 from ._util import get_error_message_from_http_response
 
@@ -65,7 +66,8 @@ def get_url(key, **kwargs):
         'task stderr': '/tasks/{uuid}/stderr',  # GET -> task stderr
         'task instance stdout': '/tasks/{uuid}/stdout/{instanceId}',  # GET -> task instance stdout
         'task instance stderr': '/tasks/{uuid}/stderr/{instanceId}',  # GET -> task instance stderr
-        'task abort': '/tasks/{uuid}/abort',  # GET -> task
+        'task abort': '/tasks/{uuid}/abort',  # POST -> abort task
+        'task carbon facts': '/carbon/v1/tasks/{uuid}/carbon-facts',  # GET -> task carbon facts
         'pools': '/pools',  # POST -> submit pool
         'paginate pools': '/pools/paginate',  # GET -> paginate pools
         'paginate pools summaries': '/pools/summaries/paginate',  # GET -> paginate pools summaries
@@ -76,6 +78,7 @@ def get_url(key, **kwargs):
         'pool stderr': '/pools/{uuid}/stderr',  # GET -> pool stderr
         'pool instance stdout': '/pools/{uuid}/stdout/{instanceId}',  # GET -> pool instance stdout
         'pool instance stderr': '/pools/{uuid}/stderr/{instanceId}',  # GET -> pool instance stderr
+        'pool carbon facts': '/carbon/v1/pools/{uuid}/carbon-facts',  # GET -> pool carbon facts
         'secrets data': '/secrets-manager/data/{secret_key}',  # GET -> get secret , PUT -> create secret, PATCH -> update secret, DELETE -> delete secret
         'secrets search': '/secrets-manager/search/{secret_prefix}',  # GET -> lists secrets starting with prefix
         'user': '/info',  # GET -> user info
@@ -88,6 +91,13 @@ def get_url(key, **kwargs):
     return urls[key].format(**kwargs)
 
 
+def get_url_with_param(key, params: Dict[str, str], **kwargs):
+    if (params is None or len(params) == 0):
+        return get_url(key, **kwargs)
+    param_string = "&".join(f'{key}={value}' for key, value in params.items())
+    return "{url}?{param}".format(url=get_url(key, **kwargs), param=param_string)
+
+
 from ._version import get_versions  # noqa
 __version__ = get_versions()['version']  # type: ignore
 del get_versions

qarnot/_version.py

@@ -8,11 +8,11 @@ import json
 
 version_json = '''
 {
- "date": "2025-02-07T16:27:29+0100",
+ "date": "2025-05-22T14:41:22+0200",
  "dirty": false,
  "error": null,
- "full-revisionid": "23daecdc71207c207e56afae3e55190f0734bd0d",
- "version": "v2.16.0"
+ "full-revisionid": "9361585630d3dbcc8fa50ecbb9d20d592234a808",
+ "version": "v2.18.0"
 }
 '''  # END VERSION_JSON
 

qarnot/advanced_bucket.py

@@ -180,7 +180,7 @@ class PrefixResourcesTransformation(AbstractResourcesTransformation):
         :return: The PrefixResourcesTransformation new object
         :rtype: :class:`PrefixResourcesTransformation`
         """
-        return PrefixResourcesTransformation(json["prefix"])
+        return PrefixResourcesTransformation(json.get("prefix"))
 
     def to_json(self) -> object:
         """Get a dict ready to be json packed.

qarnot/bucket.py

@@ -107,14 +107,14 @@ class Bucket(Storage):  # pylint: disable=W0223
         :returns: The created :class:`~qarnot.bucket.Bucket`.
         """
         filtering = None
-        if "filtering" in json_bucket and json_bucket['filtering']:
-            filtering = Filtering.from_json(json_bucket['filtering'])
+        if "filtering" in json_bucket and json_bucket.get('filtering'):
+            filtering = Filtering.from_json(json_bucket.get('filtering'))
 
         resource_transformation = None
-        if "resourcesTransformation" in json_bucket and json_bucket['resourcesTransformation']:
-            resource_transformation = ResourcesTransformation.from_json(json_bucket['resourcesTransformation'])
+        if "resourcesTransformation" in json_bucket and json_bucket.get('resourcesTransformation'):
+            resource_transformation = ResourcesTransformation.from_json(json_bucket.get('resourcesTransformation'))
 
-        bucket = Bucket(connection, json_bucket['bucketName'], create=False, filtering=filtering, resources_transformation=resource_transformation, cacheTTLSec=json_bucket['cacheTTLSec'])
+        bucket = Bucket(connection, json_bucket.get('bucketName'), create=False, filtering=filtering, resources_transformation=resource_transformation, cacheTTLSec=json_bucket.get('cacheTTLSec'))
         return bucket
 
     def with_filtering(self, filtering):
@@ -218,7 +218,7 @@ class Bucket(Storage):  # pylint: disable=W0223
                 )
             self._connection.s3client.delete_bucket(Bucket=self._uuid)
         except self._connection.s3resource.meta.client.exceptions.NoSuchBucket as err:
-            raise MissingBucketException("Cannot delete {}. Bucket not found.".format(err.response['Error']['BucketName'])) from err
+            raise MissingBucketException("Cannot delete {}. Bucket not found.".format(err.response.get('Error').get('BucketName'))) from err
 
     def list_files(self):
         """List files in the bucket
@@ -231,7 +231,7 @@ class Bucket(Storage):  # pylint: disable=W0223
             bucket = self._connection.s3resource.Bucket(self._uuid)
             return [b for b in bucket.objects.all() if b.key is not None]
         except self._connection.s3resource.meta.client.exceptions.NoSuchBucket as err:
-            raise MissingBucketException("Cannot list files. Bucket {} not found.".format(err.response['Error']['BucketName'])) from err
+            raise MissingBucketException("Cannot list files. Bucket {} not found.".format(err.response.get('Error').get('BucketName'))) from err
 
     def directory(self, directory=''):
         """List files in a directory of the bucket according to prefix.
@@ -281,7 +281,7 @@ class Bucket(Storage):  # pylint: disable=W0223
             list_files_only = [x for x in entries if not x.key.endswith('/')]
             list_directories_only = [x for x in entries if x.key.endswith('/')]
         except self._connection.s3resource.meta.client.exceptions.NoSuchBucket as err:
-            raise MissingBucketException("Cannot synchronize. Bucket {} not found.".format(err.response['Error']['BucketName'])) from err
+            raise MissingBucketException("Cannot synchronize. Bucket {} not found.".format(err.response.get('Error').get('BucketName'))) from err
 
         for directory in list_directories_only:
             if not os.path.isdir(os.path.join(local_directoy, get_key_for_local(directory.key))):
@@ -459,7 +459,7 @@ class Bucket(Storage):  # pylint: disable=W0223
                         self._connection.logger.info("Copy %s to %s" % (entry[0].name, link.name))
                     self.copy_file(entry[0].name, link.name)
         except self._connection.s3resource.meta.client.exceptions.NoSuchBucket as err:
-            raise MissingBucketException("Cannot sync files. Bucket {} not found.".format(err.response['Error']['BucketName'])) from err
+            raise MissingBucketException("Cannot sync files. Bucket {} not found.".format(err.response.get('Error').get('BucketName'))) from err
 
     def add_string(self, string, remote):
         """Add a string on the storage.
@@ -484,7 +484,7 @@ class Bucket(Storage):  # pylint: disable=W0223
         try:
             self._connection.s3client.upload_fileobj(file_, self._uuid, dest, Config=s3_multipart_config)
         except self._connection.s3resource.meta.client.exceptions.NoSuchBucket as err:
-            raise MissingBucketException("Cannot add string. Bucket {} not found.".format(err.response['Error']['BucketName'])) from err
+            raise MissingBucketException("Cannot add string. Bucket {} not found.".format(err.response.get('Error').get('BucketName'))) from err
         finally:
             if tobeclosed:
                 file_.close()
@@ -523,7 +523,7 @@ class Bucket(Storage):  # pylint: disable=W0223
             }
             return self._connection.s3client.copy_object(CopySource=copy_source, Bucket=self._uuid, Key=dest)
         except self._connection.s3resource.meta.client.exceptions.NoSuchBucket as err:
-            raise MissingBucketException("Cannot copy file {} to {} from bucket {}. Bucket not found.".format(source, dest, err.response['Error']['BucketName'])) from err
+            raise MissingBucketException("Cannot copy file {} to {} from bucket {}. Bucket not found.".format(source, dest, err.response.get('Error').get('BucketName'))) from err
 
     @deprecation.deprecated(deprecated_in="2.6.0", removed_in="3.0",
                             current_version=__version__,  # type: ignore
@@ -547,7 +547,7 @@ class Bucket(Storage):  # pylint: disable=W0223
                 try:
                     self._connection.s3client.download_fileobj(self._uuid, remote, data)
                 except self._connection.s3resource.meta.client.exceptions.NoSuchBucket as err:
-                    raise MissingBucketException("Cannot download file {} from bucket {}. Bucket not found.".format(remote, err.response['Error']['BucketName'])) from err
+                    raise MissingBucketException("Cannot download file {} from bucket {}. Bucket not found.".format(remote, err.response.get('Error').get('BucketName'))) from err
         return local
 
     @_util.copy_docs(Storage.delete_file)
@@ -557,7 +557,7 @@ class Bucket(Storage):  # pylint: disable=W0223
                 remote = _util.get_sanitized_bucket_path(remote, self._connection._show_bucket_warnings)
             self._connection.s3client.delete_object(Bucket=self._uuid, Key=remote)
         except self._connection.s3resource.meta.client.exceptions.NoSuchBucket as err:
-            raise MissingBucketException("Cannot delete file {} from bucket {}. Bucket not found.".format(remote, err.response['Error']['BucketName'])) from err
+            raise MissingBucketException("Cannot delete file {} from bucket {}. Bucket not found.".format(remote, err.response.get('Error').get('BucketName'))) from err
 
     @property
     def uuid(self):

qarnot/carbon_facts.py

@@ -0,0 +1,208 @@
+"""Carbon facts prototype"""
+
+from typing import Any, Dict
+from requests import Response
+from .exceptions import MissingPoolException, MissingTaskException
+from . import get_url, get_url_with_param, raise_on_error, _util
+
+
+class CarbonFacts(object):
+    """
+        Carbon facts details of a computed element
+    """
+
+    def __init__(
+            self,
+            energy_consumption: float = 0,
+            energy_it: float = 0,
+            energy_reuse: float = 0,
+            carbon_footprint: float = 0,
+            equivalent_dc_name: str = "",
+            equivalent_dc_carbon_footprint: float = 0,
+            saved_carbon_footprint_compute: float = 0,
+            saved_carbon_footprint_heat: float = 0,
+            saved_carbon_footprint_compute_heat: float = 0,
+            saved_carbon_footprint_percent: float = 0,
+            PUE: float = 0,
+            ERE: float = 0,
+            ERF: float = 0,
+            WUE: float = 0):
+        """The CarbonFacts constructor
+
+        :param energy_consumption: the total energy consumed, in W.h
+        :type energy_consumption: `float`
+        :param energy_it: the energy consumed by IT, in W.h
+        :type energy_it: `float`
+        :param energy_reuse: the reuse heat, in W.h
+        :type energy_reuse: `float`
+        :param carbon_footprint: the actual carbon footprint of the computation, in gCO2eq
+        :type carbon_footprint: `float`
+        :param equivalent_dc_name: the name of the equivalent datacenter used for comparison
+        :type equivalent_dc_name: `str`
+        :param equivalent_dc_carbon_footprint: the carbon footprint the computation would generate in an equivalent DC, in gCO2eq
+        :type equivalent_dc_carbon_footprint: `float`
+        :param saved_carbon_footprint_compute: the carbon footprint saved by the computation part by using Qarnot instead of the equivalent DC, in gCO2eq
+        :type saved_carbon_footprint_compute: `float`
+        :param saved_carbon_footprint_heat: the carbon footprint saved by the heating part by using Qarnot instead of the equivalent DC, in gCO2eq
+        :type saved_carbon_footprint_heat: `float`
+        :param saved_carbon_footprint_compute_heat: the total carbon footprint saved by using Qarnot instead of the equivalent DC, gCO2eq
+        :type saved_carbon_footprint_compute_heat: `float`
+        :param saved_carbon_footprint_percent: the percentage of carbon footprint saved by using Qarnot instead of the equivalent DC, in %
+        :type saved_carbon_footprint_percent: `float`
+        :param PUE: the energy efficiency of the computation site
+        :type PUE: `float`
+        :param ERE: the energy reuse ratio of the computation site
+        :type ERE: `float`
+        :param ERF: the heat reuse ratio of the computation site
+        :type ERF: `float`
+        :param WUE: the water consumption of the computation site, in L/kWh
+        :type WUE: `float`
+        """
+        self.energy_consumption_Wh: float = energy_consumption
+        self.energy_it_Wh: float = energy_it
+        self.energy_reuse_Wh: float = energy_reuse
+        self.carbon_footprint_gC02eq: float = carbon_footprint
+        self.equivalent_datacenter_name: str = equivalent_dc_name
+        self.equivalent_dc_carbon_footprint_gC02eq: float = equivalent_dc_carbon_footprint
+        self.saved_carbon_footprint_compute_gC02eq: float = saved_carbon_footprint_compute
+        self.saved_carbon_footprint_heat_gC02eq: float = saved_carbon_footprint_heat
+        self.saved_carbon_footprint_compute_heat_gC02eq: float = saved_carbon_footprint_compute_heat
+        self.saved_carbon_footprint_percent: float = saved_carbon_footprint_percent
+        self.PUE: float = PUE
+        self.ERE: float = ERE
+        self.ERF: float = ERF
+        self.WUE: float = WUE
+
+    @classmethod
+    def from_json(cls, json: Dict[str, Any]):
+        """Create a CarbonFacts from a json representation
+
+        :param json: the json to use to create the SecretsAccessRights object.
+        :type json: `Dict[str, float]`
+        :returns: The created :class:`~qarnot.carbon_facts.CarbonFacts`.
+        """
+        if json is None:
+            return None
+
+        energy_consumption = json.get("total_consumed_energy_Wh")
+        energy_it = json.get("total_energy_it_Wh")
+        energy_reuse = json.get("total_reused_energy_Wh")
+        carbon_footprint = json.get("qarnot_carbon_footprint")
+        equivalent_datacenter_name = json.get("equivalent_datacenter_name")
+        equivalent_dc_carbon_footprint = json.get("equivalent_DC_carbon_footprint")
+        saved_carbon_footprint_compute = json.get("saved_carbon_footprint_compute")
+        saved_carbon_footprint_heat = json.get("saved_carbon_footprint_heat")
+        saved_carbon_footprint_compute_heat = json.get("saved_carbon_footprint_compute_heat")
+        saved_carbon_footprint_percent = json.get("saved_carbon_footprint_percent")
+        PUE = json.get("PUE")
+        ERE = json.get("ERE")
+        ERF = json.get("ERF")
+        WUE = json.get("WUE")
+
+        return CarbonFacts(energy_consumption, energy_it, energy_reuse, carbon_footprint, equivalent_datacenter_name,
+                           equivalent_dc_carbon_footprint, saved_carbon_footprint_compute, saved_carbon_footprint_heat,
+                           saved_carbon_footprint_compute_heat, saved_carbon_footprint_percent, PUE, ERE, ERF, WUE)
+
+    def to_json(self) -> object:
+        """Get a dict ready to be json packed.
+
+        :return: the json elements of the class.
+        :rtype: `dict`
+
+        """
+        return {
+            "total_consumed_energy_Wh": self.energy_consumption_Wh,
+            "total_energy_it_Wh": self.energy_it_Wh,
+            "total_reused_energy_Wh": self.energy_reuse_Wh,
+            "qarnot_carbon_footprint": self.carbon_footprint_gC02eq,
+            "equivalent_datacenter_name": self.equivalent_datacenter_name,
+            "equivalent_DC_carbon_footprint": self.equivalent_dc_carbon_footprint_gC02eq,
+            "saved_carbon_footprint_compute": self.saved_carbon_footprint_compute_gC02eq,
+            "saved_carbon_footprint_heat": self.saved_carbon_footprint_heat_gC02eq,
+            "saved_carbon_footprint_compute_heat": self.saved_carbon_footprint_compute_heat_gC02eq,
+            "saved_carbon_footprint_percent": self.saved_carbon_footprint_percent,
+            "PUE": self.PUE,
+            "ERE": self.ERE,
+            "ERF": self.ERF,
+            "WUE": self.WUE
+        }
+
+
+class CarbonClient(object):
+    """
+        Client used to interact with the Qarnot carbon API.
+    """
+
+    def __init__(self, connection, datacenter_name: str = None):
+        """The CarbonClient constructor.
+
+        :param connection: the cluster from where carbon facts are retrieved.
+        :type connection: `qarnot.connection.Connection`
+        :param datacenter_name: the name of the datacenter used as reference to compare carbon facts.
+        :type datacenter_name: `str`
+        """
+        self._connection = connection
+        self.reference_datacenter_name = datacenter_name
+
+    def _get_carbon_facts_url(self, resource_type: str, uuid: str):
+        if self.reference_datacenter_name is None or self.reference_datacenter_name == "":
+            return get_url('%s carbon facts' % resource_type, uuid=uuid)
+        return get_url_with_param('%s carbon facts' % resource_type, {'comparisonDatacenter': self.reference_datacenter_name}, uuid=uuid)
+
+    def _get_pool_carbon_facts_raw(self, pool_id: str) -> Response:
+        """Requests the carbon facts for the pool `pool_id`.
+
+        :param pool_id: the uuid of the pool
+        :type pool_id: `str`
+        :rtype: `requests.Response`
+        :raises ~qarnot.exceptions.MissingPoolException: Pool was not found.
+        :raises ~qarnot.exceptions.UnauthorizedException: Unauthorized.
+        :raises ~qarnot.exceptions.QarnotGenericException: API general error, see message for details
+        """
+        response = self._connection._get(self._get_carbon_facts_url('pool', pool_id))
+        if response.status_code == 404:
+            raise MissingPoolException(_util.get_error_message_from_http_response(response))
+        raise_on_error(response)
+        return response
+
+    def get_pool_carbon_facts(self, pool_id: str) -> CarbonFacts:
+        """Retrieves the carbon facts of the pool `pool_id` and parses it to a CarbonFacts object.
+
+        :param pool_id: the uuid of the pool
+        :type pool_id: `str`
+        :rtype: CarbonFacts
+        :raises ~qarnot.exceptions.MissingPoolException: Pool was not found.
+        :raises ~qarnot.exceptions.UnauthorizedException: Unauthorized.
+        :raises ~qarnot.exceptions.QarnotGenericException: API general error, see message for details
+        """
+        raw_carbon_facts = self._get_pool_carbon_facts_raw(pool_id)
+        return CarbonFacts.from_json(raw_carbon_facts.json())
+
+    def _get_task_carbon_facts_raw(self, task_id: str) -> Response:
+        """Requests the carbon facts for the task `task_id`.
+
+        :param task_id: the uuid of the task
+        :type task_id: `str`
+        :rtype: `requests.Response`
+        :raises ~qarnot.exceptions.MissingTaskException: Task was not found.
+        :raises ~qarnot.exceptions.UnauthorizedException: Unauthorized.
+        :raises ~qarnot.exceptions.QarnotGenericException: API general error, see message for details
+        """
+        response = self._connection._get(self._get_carbon_facts_url('task', task_id))
+        if response.status_code == 404:
+            raise MissingTaskException(_util.get_error_message_from_http_response(response))
+        raise_on_error(response)
+        return response
+
+    def get_task_carbon_facts(self, task_id: str) -> CarbonFacts:
+        """Retrieves the carbon facts of the task `task_id` and parses it to a CarbonFacts object.
+
+        :param task_id: the uuid of the task
+        :type task_id: `str`
+        :rtype: CarbonFacts
+        :raises ~qarnot.exceptions.MissingTaskException: Task was not found.
+        :raises ~qarnot.exceptions.UnauthorizedException: Unauthorized.
+        :raises ~qarnot.exceptions.QarnotGenericException: API general error, see message for details
+        """
+        raw_carbon_facts = self._get_task_carbon_facts_raw(task_id)
+        return CarbonFacts.from_json(raw_carbon_facts.json())