ElectricityMaps_Backward_compatibility

benoit-cty · benoit-cty · commit eb76fc13e410 · 2025-11-21T20:40:19.000+01:00
diff --git a/codecarbon/core/emissions.py b/codecarbon/core/emissions.py
@@ -19,9 +19,24 @@
 
 class Emissions:
     def __init__(
-        self, data_source: DataSource, electricitymaps_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
+
+        # 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(
diff --git a/codecarbon/emissions_tracker.py b/codecarbon/emissions_tracker.py
@@ -172,6 +172,9 @@ def __init__(
         experiment_id: Optional[str] = _sentinel,
         experiment_name: 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,
@@ -222,6 +225,8 @@ def __init__(
         :param experiment_id: Id of the experiment.
         :param experiment_name: Label of the experiment
         :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.
@@ -267,7 +272,31 @@ def __init__(
         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")
+
+        # 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")
@@ -1095,6 +1124,9 @@ def track_emissions(
     experiment_id: Optional[str] = _sentinel,
     experiment_name: 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,6 +1182,8 @@ def track_emissions(
     :param experiment_id: Id of the experiment.
     :param experiment_name: Label of the experiment
     :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.
@@ -1197,6 +1231,17 @@ def _decorate(fn: Callable):
         @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
@@ -1215,7 +1260,7 @@ def wrapped_fn(*args, **kwargs):
                     prometheus_url=prometheus_url,
                     output_handlers=output_handlers,
                     gpu_ids=gpu_ids,
-                    electricitymaps_api_token=electricitymaps_api_token,
+                    electricitymaps_api_token=_electricitymaps_token,
                     tracking_mode=tracking_mode,
                     log_level=log_level,
                     on_csv_write=on_csv_write,
@@ -1254,7 +1299,7 @@ def wrapped_fn(*args, **kwargs):
                     emissions_endpoint=emissions_endpoint,
                     experiment_id=experiment_id,
                     experiment_name=experiment_name,
-                    electricitymaps_api_token=electricitymaps_api_token,
+                    electricitymaps_api_token=_electricitymaps_token,
                     tracking_mode=tracking_mode,
                     log_level=log_level,
                     on_csv_write=on_csv_write,
diff --git a/docs/edit/ElectricityMaps_Backward_compatibility.md b/docs/edit/ElectricityMaps_Backward_compatibility.md
@@ -0,0 +1,105 @@
+# Backward Compatibility for CO2 Signal → Electricity Maps Migration
+
+## Summary
+
+The API formerly known as CO2 Signal has been rebranded to Electricity Maps, and their API has been updated from v1 to v3. To maintain backward compatibility while adopting the new naming, we've implemented the following changes:
+
+## Parameter Renaming
+
+| Old Parameter Name | New Parameter Name | Status |
+|-------------------|-------------------|---------|
+| `co2_signal_api_token` | `electricitymaps_api_token` | Old name deprecated but still supported |
+| `CO2SignalAPIError` | `ElectricityMapsAPIError` | Old name removed |
+| `co2_signal` module | `electricitymaps_api` module | Old name removed |
+
+## Backward Compatibility Features
+
+### 1. Parameter Aliases
+
+The old parameter name `co2_signal_api_token` is still accepted in all APIs:
+
+```python
+# Both work, but the old name emits a deprecation warning
+tracker = EmissionsTracker(co2_signal_api_token="your-token")  # Deprecated
+tracker = EmissionsTracker(electricitymaps_api_token="your-token")  # Recommended
+```
+
+### 2. Configuration File Support
+
+Configuration files can use either the old or new parameter name:
+
+```ini
+[codecarbon]
+# Old name (deprecated, but still works)
+co2_signal_api_token=your-token
+
+# New name (recommended)
+electricitymaps_api_token=your-token
+```
+
+### 3. Deprecation Warnings
+
+When using the old parameter name, a warning is logged:
+
+```
+WARNING: Parameter 'co2_signal_api_token' is deprecated and will be removed in a future version. 
+Please use 'electricitymaps_api_token' instead.
+```
+
+## Migration Guide
+
+### For Users
+
+**No immediate action required.** Your existing code will continue to work, but you'll see deprecation warnings.
+
+To migrate:
+
+1. Replace `co2_signal_api_token` with `electricitymaps_api_token` in your code
+2. Update your `.codecarbon.config` files to use the new parameter name
+3. Update your environment variables from `CODECARBON_CO2_SIGNAL_API_TOKEN` to `CODECARBON_ELECTRICITYMAPS_API_TOKEN`
+
+Example migration:
+
+```python
+# Before
+from codecarbon import EmissionsTracker
+
+tracker = EmissionsTracker(
+    co2_signal_api_token="your-token"
+)
+
+# After
+from codecarbon import EmissionsTracker
+
+tracker = EmissionsTracker(
+    electricitymaps_api_token="your-token"
+)
+```
+
+### For Developers
+
+When both old and new parameters are provided:
+- The new parameter takes precedence
+- A deprecation warning is still emitted for the old parameter
+
+Implementation details:
+- `BaseEmissionsTracker.__init__()` handles the parameter migration
+- `Emissions.__init__()` handles the parameter migration for the core class
+- `track_emissions()` decorator handles the parameter migration
+- Configuration file reading checks both parameter names
+
+## Timeline
+
+- **v3.1.0**: New parameter introduced, old parameter deprecated
+- **v4.0.0** (planned): Old parameter will be removed
+
+## Testing
+
+Backward compatibility is tested in:
+- `tests/test_backward_compatibility.py` - Tests parameter aliases
+- `tests/test_config_backward_compatibility.py` - Tests configuration file support
+
+Run tests with:
+```bash
+uv run pytest tests/test_backward_compatibility.py tests/test_config_backward_compatibility.py -v
+```
diff --git a/tests/test_electricitymaps_backward_compatibility.py b/tests/test_electricitymaps_backward_compatibility.py
@@ -0,0 +1,84 @@
+"""
+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",
+        )
+
+        tracker.stop()
+
+    @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))
+
+        tracker.stop()
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/tests/test_electricitymaps_config_backward_compatibility.py b/tests/test_electricitymaps_config_backward_compatibility.py
@@ -0,0 +1,67 @@
+"""
+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",
+            )
+
+            tracker.stop()
+
+    @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")
+
+            tracker.stop()
+
+
+if __name__ == "__main__":
+    unittest.main()
