codecarbon 3.1.0__tar.gz → 3.1.1__tar.gz

{codecarbon-3.1.0 → codecarbon-3.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecarbon
-Version: 3.1.0
+Version: 3.1.1
 Author: Mila, DataForGood, BCG GAMMA, Comet.ml, Haverford College
 License-Expression: MIT
 Project-URL: Homepage, https://codecarbon.io/
@@ -220,7 +220,7 @@ In order to contribute a change to our code base, please submit a pull request (
 
 Check out our [contribution guidelines :arrow_upper_right:](https://github.com/mlco2/codecarbon/blob/master/CONTRIBUTING.md)
 
-Contact [@vict0rsch](https://github.com/vict0rsch) to be added to our slack workspace if you want to contribute regularly!
+Feel free to chat with us on [Discord](https://discord.gg/GS9js2XkJR).
 
 # How To Cite 📝
 
@@ -271,7 +271,11 @@ Here is a sample for BibTeX:
 
 # Contact 📝
 
-Maintainers are [@vict0rsch](https://github.com/vict0rsch) [@benoit-cty](https://github.com/benoit-cty) and [@SaboniAmine](https://github.com/saboniamine). Codecarbon is developed by volunteers from [**Mila**](http://mila.quebec) and the [**DataForGoodFR**](https://twitter.com/dataforgood_fr) community alongside donated professional time of engineers at [**Comet.ml**](https://comet.ml) and [**BCG GAMMA**](https://www.bcg.com/en-nl/beyond-consulting/bcg-gamma/default).
+Feel free to chat with us on [Discord](https://discord.gg/GS9js2XkJR).
+
+Codecarbon was formerly developed by volunteers from [**Mila**](http://mila.quebec) and the [**DataForGoodFR**](https://twitter.com/dataforgood_fr) community alongside donated professional time of engineers at [**Comet.ml**](https://comet.ml) and [**BCG GAMMA**](https://www.bcg.com/en-nl/beyond-consulting/bcg-gamma/default).
+
+Now CodeCarbon is supported by [**Code Carbon**](https://www.helloasso.com/associations/code-carbon), a French non-profit organization whose mission is to accelerate the development and adoption of CodeCarbon.
 
 ## Star History
 

{codecarbon-3.1.0 → codecarbon-3.1.1}/README.md

@@ -143,7 +143,7 @@ In order to contribute a change to our code base, please submit a pull request (
 
 Check out our [contribution guidelines :arrow_upper_right:](https://github.com/mlco2/codecarbon/blob/master/CONTRIBUTING.md)
 
-Contact [@vict0rsch](https://github.com/vict0rsch) to be added to our slack workspace if you want to contribute regularly!
+Feel free to chat with us on [Discord](https://discord.gg/GS9js2XkJR).
 
 # How To Cite 📝
 
@@ -194,7 +194,11 @@ Here is a sample for BibTeX:
 
 # Contact 📝
 
-Maintainers are [@vict0rsch](https://github.com/vict0rsch) [@benoit-cty](https://github.com/benoit-cty) and [@SaboniAmine](https://github.com/saboniamine). Codecarbon is developed by volunteers from [**Mila**](http://mila.quebec) and the [**DataForGoodFR**](https://twitter.com/dataforgood_fr) community alongside donated professional time of engineers at [**Comet.ml**](https://comet.ml) and [**BCG GAMMA**](https://www.bcg.com/en-nl/beyond-consulting/bcg-gamma/default).
+Feel free to chat with us on [Discord](https://discord.gg/GS9js2XkJR).
+
+Codecarbon was formerly developed by volunteers from [**Mila**](http://mila.quebec) and the [**DataForGoodFR**](https://twitter.com/dataforgood_fr) community alongside donated professional time of engineers at [**Comet.ml**](https://comet.ml) and [**BCG GAMMA**](https://www.bcg.com/en-nl/beyond-consulting/bcg-gamma/default).
+
+Now CodeCarbon is supported by [**Code Carbon**](https://www.helloasso.com/associations/code-carbon), a French non-profit organization whose mission is to accelerate the development and adoption of CodeCarbon.
 
 ## Star History
 

codecarbon-3.1.1/codecarbon/_version.py

@@ -0,0 +1 @@
+__version__ = "3.1.1"

codecarbon-3.1.0/codecarbon/core/co2_signal.py → codecarbon-3.1.1/codecarbon/core/electricitymaps_api.py

@@ -5,19 +5,19 @@ import requests
 from codecarbon.core.units import EmissionsPerKWh, Energy
 from codecarbon.external.geography import GeoMetadata
 
-URL: str = "https://api.co2signal.com/v1/latest"
-CO2_SIGNAL_API_TIMEOUT: int = 30
+URL: str = "https://api.electricitymaps.com/v3/carbon-intensity/latest"
+ELECTRICITYMAPS_API_TIMEOUT: int = 30
 
 
 def get_emissions(
-    energy: Energy, geo: GeoMetadata, co2_signal_api_token: str = ""
+    energy: Energy, geo: GeoMetadata, electricitymaps_api_token: str = ""
 ) -> float:
     """
     Calculate the CO2 emissions based on energy consumption and geographic location.
 
-    This function retrieves the carbon intensity (in grams of CO2 per kWh) from the CO2
-    Signal API based on the geographic location provided. It then calculates the total
-    CO2 emissions for a given amount of energy consumption.
+    This function retrieves the carbon intensity (in grams of CO2 per kWh) from the
+    Electricity Maps API (formerly CO2 Signal) based on the geographic location provided.
+    It then calculates the total CO2 emissions for a given amount of energy consumption.
 
     Args:
         energy (Energy):
@@ -25,8 +25,8 @@ def get_emissions(
         geo (GeoMetadata):
             Geographic metadata, including either latitude/longitude
             or a country code.
-        co2_signal_api_token (str, optional):
-            The API token for authenticating with the CO2 Signal API (default is an empty string).
+        electricitymaps_api_token (str, optional):
+            The API token for authenticating with the Electricity Maps API (default is an empty string).
 
     Returns:
         float:
@@ -34,8 +34,8 @@ def get_emissions(
             carbon intensity of the specified geographic location.
 
     Raises:
-        CO2SignalAPIError:
-            If the CO2 Signal API request fails or returns an error.
+        ElectricityMapsAPIError:
+            If the Electricity Maps API request fails or returns an error.
     """
     params: Dict[str, Any]
     if geo.latitude:
@@ -45,18 +45,25 @@ def get_emissions(
     resp = requests.get(
         URL,
         params=params,
-        headers={"auth-token": co2_signal_api_token},
-        timeout=CO2_SIGNAL_API_TIMEOUT,
+        headers={"auth-token": electricitymaps_api_token},
+        timeout=ELECTRICITYMAPS_API_TIMEOUT,
     )
     if resp.status_code != 200:
         message = resp.json().get("error") or resp.json().get("message")
-        raise CO2SignalAPIError(message)
-    carbon_intensity_g_per_kWh = resp.json()["data"]["carbonIntensity"]
+        raise ElectricityMapsAPIError(message)
+
+    # API v3 response structure: carbonIntensity is at the root level
+    response_data = resp.json()
+    carbon_intensity_g_per_kWh = response_data.get("carbonIntensity")
+
+    if carbon_intensity_g_per_kWh is None:
+        raise ElectricityMapsAPIError("No carbonIntensity data in response")
+
     emissions_per_kWh: EmissionsPerKWh = EmissionsPerKWh.from_g_per_kWh(
         carbon_intensity_g_per_kWh
     )
     return emissions_per_kWh.kgs_per_kWh * energy.kWh
 
 
-class CO2SignalAPIError(Exception):
+class ElectricityMapsAPIError(Exception):
     pass

{codecarbon-3.1.0 → codecarbon-3.1.1}/codecarbon/core/emissions.py

@@ -10,7 +10,7 @@ from typing import Dict, Optional
 
 import pandas as pd
 
-from codecarbon.core import co2_signal
+from codecarbon.core import electricitymaps_api
 from codecarbon.core.units import EmissionsPerKWh, Energy
 from codecarbon.external.geography import CloudMetadata, GeoMetadata
 from codecarbon.external.logger import logger
@@ -19,10 +19,25 @@ from codecarbon.input import DataSource, DataSourceException
 
 class Emissions:
     def __init__(
-        self, data_source: DataSource, co2_signal_api_token: Optional[str] = None
+        self,
+        data_source: DataSource,
+        electricitymaps_api_token: Optional[str] = None,
+        co2_signal_api_token: Optional[
+            str
+        ] = None,  # Deprecated, for backward compatibility
     ):
         self._data_source = data_source
-        self._co2_signal_api_token = co2_signal_api_token
+
+        # Handle backward compatibility
+        if co2_signal_api_token is not None:
+            logger.warning(
+                "Parameter 'co2_signal_api_token' is deprecated and will be removed in a future version. "
+                "Please use 'electricitymaps_api_token' instead."
+            )
+            if electricitymaps_api_token is None:
+                electricitymaps_api_token = co2_signal_api_token
+
+        self._electricitymaps_api_token = electricitymaps_api_token
 
     def get_cloud_emissions(
         self, energy: Energy, cloud: CloudMetadata, geo: GeoMetadata = None
@@ -123,12 +138,19 @@ class Emissions:
         :param geo: Country and region metadata
         :return: CO2 emissions in kg
         """
-        if self._co2_signal_api_token:
+        if self._electricitymaps_api_token:
             try:
-                return co2_signal.get_emissions(energy, geo, self._co2_signal_api_token)
+                emissions = electricitymaps_api.get_emissions(
+                    energy, geo, self._electricitymaps_api_token
+                )
+                logger.debug(
+                    "electricitymaps_api.get_emissions: "
+                    + f"Retrieved emissions for {geo.country_name} using Electricity Maps API :{emissions * 1000} g CO2eq"
+                )
+                return emissions
             except Exception as e:
                 logger.error(
-                    "co2_signal.get_emissions: "
+                    "electricitymaps_api.get_emissions: "
                     + str(e)
                     + " >>> Using CodeCarbon's data."
                 )

{codecarbon-3.1.0 → codecarbon-3.1.1}/codecarbon/emissions_tracker.py

@@ -171,7 +171,10 @@ class BaseEmissionsTracker(ABC):
         emissions_endpoint: Optional[str] = _sentinel,
         experiment_id: Optional[str] = _sentinel,
         experiment_name: Optional[str] = _sentinel,
-        co2_signal_api_token: Optional[str] = _sentinel,
+        electricitymaps_api_token: Optional[str] = _sentinel,
+        co2_signal_api_token: Optional[
+            str
+        ] = _sentinel,  # Deprecated, use electricitymaps_api_token
         tracking_mode: Optional[str] = _sentinel,
         log_level: Optional[Union[int, str]] = _sentinel,
         on_csv_write: Optional[str] = _sentinel,
@@ -221,8 +224,9 @@ class BaseEmissionsTracker(ABC):
                                    data.
         :param experiment_id: Id of the experiment.
         :param experiment_name: Label of the experiment
-        :param co2_signal_api_token: API token for co2signal.com (requires sign-up for
-                                     free beta)
+        :param electricitymaps_api_token: API token for electricitymaps.com (formerly co2signal.com)
+        :param co2_signal_api_token: [DEPRECATED] Use electricitymaps_api_token instead.
+                                     Old parameter name for backward compatibility.
         :param tracking_mode: One of "process" or "machine" in order to measure the
                               power consumption due to the entire machine or to try and
                               isolate the tracked processe's in isolation.
@@ -268,7 +272,31 @@ class BaseEmissionsTracker(ABC):
         self._set_from_conf(api_call_interval, "api_call_interval", 8, int)
         self._set_from_conf(api_endpoint, "api_endpoint", "https://api.codecarbon.io")
         self._set_from_conf(api_key, "api_key", "api_key")
-        self._set_from_conf(co2_signal_api_token, "co2_signal_api_token")
+
+        # Handle backward compatibility for co2_signal_api_token
+        if co2_signal_api_token is not _sentinel:
+            logger.warning(
+                "Parameter 'co2_signal_api_token' is deprecated and will be removed in a future version. "
+                "Please use 'electricitymaps_api_token' instead."
+            )
+            if electricitymaps_api_token is _sentinel:
+                electricitymaps_api_token = co2_signal_api_token
+
+        self._set_from_conf(electricitymaps_api_token, "electricitymaps_api_token")
+        # Also check for old config name for backward compatibility
+        if (
+            not hasattr(self, "_electricitymaps_api_token")
+            or self._electricitymaps_api_token is None
+        ):
+            self._set_from_conf(_sentinel, "co2_signal_api_token", prevent_setter=True)
+            old_token = self._external_conf.get("co2_signal_api_token")
+            if old_token:
+                logger.warning(
+                    "Configuration parameter 'co2_signal_api_token' is deprecated. "
+                    "Please update your config to use 'electricitymaps_api_token' instead."
+                )
+                self._electricitymaps_api_token = old_token
+
         self._set_from_conf(emissions_endpoint, "emissions_endpoint")
         self._set_from_conf(experiment_name, "experiment_name", "base")
         self._set_from_conf(gpu_ids, "gpu_ids")
@@ -378,7 +406,7 @@ class BaseEmissionsTracker(ABC):
             self._conf["provider"] = cloud.provider
 
         self._emissions: Emissions = Emissions(
-            self._data_source, self._co2_signal_api_token
+            self._data_source, self._electricitymaps_api_token
         )
         self._init_output_methods(api_key=self._api_key)
 
@@ -956,7 +984,7 @@ class OfflineEmissionsTracker(BaseEmissionsTracker):
                              See https://github.com/mlco2/codecarbon/
                                         blob/master/codecarbon/data/cloud/impact.csv
                              for a list of cloud regions.
-        :param country_2letter_iso_code: For use with the CO2Signal emissions API.
+        :param country_2letter_iso_code: For use with the Electricity Maps emissions API.
                                          See http://api.electricitymap.org/v3/zones for
                                          a list of codes and their corresponding
                                          locations.
@@ -1095,7 +1123,10 @@ def track_emissions(
     emissions_endpoint: Optional[str] = _sentinel,
     experiment_id: Optional[str] = _sentinel,
     experiment_name: Optional[str] = _sentinel,
-    co2_signal_api_token: Optional[str] = _sentinel,
+    electricitymaps_api_token: Optional[str] = _sentinel,
+    co2_signal_api_token: Optional[
+        str
+    ] = _sentinel,  # Deprecated, use electricitymaps_api_token
     tracking_mode: Optional[str] = _sentinel,
     log_level: Optional[Union[int, str]] = _sentinel,
     on_csv_write: Optional[str] = _sentinel,
@@ -1150,8 +1181,9 @@ def track_emissions(
                                data.
     :param experiment_id: Id of the experiment.
     :param experiment_name: Label of the experiment
-    :param co2_signal_api_token: API token for co2signal.com (requires sign-up for
-                                 free beta)
+    :param electricitymaps_api_token: API token for electricitymaps.com (formerly co2signal.com)
+    :param co2_signal_api_token: [DEPRECATED] Use electricitymaps_api_token instead.
+                                 Old parameter name for backward compatibility.
     :param tracking_mode: One of "process" or "machine" in order to measure the
                           power consumption due to the entire machine or to try and
                           isolate the tracked processe's in isolation.
@@ -1180,7 +1212,7 @@ def track_emissions(
                          See https://github.com/mlco2/codecarbon/
                                             blob/master/codecarbon/data/cloud/impact.csv
                          for a list of cloud regions.
-    :param country_2letter_iso_code: For use with the CO2Signal emissions API.
+    :param country_2letter_iso_code: For use with the Electricity Maps emissions API.
                                      See http://api.electricitymap.org/v3/zones for
                                      a list of codes and their corresponding
                                      locations.
@@ -1199,6 +1231,17 @@ def track_emissions(
         @wraps(fn)
         def wrapped_fn(*args, **kwargs):
             fn_result = None
+
+            # Handle backward compatibility for co2_signal_api_token
+            _electricitymaps_token = electricitymaps_api_token
+            if co2_signal_api_token is not _sentinel:
+                logger.warning(
+                    "Parameter 'co2_signal_api_token' is deprecated and will be removed in a future version. "
+                    "Please use 'electricitymaps_api_token' instead."
+                )
+                if electricitymaps_api_token is _sentinel:
+                    _electricitymaps_token = co2_signal_api_token
+
             if offline and offline is not _sentinel:
                 if (country_iso_code is None or country_iso_code is _sentinel) and (
                     cloud_provider is None or cloud_provider is _sentinel
@@ -1217,7 +1260,7 @@ def track_emissions(
                     prometheus_url=prometheus_url,
                     output_handlers=output_handlers,
                     gpu_ids=gpu_ids,
-                    co2_signal_api_token=co2_signal_api_token,
+                    electricitymaps_api_token=_electricitymaps_token,
                     tracking_mode=tracking_mode,
                     log_level=log_level,
                     on_csv_write=on_csv_write,
@@ -1256,7 +1299,7 @@ def track_emissions(
                     emissions_endpoint=emissions_endpoint,
                     experiment_id=experiment_id,
                     experiment_name=experiment_name,
-                    co2_signal_api_token=co2_signal_api_token,
+                    electricitymaps_api_token=_electricitymaps_token,
                     tracking_mode=tracking_mode,
                     log_level=log_level,
                     on_csv_write=on_csv_write,

{codecarbon-3.1.0 → codecarbon-3.1.1}/codecarbon/output_methods/file.py

@@ -13,11 +13,29 @@ from codecarbon.output_methods.emissions_data import EmissionsData, TaskEmission
 class FileOutput(BaseOutput):
     """
     Saves experiment artifacts to a file
+
+    Attributes:
+        output_file_name: str, name of file to write to.
+        output_dir: str, path to directory to write to.
+        save_file_path: str, path to file to write to.
+        on_csv_write: str, "append" or "update", whether or not to append or overwrite a file if it exists.
     """
 
     def __init__(
         self, output_file_name: str, output_dir: str, on_csv_write: str = "append"
     ):
+        """
+        Initialize the FileOutput object.
+
+        Args:
+            output_file_name: name of file to write to.
+            output_dir: path to directory to write to.
+            on_csv_write: "append" or "update", whether or not to append or overwrite a file if it exists
+
+        Raises:
+            ValueError: If the on_csv_write value is invalid.
+            OSError: If the output directory does not exist.
+        """
         if on_csv_write not in {"append", "update"}:
             raise ValueError(
                 f"Unknown `on_csv_write` value: {on_csv_write}"
@@ -33,7 +51,16 @@ class FileOutput(BaseOutput):
             f"Emissions data (if any) will be saved to file {os.path.abspath(self.save_file_path)}"
         )
 
-    def has_valid_headers(self, data: EmissionsData):
+    def has_valid_headers(self, data: EmissionsData) -> bool:
+        """
+        Checks self.save_file_path has headers matching those from passed data.
+
+        Args:
+            data: EmissionsData object with valid headers.
+
+        Returns:
+            True if the file has valid headers, False otherwise.
+        """
         with open(self.save_file_path) as csv_file:
             csv_reader = csv.DictReader(csv_file)
             csv_entries_list = list(csv_reader)
@@ -44,11 +71,21 @@ class FileOutput(BaseOutput):
             list_of_column_names = list(dict_from_csv.keys())
             return list(data.values.keys()) == list_of_column_names
 
-    def out(self, total: EmissionsData, delta: EmissionsData):
+    def out(self, total: EmissionsData, _: EmissionsData):
         """
-        Save the emissions data to a CSV file.
-        If the file already exists, append the new data to it.
-        param `delta` is not used in this method.
+        Save the emissions data from a whole run to a CSV file.
+
+        * If the file does not exist, then create it.
+        * If the file already exists but has invalid headers, then back it up and replace with new data.
+        * If the file already exists and has valid headers:
+            * If it has no rows with a matching run ID, append the new data.
+            * If it has one row with a matching run ID, then replace that row with the new data.
+            * If it has > one row with a matching run ID, append the new data
+
+        Args:
+            total: data to save.
+
+
         """
         file_exists: bool = os.path.isfile(self.save_file_path)
         if file_exists and not self.has_valid_headers(total):
@@ -60,6 +97,10 @@ class FileOutput(BaseOutput):
             df = new_df
         elif self.on_csv_write == "append":
             df = pd.read_csv(self.save_file_path)
+            # Filter out empty or all-NA columns, to avoid warnings from Pandas,
+            # see https://github.com/pandas-dev/pandas/issues/55928
+            df = df.dropna(axis=1, how="all")
+            new_df = new_df.dropna(axis=1, how="all")
             df = pd.concat([df, new_df])
         else:
             df = pd.read_csv(self.save_file_path)
@@ -74,13 +115,22 @@ class FileOutput(BaseOutput):
                 )
                 df = pd.concat([df, new_df])
             else:
-                df.at[df.run_id == total.run_id, total.values.keys()] = (
-                    total.values.values()
+                update_values = {}
+                for col, val in dict(total.values).items():
+                    # Explicitly cast new values to prevent warnings about incompatible dtypes.
+                    update_values[col] = df[col].dtype.type(val)
+                df.loc[df.run_id == total.run_id, update_values.keys()] = (
+                    update_values.values()
                 )
 
         df.to_csv(self.save_file_path, index=False)
 
     def task_out(self, data: List[TaskEmissionsData], experiment_name: str):
+        """
+        Save the emissions data from a single task in an experiment run to a CSV file.
+
+        Does not attempt to backup existing files or prevent ovewritting them.
+        """
         run_id = data[0].run_id
         save_task_file_path = os.path.join(
             self.output_dir, "emissions_" + experiment_name + "_" + run_id + ".csv"
@@ -90,6 +140,8 @@ class FileOutput(BaseOutput):
             [dict(data_point.values) for data_point in data]
         )
         # Filter out empty or all-NA columns, to avoid warnings from Pandas
+        # see https://github.com/pandas-dev/pandas/issues/55928
+        df = df.dropna(axis=1, how="all")
         new_df = new_df.dropna(axis=1, how="all")
         df = pd.concat([df, new_df], ignore_index=True)
         df.to_csv(save_task_file_path, index=False)

{codecarbon-3.1.0 → codecarbon-3.1.1}/codecarbon.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codecarbon
-Version: 3.1.0
+Version: 3.1.1
 Author: Mila, DataForGood, BCG GAMMA, Comet.ml, Haverford College
 License-Expression: MIT
 Project-URL: Homepage, https://codecarbon.io/
@@ -220,7 +220,7 @@ In order to contribute a change to our code base, please submit a pull request (
 
 Check out our [contribution guidelines :arrow_upper_right:](https://github.com/mlco2/codecarbon/blob/master/CONTRIBUTING.md)
 
-Contact [@vict0rsch](https://github.com/vict0rsch) to be added to our slack workspace if you want to contribute regularly!
+Feel free to chat with us on [Discord](https://discord.gg/GS9js2XkJR).
 
 # How To Cite 📝
 
@@ -271,7 +271,11 @@ Here is a sample for BibTeX:
 
 # Contact 📝
 
-Maintainers are [@vict0rsch](https://github.com/vict0rsch) [@benoit-cty](https://github.com/benoit-cty) and [@SaboniAmine](https://github.com/saboniamine). Codecarbon is developed by volunteers from [**Mila**](http://mila.quebec) and the [**DataForGoodFR**](https://twitter.com/dataforgood_fr) community alongside donated professional time of engineers at [**Comet.ml**](https://comet.ml) and [**BCG GAMMA**](https://www.bcg.com/en-nl/beyond-consulting/bcg-gamma/default).
+Feel free to chat with us on [Discord](https://discord.gg/GS9js2XkJR).
+
+Codecarbon was formerly developed by volunteers from [**Mila**](http://mila.quebec) and the [**DataForGoodFR**](https://twitter.com/dataforgood_fr) community alongside donated professional time of engineers at [**Comet.ml**](https://comet.ml) and [**BCG GAMMA**](https://www.bcg.com/en-nl/beyond-consulting/bcg-gamma/default).
+
+Now CodeCarbon is supported by [**Code Carbon**](https://www.helloasso.com/associations/code-carbon), a French non-profit organization whose mission is to accelerate the development and adoption of CodeCarbon.
 
 ## Star History
 

{codecarbon-3.1.0 → codecarbon-3.1.1}/codecarbon.egg-info/SOURCES.txt

@@ -19,9 +19,9 @@ codecarbon/cli/main.py
 codecarbon/core/__init__.py
 codecarbon/core/api_client.py
 codecarbon/core/cloud.py
-codecarbon/core/co2_signal.py
 codecarbon/core/config.py
 codecarbon/core/cpu.py
+codecarbon/core/electricitymaps_api.py
 codecarbon/core/emissions.py
 codecarbon/core/gpu.py
 codecarbon/core/measure.py
@@ -71,12 +71,14 @@ codecarbon/viz/assets/tv_icon.png
 tests/test_api_call.py
 tests/test_cli.py
 tests/test_cloud.py
-tests/test_co2_signal.py
 tests/test_config.py
 tests/test_core_util.py
 tests/test_cpu.py
 tests/test_cpu_load.py
 tests/test_custom_handler.py
+tests/test_electricitymaps_api.py
+tests/test_electricitymaps_backward_compatibility.py
+tests/test_electricitymaps_config_backward_compatibility.py
 tests/test_emissions.py
 tests/test_emissions_tracker.py
 tests/test_emissions_tracker_constant.py

{codecarbon-3.1.0 → codecarbon-3.1.1}/pyproject.toml

@@ -165,7 +165,7 @@ docs = "cd docs/edit && make docs"
 carbonboard = "python codecarbon/viz/carbonboard.py"
 
 [tool.bumpver]
-current_version = "3.1.0"
+current_version = "3.1.1"
 version_pattern = "MAJOR.MINOR.PATCH[_TAGNUM]"
 
 [tool.bumpver.file_patterns]

{codecarbon-3.1.0 → codecarbon-3.1.1}/tests/test_config.py

@@ -183,7 +183,8 @@ class TestConfig(unittest.TestCase):
         ):
             with patch("os.path.exists", return_value=True):
                 tracker = EmissionsTracker(
-                    project_name="test-project", co2_signal_api_token="signal-token"
+                    project_name="test-project",
+                    electricitymaps_api_token="signal-token",
                 )
             self.assertEqual(tracker._measure_power_secs, 10)
             self.assertEqual(tracker._force_cpu_power, None)
@@ -191,7 +192,7 @@ class TestConfig(unittest.TestCase):
             self.assertEqual(tracker._output_dir, "/success/overwritten")
             self.assertEqual(tracker._emissions_endpoint, "http://testhost:2000")
             self.assertEqual(tracker._gpu_ids, ["0", "1"])
-            self.assertEqual(tracker._co2_signal_api_token, "signal-token")
+            self.assertEqual(tracker._electricitymaps_api_token, "signal-token")
             self.assertEqual(tracker._project_name, "test-project")
             self.assertTrue(tracker._save_to_file)
 

codecarbon-3.1.1/tests/test_electricitymaps_api.py

@@ -0,0 +1,45 @@
+import unittest
+
+import pytest
+import responses
+
+from codecarbon.core import electricitymaps_api
+from codecarbon.core.units import Energy
+from codecarbon.external.geography import GeoMetadata
+
+
+class TestElectricityMapsAPI(unittest.TestCase):
+    def setUp(self) -> None:
+        # GIVEN
+        self._energy = Energy.from_energy(kWh=10)
+        self._geo = GeoMetadata(
+            country_iso_code="FRA",
+            country_name="France",
+            region=None,
+            country_2letter_iso_code="FR",
+        )
+
+    @responses.activate
+    def test_get_emissions_RUNS(self):
+        responses.add(
+            responses.GET,
+            electricitymaps_api.URL,
+            json={
+                "zone": "FR",
+                "carbonIntensity": 58.765447504659946,
+                "datetime": "2025-11-21T19:00:00.000Z",
+                "updatedAt": "2025-11-21T19:09:54.950Z",
+            },
+            status=200,
+        )
+        result = electricitymaps_api.get_emissions(self._energy, self._geo)
+        assert round(result, 5) == 0.58765
+
+    @pytest.mark.integ_test
+    @unittest.skip("Skip real API call in regular test runs")
+    def test_get_emissions_with_api_key(self):
+        """Test with real API call using provided API key"""
+        api_key = "YOUR_REAL_API_KEY"
+        result = electricitymaps_api.get_emissions(self._energy, self._geo, api_key)
+        # Should return a positive emissions value
+        assert result > 0

codecarbon-3.1.1/tests/test_electricitymaps_backward_compatibility.py

@@ -0,0 +1,80 @@
+"""
+Tests for backward compatibility with deprecated parameter names.
+"""
+
+import unittest
+from unittest.mock import patch
+
+from codecarbon.core.emissions import Emissions
+from codecarbon.emissions_tracker import EmissionsTracker
+from codecarbon.input import DataSource
+
+
+class TestElectricityMapsBackwardCompatibility(unittest.TestCase):
+    """Test that old parameter names still work with deprecation warnings."""
+
+    def test_emissions_co2_signal_api_token_deprecated(self):
+        """Test that co2_signal_api_token still works in Emissions class."""
+        data_source = DataSource()
+
+        # Using the old parameter name should emit a warning
+        with self.assertLogs("codecarbon", level="WARNING") as log:
+            emissions = Emissions(data_source, co2_signal_api_token="test-token")
+
+        # Check that the token was set correctly
+        self.assertEqual(emissions._electricitymaps_api_token, "test-token")
+
+        # Check that a deprecation warning was logged
+        self.assertTrue(
+            any("deprecated" in message.lower() for message in log.output),
+            "Expected deprecation warning not found",
+        )
+
+    def test_emissions_new_parameter_takes_precedence(self):
+        """Test that new parameter takes precedence over old one."""
+        data_source = DataSource()
+
+        with self.assertLogs("codecarbon", level="WARNING"):
+            emissions = Emissions(
+                data_source,
+                electricitymaps_api_token="new-token",
+                co2_signal_api_token="old-token",
+            )
+
+        # New parameter should take precedence
+        self.assertEqual(emissions._electricitymaps_api_token, "new-token")
+
+    @patch("os.path.exists", return_value=True)
+    def test_tracker_co2_signal_api_token_deprecated(self, mock_exists):
+        """Test that co2_signal_api_token parameter works in EmissionsTracker."""
+
+        with self.assertLogs("codecarbon", level="WARNING") as log:
+            tracker = EmissionsTracker(co2_signal_api_token="test-token")
+
+        # Check that the token was set correctly
+        self.assertEqual(tracker._electricitymaps_api_token, "test-token")
+
+        # Check that a deprecation warning was logged
+        self.assertTrue(
+            any("deprecated" in message.lower() for message in log.output),
+            "Expected deprecation warning not found",
+        )
+
+    @patch("os.path.exists", return_value=True)
+    def test_tracker_new_parameter_takes_precedence(self, mock_exists):
+        """Test that new parameter takes precedence in EmissionsTracker."""
+
+        with self.assertLogs("codecarbon", level="WARNING") as log:
+            tracker = EmissionsTracker(
+                electricitymaps_api_token="new-token", co2_signal_api_token="old-token"
+            )
+
+        # New parameter should take precedence
+        self.assertEqual(tracker._electricitymaps_api_token, "new-token")
+
+        # Still should warn about using deprecated parameter
+        self.assertTrue(any("deprecated" in message.lower() for message in log.output))
+
+
+if __name__ == "__main__":
+    unittest.main()

codecarbon-3.1.1/tests/test_electricitymaps_config_backward_compatibility.py

@@ -0,0 +1,63 @@
+"""
+Test backward compatibility with configuration files using old parameter names.
+"""
+
+import unittest
+from textwrap import dedent
+from unittest.mock import patch
+
+from codecarbon.emissions_tracker import EmissionsTracker
+from tests.testutils import get_custom_mock_open
+
+
+class TestConfigBackwardCompatibility(unittest.TestCase):
+    """Test that old config parameter names still work."""
+
+    @patch("os.path.exists", return_value=True)
+    def test_old_config_parameter_name(self, mock_exists):
+        """Test that co2_signal_api_token in config file still works."""
+        config_with_old_name = dedent(
+            """\
+            [codecarbon]
+            co2_signal_api_token=old-config-token
+            """
+        )
+
+        with patch(
+            "builtins.open", new_callable=get_custom_mock_open(config_with_old_name, "")
+        ):
+            with self.assertLogs("codecarbon", level="WARNING") as log:
+                tracker = EmissionsTracker()
+
+            # Should use the token from config
+            self.assertEqual(tracker._electricitymaps_api_token, "old-config-token")
+
+            # Should warn about deprecated config parameter
+            self.assertTrue(
+                any("deprecated" in message.lower() for message in log.output),
+                "Expected deprecation warning for config parameter",
+            )
+
+    @patch("os.path.exists", return_value=True)
+    def test_new_config_parameter_takes_precedence(self, mock_exists):
+        """Test that new config parameter takes precedence over old one."""
+        config_with_both_names = dedent(
+            """\
+            [codecarbon]
+            electricitymaps_api_token=new-config-token
+            co2_signal_api_token=old-config-token
+            """
+        )
+
+        with patch(
+            "builtins.open",
+            new_callable=get_custom_mock_open(config_with_both_names, ""),
+        ):
+            tracker = EmissionsTracker()
+
+            # New parameter should take precedence
+            self.assertEqual(tracker._electricitymaps_api_token, "new-config-token")
+
+
+if __name__ == "__main__":
+    unittest.main()

codecarbon-3.1.0/codecarbon/_version.py

@@ -1 +0,0 @@
-__version__ = "3.1.0"

codecarbon-3.1.0/tests/test_co2_signal.py

@@ -1,47 +0,0 @@
-import unittest
-
-import pytest
-import requests
-import responses
-
-from codecarbon.core import co2_signal
-from codecarbon.core.units import Energy
-from codecarbon.external.geography import GeoMetadata
-
-
-class TestCO2Signal(unittest.TestCase):
-    def setUp(self) -> None:
-        # GIVEN
-        self._energy = Energy.from_energy(kWh=10)
-        self._geo = GeoMetadata(
-            country_iso_code="FRA",
-            country_name="France",
-            region=None,
-            country_2letter_iso_code="FR",
-        )
-
-    @responses.activate
-    def test_get_emissions_RUNS(self):
-        responses.add(
-            responses.GET,
-            co2_signal.URL,
-            json={
-                "status": "ok",
-                "countryCode": "FR",
-                "data": {
-                    "carbonIntensity": 58.765447504659946,
-                    "fossilFuelPercentage": 8.464454194205029,
-                },
-                "units": {"carbonIntensity": "gCO2eq/kWh"},
-            },
-            status=200,
-        )
-        result = co2_signal.get_emissions(self._energy, self._geo)
-        assert round(result, 5) == 0.58765
-
-    @pytest.mark.integ_test
-    def test_get_emissions_TIMEOUT(self):
-        with self.assertRaises(
-            (requests.exceptions.ConnectionError, requests.exceptions.ReadTimeout)
-        ):
-            co2_signal.get_emissions(self._energy, self._geo)