feat(wait): one API call, and --finish-by

`find_green_window` fetched the forecast and then asked /latest for the
current intensity, a second HTTP call whose value only fed a "saves ~X%" line
and the --threshold short-circuit. The forecast's first point is that same
period, so use it and drop the call, the fallback and the try/except with it.

Add --finish-by as the complement to --deadline: --deadline bounds the start,
--finish-by bounds the end and is what most people mean. It is a subtraction,
not a second search path.

The Electricity Maps request extraction this branch used to carry now lives in
its base branch (#1358) where it belongs, so `clear_cooldown` is gone: request()
clears its own location's cooldown on a usable response.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: davidberenstein1957

codecarbon/cli/main.py

@@ -480,6 +480,12 @@ def wait(
         str,
         typer.Option(help="Maximum delay before the job must start."),
     ] = "12h",
+    finish_by: Annotated[
+        Optional[str],
+        typer.Option(
+            help="Latest acceptable finish time, e.g. '8h'. Overrides --deadline."
+        ),
+    ] = None,
     threshold: Annotated[
         Optional[float],
         typer.Option(help="gCO2e/kWh at or below which we start immediately."),
@@ -509,6 +515,7 @@ def wait(
         ctx,
         duration=duration,
         deadline=deadline,
+        finish_by=finish_by,
         threshold=threshold,
         dry_run=dry_run,
         log_level=log_level,

codecarbon/cli/wait.py

@@ -30,8 +30,12 @@ def find_green_window(
     deadline: timedelta,
     token: str | None,
 ):
-    """Return (start, intensity, now_intensity) or None when we should run now."""
-    from codecarbon.core import electricitymaps_api
+    """Return (start, intensity, now_intensity) or None when we should run now.
+
+    `now_intensity` is the first forecast point, i.e. the current period as the
+    forecast sees it. Asking the /latest endpoint for a live value instead
+    would be a second HTTP call for a number only used to print a percentage.
+    """
     from codecarbon.core.intensity_forecast import best_window, get_forecast
     from codecarbon.external.geography import GeoMetadata
     from codecarbon.input import DataSource
@@ -45,13 +49,7 @@ def find_green_window(
     if forecast is None:
         return None
 
-    try:
-        now_intensity = electricitymaps_api.get_carbon_intensity(geo, token or "")
-    except Exception as e:
-        # The forecast's first point is a stand-in, not the live value.
-        logger.debug(f"wait: current intensity unavailable ({e}), using the forecast.")
-        now_intensity = forecast.points[0].g_co2e_per_kwh
-
+    now_intensity = forecast.points[0].g_co2e_per_kwh
     now = datetime.now(timezone.utc)
     start, intensity = best_window(forecast, duration, deadline=now + deadline)
     return start, intensity, now_intensity
@@ -65,6 +63,7 @@ def wait_for_green_window(
     ctx: typer.Context,
     duration: str = "1h",
     deadline: str = "12h",
+    finish_by: str | None = None,
     threshold: float | None = None,
     dry_run: bool = False,
     log_level: str = "error",
@@ -91,7 +90,16 @@ def wait_for_green_window(
 
     try:
         job_duration = parse_duration(duration)
-        max_delay = parse_duration(deadline)
+        # --deadline bounds the start, --finish-by bounds the end; the search
+        # only ever needs the latest acceptable start.
+        if finish_by is not None:
+            max_delay = parse_duration(finish_by) - job_duration
+            if max_delay < timedelta(0):
+                raise ValueError(
+                    f"--finish-by {finish_by} is sooner than --duration {duration}."
+                )
+        else:
+            max_delay = parse_duration(deadline)
     except ValueError as e:
         print(f"ERROR: {e}", file=sys.stderr)
         raise typer.Exit(1)

codecarbon/core/intensity_forecast.py

@@ -9,7 +9,7 @@
 API backs off once for the whole process instead of once per caller. The
 forecast response itself is not cached: it is fetched once per `codecarbon
 wait` invocation, and its useful lifetime is nothing like the current
-intensity's five-minute TTL.
+intensity's short TTL.
 
 Once pluggable intensity providers land (see issue #1356), `get_forecast`
 should become an optional `forecast()` method on the provider protocol.
@@ -19,11 +19,7 @@
 from datetime import datetime, timedelta, timezone
 from typing import List, Optional, Tuple
 
-from codecarbon.core.electricitymaps_api import (
-    clear_cooldown,
-    location_params,
-    request,
-)
+from codecarbon.core.electricitymaps_api import location_params, request
 from codecarbon.external.geography import GeoMetadata
 from codecarbon.external.logger import logger
 
@@ -86,7 +82,6 @@ def get_forecast(
         if not points:
             raise ValueError("No usable forecast points in response")
 
-        clear_cooldown()
         return Forecast(
             zone=data.get("zone", ""),
             points=points,

docs/reference/cli.md

@@ -113,6 +113,7 @@ tracker only starts after the sleep, so a waiting process holds no lock.
 |--------|------|---------|-------------|
 | `--duration` | string | 1h | Expected job length, e.g. `90m`, `2h`, `1h30m`, or a plain number of seconds |
 | `--deadline` | string | 12h | Maximum delay before the job must start; the job itself may finish after it |
+| `--finish-by` | string | - | Latest acceptable *finish* time. Overrides `--deadline` with `--finish-by` minus `--duration` |
 | `--threshold` | float | - | gCO2e/kWh at or below which the job starts immediately, without waiting |
 | `--dry-run` | flag | false | Print the recommendation and exit without waiting or running |
 | `--measure-power-secs` | int | 10 | Interval between two measures |
@@ -128,6 +129,9 @@ codecarbon wait --deadline 12h --duration 2h -- python train.py
 
 # Start straight away if the grid is already below 100 gCO2e/kWh
 codecarbon wait --threshold 100 --deadline 6h -- bash benchmark.sh
+
+# The job must be finished within 8 hours, and takes about 2
+codecarbon wait --finish-by 8h --duration 2h -- python train.py
 ```
 
 The dry run prints the chosen window, for example:
@@ -153,7 +157,12 @@ straight away. The same applies when the forecast covers no complete window, or
 the greenest moment.
 
 `--deadline` bounds the *start* time, not the end: `--deadline 12h --duration 2h` considers every
-start in the next 12 hours, so the job may still be running 14 hours from now.
+start in the next 12 hours, so the job may still be running 14 hours from now. When you mean "this
+must be **done** by then", use `--finish-by` instead: `--finish-by 12h --duration 2h` searches
+starts in the next 10 hours. Passing a `--finish-by` shorter than `--duration` is an error.
+
+The `now:` figure in the output is the first point of the forecast, i.e. the current period as the
+forecast sees it, not a separate reading of the live grid — `wait` makes exactly one API call.
 
 ### `codecarbon detect`
 

tests/cli/test_wait.py

@@ -33,16 +33,12 @@ def no_network(monkeypatch):
     )
 
 
-def _patch_forecast(monkeypatch, values, now_intensity=None):
+def _patch_forecast(monkeypatch, values):
     now = datetime.now(timezone.utc)
     monkeypatch.setattr(
         "codecarbon.core.intensity_forecast.get_forecast",
         lambda geo, **kwargs: _forecast(values, now),
     )
-    monkeypatch.setattr(
-        "codecarbon.core.electricitymaps_api.get_carbon_intensity",
-        lambda geo, token="": values[0] if now_intensity is None else now_intensity,
-    )
 
 
 @pytest.mark.parametrize(
@@ -130,11 +126,14 @@ def test_threshold_short_circuits_the_wait(monkeypatch, capsys, no_network):
     assert "running now" in capsys.readouterr().out
 
 
-def test_threshold_uses_the_live_intensity_not_the_forecast(
-    monkeypatch, capsys, no_network
-):
-    # The first forecast point is above the threshold, the live grid is below.
-    _patch_forecast(monkeypatch, [300, 300, 100, 100], now_intensity=120)
+def test_no_second_call_for_the_current_intensity(monkeypatch, capsys, no_network):
+    # The first forecast point is the "now" value: fetching /latest as well
+    # would be a second HTTP call just to print a percentage.
+    _patch_forecast(monkeypatch, [120, 300, 50, 50])
+    monkeypatch.setattr(
+        "codecarbon.core.electricitymaps_api.get_carbon_intensity",
+        lambda *a, **k: pytest.fail("second live call"),
+    )
     monkeypatch.setattr(wait_module.time, "sleep", lambda s: pytest.fail("slept"))
     monkeypatch.setattr(
         "codecarbon.cli.monitor.run_and_monitor", lambda ctx, **kwargs: None
@@ -147,6 +146,31 @@ def test_threshold_uses_the_live_intensity_not_the_forecast(
     assert "running now" in capsys.readouterr().out
 
 
+def test_finish_by_bounds_the_end_not_the_start(monkeypatch, no_network):
+    # Trough at +4h, but the job must be done by +3h, so only a start at or
+    # before +2h is acceptable: the cheapest of those is +1h.
+    _patch_forecast(monkeypatch, [300, 100, 200, 200, 10, 10])
+    slept = []
+    monkeypatch.setattr(wait_module.time, "sleep", lambda s: slept.append(s))
+    monkeypatch.setattr(
+        "codecarbon.cli.monitor.run_and_monitor", lambda ctx, **kwargs: None
+    )
+
+    wait_module.wait_for_green_window(
+        SimpleNamespace(args=[]), duration="1h", finish_by="3h"
+    )
+
+    assert len(slept) == 1
+    assert 3600 - 60 < slept[0] <= 3600
+
+
+def test_finish_by_shorter_than_duration_is_rejected(monkeypatch, capsys, no_network):
+    with pytest.raises(typer.Exit):
+        wait_module.wait_for_green_window(
+            SimpleNamespace(args=[]), duration="4h", finish_by="1h"
+        )
+
+
 def test_only_the_leading_subcommand_name_is_stripped(monkeypatch, no_network):
     _patch_forecast(monkeypatch, [100, 300, 300])
     called = {}

tests/test_intensity_forecast.py

@@ -71,7 +71,11 @@ def test_no_token_returns_none_without_calling_api(self):
     def test_shared_cooldown_skips_the_request(self):
         # A failure on the current-intensity path must back the forecast off
         # too: no HTTP request, and still a None instead of a raise.
-        electricitymaps_api._start_cooldown()
+        electricitymaps_api._start_cooldown(
+            electricitymaps_api._cache_key(
+                electricitymaps_api.location_params(self._geo), "tok"
+            )
+        )
         responses.add(
             responses.GET,
             intensity_forecast.FORECAST_URL,