From 2ab82195b755cfc6d814439a72670632d2e025ff Mon Sep 17 00:00:00 2001
From: Sebastiaan Huber <mail@sphuber.net>
Date: Mon, 22 Jul 2024 09:16:08 +0200
Subject: [PATCH] `launch_shell_job`: Move `computer` to top-level of
 `metadata`

The `metadata` passed to the `launch_shell_job` is just supposed to
expose the same input of the `ShellJob` and essentially forward it.
However, the `computer` input was expected to be passed nested inside
the `options` namespace, even though it is defined as a top-level
metadata input. This makes the inputs for `launch_shell_job` dfifferent
from the `ShellJob` causing unnecessary confusion.

The `computer` input should now be specified as a top-level metadata
input for the `launch_shell_job` wrapper as well and passing it nested
inside the `metadata.options` is deprecated.
---
 docs/source/howto.rst     |  4 ++--
 src/aiida_shell/launch.py | 15 ++++++++++++++-
 tests/test_launch.py      | 11 +++++++++++
 3 files changed, 27 insertions(+), 3 deletions(-)

diff --git a/docs/source/howto.rst b/docs/source/howto.rst
index 7583083..e320d14 100644
--- a/docs/source/howto.rst
+++ b/docs/source/howto.rst
@@ -444,7 +444,7 @@ Defining a specific computer
 By default the shell command ran by ``launch_shell_job`` will be executed on the localhost, i.e., the computer where AiiDA is running.
 However, AiiDA also supports running commands on remote computers.
 See the `AiiDA's documentation <https://aiida.readthedocs.io/projects/aiida-core/en/latest/howto/run_codes.html#how-to-set-up-a-computer>`__ for instructions to setting up and configuring a remote computer.
-To specify what computer to use for a shell command, pass it as an option to the ``metadata`` keyword:
+To specify what computer to use for a shell command, pass it as a key to the ``metadata`` argument:
 
 .. code-block:: python
 
@@ -452,7 +452,7 @@ To specify what computer to use for a shell command, pass it as an option to the
     from aiida_shell import launch_shell_job
     results, node = launch_shell_job(
         'date',
-        metadata={'options': {'computer': load_computer('some-computer')}}
+        metadata={'computer': load_computer('some-computer')}
     )
     print(results['stdout'].get_content())
 
diff --git a/src/aiida_shell/launch.py b/src/aiida_shell/launch.py
index 99f91ce..e47a325 100644
--- a/src/aiida_shell/launch.py
+++ b/src/aiida_shell/launch.py
@@ -6,8 +6,10 @@
 import shlex
 import tempfile
 import typing as t
+import warnings
 
 from aiida.common import exceptions, lang
+from aiida.common.warnings import AiidaDeprecationWarning
 from aiida.engine import Process, WorkChain, launch
 from aiida.orm import AbstractCode, Computer, Data, ProcessNode, SinglefileData, load_code, load_computer
 
@@ -58,7 +60,18 @@ def launch_shell_job(  # noqa: PLR0913
         generated for each ``CalcJob`` and typically are not of interest to a user running ``launch_shell_job``. In
         order to not confuse them, these nodes are omitted, but they can always be accessed through the node.
     """
-    computer = (metadata or {}).get('options', {}).pop('computer', None)
+    metadata = metadata or {}
+    computer = metadata.get('options', {}).pop('computer', None)
+
+    if computer:
+        warnings.warn(
+            'Specifying a computer through `metadata.options.computer` in `launch_shell_job` is deprecated. Please use '
+            '`metadata.computer` instead.',
+            AiidaDeprecationWarning,
+            stacklevel=2,
+        )
+    else:
+        computer = metadata.pop('computer', None)
 
     if isinstance(command, str):
         code = prepare_code(command, computer, resolve_command)
diff --git a/tests/test_launch.py b/tests/test_launch.py
index c9da67b..3e04325 100644
--- a/tests/test_launch.py
+++ b/tests/test_launch.py
@@ -337,3 +337,14 @@ def test_preexisting_localhost_no_default_mpiprocs_per_machine(
         assert computer.get_default_mpiprocs_per_machine() is None
 
     Computer.collection.delete(computer.pk)
+
+
+def test_metadata_computer(generate_computer):
+    """Test the ``metadata.computer`` input."""
+    label = 'custom-computer'
+    computer = generate_computer(label=label)
+    assert computer.label == label
+
+    _, node = launch_shell_job('date', metadata={'computer': computer})
+    assert node.is_finished_ok
+    assert node.inputs.code.computer.uuid == computer.uuid