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

@@ -444,15 +444,15 @@ 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
 
  from aiida.orm import load_computer
  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())
 

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)

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