feat(annual): let a caller supply the storage backend to annual_cli.main()

StorageBase is already an abstraction — annual_weather.py and annual_tariff.py
only ever call self.storage.load()/save(), and AnnualPredictor takes whatever
storage it is given — but annual_cli.main() hard-coded StorageLocalFiles. The
only way to run the annual tool against a different backend was therefore to
fork the CLI, or to reimplement main() and with it the --machine stdout/stderr
contract, which is the fiddly part: the stdout redirect that stops a stray
print() from corrupting the one-JSON-object stdout a parent process parses.

main() now takes storage_factory, called as storage_factory(work_dir, log) —
exactly how StorageLocalFiles is constructed, so the default is that class
itself and the command line behaves as it always has.

The motivating case is embedding the annual tool in a long-lived service. There
a per-process work dir means every process re-downloads the same immutable ERA5
and Octopus data and none of it can be shared, which also multiplies requests
against the rate APIs. A shared backend (Redis, S3, a database) fixes both, and
now needs a factory rather than a fork.

Tests cover both paths: the default still constructs StorageLocalFiles, and a
supplied factory reaches AnnualPredictor and receives --work-dir and the run's
log callable. The new assertions were verified to fail without the change
(TypeError: unexpected keyword argument 'storage_factory'). The annual_cli,
annual_cli_machine, annual_cli_machine_end_to_end, annual_job and storage
suites all pass, and black 23.11.0 and ruff 0.11.4 (the pinned pre-commit
versions) report no changes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: 2 people

apps/predbat/annual_cli.py

@@ -150,8 +150,23 @@ def progress(completed, total, message):
     return progress
 
 
-def main(argv=None):
-    """Parse arguments, run the projection, and write the results. Returns an exit code."""
+def main(argv=None, storage_factory=StorageLocalFiles):
+    """Parse arguments, run the projection, and write the results. Returns an exit code.
+
+    ``storage_factory`` builds the ``StorageBase`` the run caches weather and tariff
+    downloads through, and is called as ``storage_factory(work_dir, log)`` - exactly how
+    ``StorageLocalFiles`` is constructed, so the default is that class itself and the
+    command line behaves as it always has.
+
+    It exists because ``StorageBase`` is already an abstraction (``annual_weather`` and
+    ``annual_tariff`` only ever call ``self.storage.load``/``save``), but this entry point
+    hard-coded the one implementation, so the only way to run the annual tool against a
+    different backend was to fork the CLI. A caller embedding the tool in a long-lived
+    service - where a per-process work dir means every process re-downloads the same
+    immutable ERA5 and Octopus data, and nothing can be shared between them - can now pass
+    a factory for their own backend and reuse everything else here, including the
+    ``--machine`` stdout/stderr contract, which is the fiddly part to reimplement.
+    """
     parser = argparse.ArgumentParser(description="Project a year of electricity costs using the Predbat engine")
     parser.add_argument("--config", required=True, help="Path to the annual prediction YAML config")
     parser.add_argument("--out", default=None, help="Write the results JSON to this path")
@@ -174,7 +189,7 @@ def main(argv=None):
     # process depends on. The default (non-machine) path keeps log=print unchanged.
     log = _stderr_log if args.machine else print
 
-    storage = StorageLocalFiles(args.work_dir, log)
+    storage = storage_factory(args.work_dir, log)
 
     # predictor.run() lazily imports the full Predbat engine (predbat.py) on its first call
     # to create_headless_predbat(); that module's top-level self-update check

apps/predbat/tests/test_annual_cli.py

@@ -16,6 +16,7 @@
 
 import annual_cli
 from annual_cli import format_table, make_progress
+from storage import StorageLocalFiles
 
 
 class _StubPredictor:
@@ -27,10 +28,12 @@ class _StubPredictor:
     """
 
     captured_log = None
+    captured_storage = None
 
     def __init__(self, config, log=None, storage=None, work_dir=None):
-        """Record the log callable and discard everything else."""
+        """Record the log callable and the storage, and discard everything else."""
         _StubPredictor.captured_log = log
+        _StubPredictor.captured_storage = storage
 
     async def run(self, progress=None):
         """Report one fake progress step (if asked) and return canned results."""
@@ -237,6 +240,59 @@ def test_annual_cli(my_predbat):
         print("  ERROR: --quiet should still construct AnnualPredictor with log=print, got {}".format(_StubPredictor.captured_log))
         failed = True
 
+    print("Test: storage_factory defaults to local files and is called with (work_dir, log)")
+    # The default must keep the command line behaving exactly as it did before the factory
+    # existed, so a plain run is still backed by StorageLocalFiles rooted at --work-dir.
+    original_predictor = annual_cli.AnnualPredictor
+    annual_cli.AnnualPredictor = _StubPredictor
+    with tempfile.TemporaryDirectory() as work_dir:
+        config_path = os.path.join(work_dir, "annual.yaml")
+        with open(config_path, "w") as handle:
+            handle.write("annual: {}\n")
+        try:
+            with redirect_stdout(io.StringIO()), redirect_stderr(io.StringIO()):
+                annual_cli.main(["--config", config_path, "--work-dir", os.path.join(work_dir, "work")])
+        finally:
+            annual_cli.AnnualPredictor = original_predictor
+
+    if not isinstance(_StubPredictor.captured_storage, StorageLocalFiles):
+        print("  ERROR: the default storage should be StorageLocalFiles, got {!r}".format(_StubPredictor.captured_storage))
+        failed = True
+
+    print("Test: a supplied storage_factory replaces it, receiving the work dir and log")
+    captured_args = {}
+
+    class _StubStorage:
+        """Records what main() hands the factory, standing in for a non-file backend."""
+
+    def _factory(work_dir, log):
+        captured_args["work_dir"] = work_dir
+        captured_args["log"] = log
+        return _StubStorage()
+
+    original_predictor = annual_cli.AnnualPredictor
+    annual_cli.AnnualPredictor = _StubPredictor
+    with tempfile.TemporaryDirectory() as work_dir:
+        config_path = os.path.join(work_dir, "annual.yaml")
+        with open(config_path, "w") as handle:
+            handle.write("annual: {}\n")
+        expected_work = os.path.join(work_dir, "work")
+        try:
+            with redirect_stdout(io.StringIO()), redirect_stderr(io.StringIO()):
+                annual_cli.main(["--config", config_path, "--work-dir", expected_work], storage_factory=_factory)
+        finally:
+            annual_cli.AnnualPredictor = original_predictor
+
+    if not isinstance(_StubPredictor.captured_storage, _StubStorage):
+        print("  ERROR: the supplied factory's storage should reach AnnualPredictor, got {!r}".format(_StubPredictor.captured_storage))
+        failed = True
+    if captured_args.get("work_dir") != expected_work:
+        print("  ERROR: the factory should receive --work-dir, got {!r}".format(captured_args.get("work_dir")))
+        failed = True
+    if captured_args.get("log") is not print:
+        print("  ERROR: the factory should receive the run's log callable, got {!r}".format(captured_args.get("log")))
+        failed = True
+
     return failed