Switch from CO2Signal to ElectricityMaps

[benoit-cty]

Description

CO2 Signal was the previous name of Electricity Maps API. The url https://api.co2signal.com/v1/latest is no longer working so we need to migrate.

Related Issue

Please link to the issue this PR resolves: #979

Motivation and Context

The url https://api.co2signal.com/v1/latest is no longer working

How Has This Been Tested?

Use a test token.

Types of changes

What types of changes does your code introduce? Put an x in all the boxes that apply:

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

Go over all the following points, and put an x in all the boxes that apply.

• My code follows the code style of this project.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have read the CONTRIBUTING.md document.
• I have added tests to cover my changes.
• All new and existing tests passed.

[benoit-cty]

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:

# 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:

[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:

# 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.1: 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:

uv run pytest tests/test_backward_compatibility.py tests/test_config_backward_compatibility.py -v

[benoit-cty]

Doc has been updated :

I also made a test with an Electricity Maps API token.

[inimaz]

Nice! Thanks @benoit-cty . This will update it so users can input the new electricity maps token.
Some minor comments on the tests. But other than that great!

[inimaz]

LGTM!