modAL 1.2.5.dev24__py3-none-any.whl → 1.2.5.dev25__py3-none-any.whl

modal/cli/shell.py

@@ -1,9 +1,9 @@
 # Copyright Modal Labs 2022
+import inspect
 import platform
 import shlex
-from functools import partial
 from pathlib import Path, PurePosixPath
-from typing import Optional
+from typing import Any, Callable, Optional
 
 import typer
 from click import ClickException
@@ -16,8 +16,10 @@ from ..functions import Function
 from ..image import Image
 from ..mount import _Mount
 from ..runner import interactive_shell
+from ..sandbox import Sandbox
 from ..secret import Secret
 from ..volume import Volume
+from .container import exec
 from .import_refs import (
     MethodReference,
     import_and_filter,
@@ -27,6 +29,171 @@ from .run import _get_runnable_list
 from .utils import ENV_OPTION, is_tty
 
 
+def _params_from_signature(
+    func: Callable[..., Any],
+) -> dict[str, typer.models.ParameterInfo]:
+    sig = inspect.signature(func)
+    params = {param_name: param.default for param_name, param in sig.parameters.items()}
+    assert all(isinstance(param, typer.models.ParameterInfo) for param in params.values()), (
+        f"All params to {func.__name__} must be of type typer.models.ParameterInfo."
+    )
+    return params
+
+
+def _passed_forbidden_args(
+    param_objs: dict[str, typer.models.ParameterInfo],
+    passed_args: dict[str, Any],
+    allowed: Callable[[str], bool],
+) -> list[str]:
+    """Check which forbidden arguments were passed with non-default values."""
+    passed_forbidden: list[str] = []
+    for param_name, param_obj in param_objs.items():
+        if allowed(param_name):
+            continue
+
+        assert param_obj.param_decls is not None, "All params must be typer.models.ParameterInfo, and have param_decls."
+
+        if passed_args.get(param_name) != param_obj.default:
+            passed_forbidden.append("/".join(param_obj.param_decls))
+
+    return passed_forbidden
+
+
+def _is_valid_modal_id(ref: str, prefix: str) -> bool:
+    assert prefix.endswith("-")
+    return ref.startswith(prefix) and len(ref[len(prefix) :]) > 0 and ref[len(prefix) :].isalnum()
+
+
+def _is_running_container_ref(ref: Optional[str]) -> bool:
+    if ref is None:
+        return False
+    return _is_valid_modal_id(ref, "sb-") or _is_valid_modal_id(ref, "ta-")
+
+
+def _start_shell_in_running_container(ref: str, cmd: str, pty: bool) -> None:
+    if _is_valid_modal_id(ref, "sb-"):
+        try:
+            sandbox = Sandbox.from_id(ref)
+            ref = sandbox._get_task_id()
+        except NotFoundError as e:
+            raise ClickException(f"Sandbox '{ref}' not found (is it still running?)")
+        except Exception as e:
+            raise ClickException(f"Error connecting to Sandbox '{ref}': {str(e)}")
+
+    assert _is_valid_modal_id(ref, "ta-")
+    try:
+        exec(container_id=ref, command=shlex.split(cmd), pty=pty)
+    except NotFoundError as e:
+        raise ClickException(f"Container '{ref}' not found (is it still running?)")
+    except Exception as e:
+        raise ClickException(f"Error connecting to container '{ref}': {str(e)}")
+
+
+def _function_spec_from_ref(ref: str, use_module_mode: bool) -> _FunctionSpec:
+    import_ref = parse_import_ref(ref, use_module_mode=use_module_mode)
+    runnable, all_usable_commands = import_and_filter(
+        import_ref, base_cmd="modal shell", accept_local_entrypoint=False, accept_webhook=True
+    )
+    if not runnable:
+        help_header = (
+            "Specify a Modal function to start a shell session for. E.g.\n"
+            f"> modal shell {import_ref.file_or_module}::my_function"
+        )
+
+        if all_usable_commands:
+            help_footer = f"The selected module '{import_ref.file_or_module}' has the following choices:\n\n"
+            help_footer += _get_runnable_list(all_usable_commands)
+        else:
+            help_footer = f"The selected module '{import_ref.file_or_module}' has no Modal functions or classes."
+
+        raise ClickException(f"{help_header}\n\n{help_footer}")
+
+    if isinstance(runnable, MethodReference):
+        # TODO: let users specify a class instead of a method, since they use the same environment
+        class_service_function = runnable.cls._get_class_service_function()
+        return class_service_function.spec
+    elif isinstance(runnable, Function):
+        return runnable.spec
+
+    raise ValueError("Referenced entity is not a Modal Function or Cls")
+
+
+def _start_shell_from_function_spec(
+    app: App,
+    cmds: list[str],
+    env: str,
+    timeout: int,
+    function_spec: _FunctionSpec,
+    pty: bool,
+) -> None:
+    interactive_shell(
+        app,
+        cmds=cmds,
+        environment_name=env,
+        timeout=timeout,
+        image=function_spec.image,
+        mounts=function_spec.mounts,
+        secrets=function_spec.secrets,
+        network_file_systems=function_spec.network_file_systems,
+        gpu=function_spec.gpus,
+        cloud=function_spec.cloud,
+        cpu=function_spec.cpu,
+        memory=function_spec.memory,
+        volumes=function_spec.volumes,
+        region=function_spec.scheduler_placement.regions if function_spec.scheduler_placement else None,
+        pty=pty,
+        proxy=function_spec.proxy,
+    )
+
+
+def _start_shell_from_image(
+    app: App,
+    cmds: list[str],
+    env: str,
+    timeout: int,
+    modal_image: Optional[Image],
+    volume: list[str],
+    secret: list[str],
+    add_local: list[str],
+    cpu: Optional[int],
+    memory: Optional[int],
+    gpu: Optional[str],
+    cloud: Optional[str],
+    region: Optional[str],
+    pty: bool,
+) -> None:
+    volumes = {f"/mnt/{vol}": Volume.from_name(vol) for vol in volume}
+    secrets = [Secret.from_name(s) for s in secret]
+
+    mounts = []
+    for local_path_str in add_local:
+        local_path = Path(local_path_str).expanduser().resolve()
+        remote_path = PurePosixPath(f"/mnt/{local_path.name}")
+
+        if local_path.is_dir():
+            m = _Mount._from_local_dir(local_path, remote_path=remote_path)
+        else:
+            m = _Mount._from_local_file(local_path, remote_path=remote_path)
+        mounts.append(m)
+
+    interactive_shell(
+        app,
+        cmds=cmds,
+        environment_name=env,
+        timeout=timeout,
+        image=modal_image,
+        mounts=mounts,
+        cpu=cpu,
+        memory=memory,
+        gpu=gpu,
+        cloud=cloud,
+        volumes=volumes,
+        secrets=secrets,
+        region=region.split(",") if region else [],
+        pty=pty,
+    )
+
+
 def shell(
     ref: Optional[str] = typer.Argument(
         default=None,
@@ -36,51 +203,59 @@ def shell(
         ),
     ),
     cmd: str = typer.Option("/bin/bash", "-c", "--cmd", help="Command to run inside the Modal image."),
-    env: str = ENV_OPTION,
+    env: Optional[str] = ENV_OPTION,
     image: Optional[str] = typer.Option(
-        default=None, help="Container image tag for inside the shell (if not using REF)."
+        None, "--image", help="Container image tag for inside the shell (if not using REF)."
     ),
-    add_python: Optional[str] = typer.Option(default=None, help="Add Python to the image (if not using REF)."),
+    add_python: Optional[str] = typer.Option(None, "--add-python", help="Add Python to the image (if not using REF)."),
     volume: Optional[list[str]] = typer.Option(
-        default=None,
+        None,
+        "--volume",
         help=(
             "Name of a `modal.Volume` to mount inside the shell at `/mnt/{name}` (if not using REF)."
             " Can be used multiple times."
         ),
     ),
     add_local: Optional[list[str]] = typer.Option(
-        default=None,
+        None,
+        "--add-local",
         help=(
             "Local file or directory to mount inside the shell at `/mnt/{basename}` (if not using REF)."
             " Can be used multiple times."
         ),
     ),
     secret: Optional[list[str]] = typer.Option(
-        default=None,
+        None,
+        "--secret",
         help=("Name of a `modal.Secret` to mount inside the shell (if not using REF). Can be used multiple times."),
     ),
-    cpu: Optional[int] = typer.Option(default=None, help="Number of CPUs to allocate to the shell (if not using REF)."),
+    cpu: Optional[int] = typer.Option(
+        None, "--cpu", help="Number of CPUs to allocate to the shell (if not using REF)."
+    ),
     memory: Optional[int] = typer.Option(
-        default=None, help="Memory to allocate for the shell, in MiB (if not using REF)."
+        None, "--memory", help="Memory to allocate for the shell, in MiB (if not using REF)."
     ),
     gpu: Optional[str] = typer.Option(
-        default=None,
+        None,
+        "--gpu",
         help="GPUs to request for the shell, if any. Examples are `any`, `a10g`, `a100:4` (if not using REF).",
     ),
     cloud: Optional[str] = typer.Option(
-        default=None,
+        None,
+        "--cloud",
         help=(
             "Cloud provider to run the shell on. Possible values are `aws`, `gcp`, `oci`, `auto` (if not using REF)."
         ),
     ),
     region: Optional[str] = typer.Option(
-        default=None,
+        None,
+        "--region",
         help=(
             "Region(s) to run the container on. "
             "Can be a single region or a comma-separated list to choose from (if not using REF)."
         ),
     ),
-    pty: Optional[bool] = typer.Option(default=None, help="Run the command using a PTY."),
+    pty: Optional[bool] = typer.Option(None, "--pty", help="Run the command using a PTY."),
     use_module_mode: bool = typer.Option(
         False, "-m", help="Interpret argument as a Python module path instead of a file/script path"
     ),
@@ -127,111 +302,74 @@ def shell(
     modal shell sb-abc123xyz
     ```
     """
-    env = ensure_env(env)
-
     if pty is None:
         pty = is_tty()
 
     if platform.system() == "Windows":
         raise InvalidError("`modal shell` is currently not supported on Windows")
 
+    param_objs = _params_from_signature(shell)
+
+    if ref is not None and _is_running_container_ref(ref):
+        # We're attaching to an already running container or Sandbox.
+        if passed_forbidden := _passed_forbidden_args(
+            param_objs, locals(), allowed=lambda p: p in {"cmd", "pty", "ref"}
+        ):
+            raise ClickException(
+                f"Cannot specify container configuration arguments ({', '.join(passed_forbidden)}) "
+                f"when attaching to an already running container or Sandbox ('{ref}')."
+            )
+
+        _start_shell_in_running_container(ref, cmd, pty)
+        return
+
+    # We're not attaching to an existing container, so we need to create a new one.
+    env = ensure_env(env)
     app = App("modal shell")
 
-    if ref is not None:
-        # `modal shell` with a sandbox ID gets the task_id, that's then handled by the `ta-*` flow below.
-        if ref.startswith("sb-") and len(ref[3:]) > 0 and ref[3:].isalnum():
-            from ..sandbox import Sandbox
-
-            try:
-                sandbox = Sandbox.from_id(ref)
-                task_id = sandbox._get_task_id()
-                ref = task_id
-            except NotFoundError as e:
-                raise ClickException(f"Sandbox '{ref}' not found")
-            except Exception as e:
-                raise ClickException(f"Error connecting to sandbox '{ref}': {str(e)}")
-
-        # `modal shell` with a container ID is a special case, alias for `modal container exec`.
-        if ref.startswith("ta-") and len(ref[3:]) > 0 and ref[3:].isalnum():
-            from .container import exec
-
-            exec(container_id=ref, command=shlex.split(cmd), pty=pty)
-            return
-
-        import_ref = parse_import_ref(ref, use_module_mode=use_module_mode)
-        runnable, all_usable_commands = import_and_filter(
-            import_ref, base_cmd="modal shell", accept_local_entrypoint=False, accept_webhook=True
-        )
-        if not runnable:
-            help_header = (
-                "Specify a Modal function to start a shell session for. E.g.\n"
-                f"> modal shell {import_ref.file_or_module}::my_function"
+    # NB: invoking under bash makes --cmd a lot more flexible.
+    cmds = shlex.split(f'/bin/bash -c "{cmd}"')
+    timeout = 3600
+
+    if ref is not None and not _is_valid_modal_id(ref, "im-"):
+        # If ref it not a Modal Image ID, then it's a function reference, and we'll start a new container from its spec.
+        if passed_forbidden := _passed_forbidden_args(
+            param_objs, locals(), allowed=lambda p: p in {"cmd", "env", "pty", "ref", "use_module_mode"}
+        ):
+            raise ClickException(
+                f"Cannot specify container configuration arguments ({', '.join(passed_forbidden)}) "
+                f"when starting a new container from a function reference ('{ref}')."
             )
 
-            if all_usable_commands:
-                help_footer = f"The selected module '{import_ref.file_or_module}' has the following choices:\n\n"
-                help_footer += _get_runnable_list(all_usable_commands)
-            else:
-                help_footer = f"The selected module '{import_ref.file_or_module}' has no Modal functions or classes."
-
-            raise ClickException(f"{help_header}\n\n{help_footer}")
-
-        function_spec: _FunctionSpec
-        if isinstance(runnable, MethodReference):
-            # TODO: let users specify a class instead of a method, since they use the same environment
-            class_service_function = runnable.cls._get_class_service_function()
-            function_spec = class_service_function.spec
-        elif isinstance(runnable, Function):
-            function_spec = runnable.spec
-        else:
-            raise ValueError("Referenced entity is not a Modal function or class")
-
-        start_shell = partial(
-            interactive_shell,
-            image=function_spec.image,
-            mounts=function_spec.mounts,
-            secrets=function_spec.secrets,
-            network_file_systems=function_spec.network_file_systems,
-            gpu=function_spec.gpus,
-            cloud=function_spec.cloud,
-            cpu=function_spec.cpu,
-            memory=function_spec.memory,
-            volumes=function_spec.volumes,
-            region=function_spec.scheduler_placement.regions if function_spec.scheduler_placement else None,
-            pty=pty,
-            proxy=function_spec.proxy,
-        )
+        function_spec = _function_spec_from_ref(ref, use_module_mode)
+        _start_shell_from_function_spec(app, cmds, env, timeout, function_spec, pty)
+        return
+
+    if ref is not None and _is_valid_modal_id(ref, "im-"):
+        if passed_forbidden := _passed_forbidden_args(
+            param_objs, locals(), allowed=lambda p: p not in {"add_python", "image"}
+        ):
+            raise ClickException(
+                f"Cannot specify {', '.join(passed_forbidden)} argument(s) "
+                f"when starting a new container from a Modal Image ID ('{ref}')."
+            )
+        modal_image = Image.from_id(ref)
     else:
         modal_image = Image.from_registry(image, add_python=add_python) if image else None
-        volumes = {} if volume is None else {f"/mnt/{vol}": Volume.from_name(vol) for vol in volume}
-        secrets = [] if secret is None else [Secret.from_name(s) for s in secret]
-
-        mounts = []
-        if add_local:
-            for local_path_str in add_local:
-                local_path = Path(local_path_str).expanduser().resolve()
-                remote_path = PurePosixPath(f"/mnt/{local_path.name}")
-
-                if local_path.is_dir():
-                    m = _Mount._from_local_dir(local_path, remote_path=remote_path)
-                else:
-                    m = _Mount._from_local_file(local_path, remote_path=remote_path)
-                mounts.append(m)
-
-        start_shell = partial(
-            interactive_shell,
-            image=modal_image,
-            mounts=mounts,
-            cpu=cpu,
-            memory=memory,
-            gpu=gpu,
-            cloud=cloud,
-            volumes=volumes,
-            secrets=secrets,
-            region=region.split(",") if region else [],
-            pty=pty,
-        )
 
-    # NB: invoking under bash makes --cmd a lot more flexible.
-    cmds = shlex.split(f'/bin/bash -c "{cmd}"')
-    start_shell(app, cmds=cmds, environment_name=env, timeout=3600)
+    _start_shell_from_image(
+        app,
+        cmds,
+        env,
+        timeout,
+        modal_image,
+        volume or [],
+        secret or [],
+        add_local or [],
+        cpu,
+        memory,
+        gpu,
+        cloud,
+        region,
+        pty,
+    )

modal/client.pyi

@@ -32,7 +32,7 @@ class _Client:
         server_url: str,
         client_type: int,
         credentials: typing.Optional[tuple[str, str]],
-        version: str = "1.2.5.dev24",
+        version: str = "1.2.5.dev25",
     ):
         """mdmd:hidden
         The Modal client object is not intended to be instantiated directly by users.
@@ -163,7 +163,7 @@ class Client:
         server_url: str,
         client_type: int,
         credentials: typing.Optional[tuple[str, str]],
-        version: str = "1.2.5.dev24",
+        version: str = "1.2.5.dev25",
     ):
         """mdmd:hidden
         The Modal client object is not intended to be instantiated directly by users.

{modal-1.2.5.dev24.dist-info → modal-1.2.5.dev25.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: modal
-Version: 1.2.5.dev24
+Version: 1.2.5.dev25
 Summary: Python client library for Modal
 Author-email: Modal Labs <support@modal.com>
 License: Apache-2.0

{modal-1.2.5.dev24.dist-info → modal-1.2.5.dev25.dist-info}/RECORD

@@ -26,7 +26,7 @@ modal/app.pyi,sha256=nI_Tibj-rI5I7dJFJnczbHvcmVzCvvCih0tMzoQlr_Y,50835
 modal/billing.py,sha256=zmQ3bcCJlwa4KD1IA_QgdWpm1pn13c-7qfy79iEauYI,195
 modal/call_graph.py,sha256=1g2DGcMIJvRy-xKicuf63IVE98gJSnQsr8R_NVMptNc,2581
 modal/client.py,sha256=k1CqQ_0t4-vHylkqYZgYCnClg-FT0QrTPAKivL01A_k,14354
-modal/client.pyi,sha256=JX95R72YyYt-ILECQ0kaLmLTunhGjbW0FE46mNfLLl8,13148
+modal/client.pyi,sha256=4ayE1w6tzXcr1vPAhMLYEP8JthQBFrE4PyI0Agy9YJM,13148
 modal/cloud_bucket_mount.py,sha256=cvVj5Rt4nDHoQbTneoJPTaAcnl_Ab_mrsjnnzd0v9OI,6013
 modal/cloud_bucket_mount.pyi,sha256=vXusGMOUk9HjCs4lhxteuCK4xLQclPfugGWKo7LECEA,7539
 modal/cls.py,sha256=4T__mtYlQUnkatif1Wnr8Ld9DN_ySydHj2UwhRg89ok,41984
@@ -147,7 +147,7 @@ modal/cli/profile.py,sha256=g8X6tFFK9ccKyu2he9Yu19WLSLNdztzECgmIV__XJFs,3257
 modal/cli/queues.py,sha256=S5dqk6lEd_2fJolHqoN9iRs6EkeTa0k7KqJWBBGS23k,6170
 modal/cli/run.py,sha256=Uftci2utrO6HJH4-JS_gRuy-d5Dfpt-PcXbc_JkiRVY,18378
 modal/cli/secret.py,sha256=zkCztov8c4x8CI8G0EoyieUfv9XLQQtVXV8xeMLK-Os,8044
-modal/cli/shell.py,sha256=SllhtMrxrGCjJcS5wlHGFUSRwGoKNepKcPqdfNsISt4,8660
+modal/cli/shell.py,sha256=L5Dw8yeuu9-f6vNlBGbUT4oh9AVSK4GuB5J6m6vYLBk,12613
 modal/cli/token.py,sha256=NAmQzKBfEHkcldWKeFxAVIqQBoo1RTp7_A4yc7-8qM0,1911
 modal/cli/utils.py,sha256=aUXDU9_VgcJrGaGRy4bGf4dqwKYXHCpoO27x4m_bpuo,3293
 modal/cli/volume.py,sha256=wJchJyIEw9lTKiNUNTgR4I3DPYHYJBu50gU_SsecP0w,10877
@@ -160,7 +160,7 @@ modal/experimental/__init__.py,sha256=GOuo3t4-Le0ZVddiHIOw0MQxkdTJge-bVbhDvgnblm
 modal/experimental/flash.py,sha256=GJZwSr-4OHlP6gCIZdcbsSb8D8WX9xJwMphjwcfsRoU,31262
 modal/experimental/flash.pyi,sha256=q4a3mdgL0jzATPL2tS7LpuyulYzF1vUSE453S9xc8n8,16965
 modal/experimental/ipython.py,sha256=TrCfmol9LGsRZMeDoeMPx3Hv3BFqQhYnmD_iH0pqdhk,2904
-modal-1.2.5.dev24.dist-info/licenses/LICENSE,sha256=psuoW8kuDP96RQsdhzwOqi6fyWv0ct8CR6Jr7He_P_k,10173
+modal-1.2.5.dev25.dist-info/licenses/LICENSE,sha256=psuoW8kuDP96RQsdhzwOqi6fyWv0ct8CR6Jr7He_P_k,10173
 modal_docs/__init__.py,sha256=svYKtV8HDwDCN86zbdWqyq5T8sMdGDj0PVlzc2tIxDM,28
 modal_docs/gen_cli_docs.py,sha256=c1yfBS_x--gL5bs0N4ihMwqwX8l3IBWSkBAKNNIi6bQ,3801
 modal_docs/gen_reference_docs.py,sha256=d_CQUGQ0rfw28u75I2mov9AlS773z9rG40-yq5o7g2U,6359
@@ -188,10 +188,10 @@ modal_proto/task_command_router_pb2.py,sha256=_pD2ZpU0bNzhwBdzmLoLyLtAtftI_Agxwn
 modal_proto/task_command_router_pb2.pyi,sha256=EyDgXPLr7alqjXYERV8w_MPuO404x0uCppmSkrfE9IE,14589
 modal_proto/task_command_router_pb2_grpc.py,sha256=uEQ0HdrCp8v-9bB5yIic9muA8spCShLHY6Bz9cCgOUE,10114
 modal_proto/task_command_router_pb2_grpc.pyi,sha256=s3Yxsrawdj4nr8vqQqsAxyX6ilWaGbdECy425KKbLIA,3301
-modal_version/__init__.py,sha256=SHHQC5xr-U7-6iEfX2brvTGLLIV9ISS6rXBSGfoZDd8,121
+modal_version/__init__.py,sha256=-etaRaNaDPMtSgduiHoS1BHtJ-b3tv_L-BwSmNQoxks,121
 modal_version/__main__.py,sha256=2FO0yYQQwDTh6udt1h-cBnGd1c4ZyHnHSI4BksxzVac,105
-modal-1.2.5.dev24.dist-info/METADATA,sha256=TRrHXpW966lipczKqKoGqKp5GIWLrjQnyROIhOQPJzA,2490
-modal-1.2.5.dev24.dist-info/WHEEL,sha256=1tXe9gY0PYatrMPMDd6jXqjfpz_B-Wqm32CPfRC58XU,91
-modal-1.2.5.dev24.dist-info/entry_points.txt,sha256=An-wYgeEUnm6xzrAP9_NTSTSciYvvEWsMZILtYrvpAI,46
-modal-1.2.5.dev24.dist-info/top_level.txt,sha256=4BWzoKYREKUZ5iyPzZpjqx4G8uB5TWxXPDwibLcVa7k,43
-modal-1.2.5.dev24.dist-info/RECORD,,
+modal-1.2.5.dev25.dist-info/METADATA,sha256=evkNwlrHZZRwWDDf-FLWtLJ9yn81nse_iGMzgZIXuwA,2490
+modal-1.2.5.dev25.dist-info/WHEEL,sha256=1tXe9gY0PYatrMPMDd6jXqjfpz_B-Wqm32CPfRC58XU,91
+modal-1.2.5.dev25.dist-info/entry_points.txt,sha256=An-wYgeEUnm6xzrAP9_NTSTSciYvvEWsMZILtYrvpAI,46
+modal-1.2.5.dev25.dist-info/top_level.txt,sha256=4BWzoKYREKUZ5iyPzZpjqx4G8uB5TWxXPDwibLcVa7k,43
+modal-1.2.5.dev25.dist-info/RECORD,,

modal_version/__init__.py

@@ -1,4 +1,4 @@
 # Copyright Modal Labs 2025
 """Supplies the current version of the modal client library."""
 
-__version__ = "1.2.5.dev24"
+__version__ = "1.2.5.dev25"