modal 1.4.3.dev10__tar.gz → 1.4.3.dev12__tar.gz

{modal-1.4.3.dev10 → modal-1.4.3.dev12}/PKG-INFO

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

{modal-1.4.3.dev10 → modal-1.4.3.dev12}/modal/_runtime/execution_context.py

@@ -10,10 +10,13 @@ from .container_io_manager import _ContainerIOManager
 
 
 def is_local() -> bool:
-    """Returns if we are currently on the machine launching/deploying a Modal app
+    """Indicate the execution context of the current process.
+
+    Note: this function specifically returns False when the current process is
+    running a Modal Function and True in all other cases. It will return True
+    when called from a child process of a Function or inside a Modal Sandbox,
+    even though those processes are running on Modal hardware.
 
-    Returns `True` when executed locally on the user's machine.
-    Returns `False` when executed from a Modal container in the cloud.
     """
     return not _ContainerIOManager._singleton
 

{modal-1.4.3.dev10 → modal-1.4.3.dev12}/modal/_runtime/execution_context.pyi

@@ -4,10 +4,12 @@ import typing
 import typing_extensions
 
 def is_local() -> bool:
-    """Returns if we are currently on the machine launching/deploying a Modal app
+    """Indicate the execution context of the current process.
 
-    Returns `True` when executed locally on the user's machine.
-    Returns `False` when executed from a Modal container in the cloud.
+    Note: this function specifically returns False when the current process is
+    running a Modal Function and True in all other cases. It will return True
+    when called from a child process of a Function or inside a Modal Sandbox,
+    even though those processes are running on Modal hardware.
     """
     ...
 

{modal-1.4.3.dev10 → modal-1.4.3.dev12}/modal/_utils/sandbox_fs_utils.py

@@ -255,6 +255,36 @@ def make_make_directory_command(remote_path: str, create_parents: bool) -> str:
     return json.dumps({"MakeDirectory": {"path": remote_path, "parents": create_parents}})
 
 
+def raise_stat_error(returncode: int, stderr: Union[str, bytes], remote_path: str) -> NoReturn:
+    if payload := try_parse_error_payload(stderr):
+        logger.debug(
+            f"sandbox-fs-tools stat error: path={remote_path}, "
+            f"error_kind={payload.error_kind}, message={payload.message}, detail={payload.detail}"
+        )
+        if payload.error_kind == "NotFound":
+            raise SandboxFilesystemNotFoundError(f"{payload.message}: {remote_path}")
+        if payload.error_kind == "NotDirectory":
+            raise SandboxFilesystemNotADirectoryError(f"{payload.message}: {remote_path}")
+        if payload.error_kind == "PermissionDenied":
+            raise SandboxFilesystemPermissionError(f"{payload.message}: {remote_path}")
+        raise SandboxFilesystemError(payload.message)
+
+    if stderr_text := _stderr_to_text(stderr):
+        logger.debug(f"Unstructured modal-sandbox-fs-tools stderr: {stderr_text}")
+    raise SandboxFilesystemError(f"Operation on '{remote_path}' failed with exit code {returncode}")
+
+
+def make_stat_command(remote_path: str) -> str:
+    """Build the JSON command string for a Stat operation.
+
+    The returned JSON must match the `Command` enum in the modal-sandbox-fs-tools
+    Rust crate (crates/modal-sandbox-fs-tools/src/lib.rs). Treat changes to
+    this schema like protobuf changes: fields must not be removed or renamed,
+    only added with backwards-compatible defaults.
+    """
+    return json.dumps({"Stat": {"path": remote_path}})
+
+
 def validate_absolute_remote_path(remote_path: str, operation: str) -> None:
     if not PurePosixPath(remote_path).is_absolute():
         raise InvalidError(f"Sandbox.filesystem.{operation}() currently only supports absolute remote_path values")

{modal-1.4.3.dev10 → modal-1.4.3.dev12}/modal/app.py

@@ -379,6 +379,7 @@ class _App:
     async def run(
         self,
         *,
+        name: Optional[str] = None,
         client: Optional[_Client] = None,
         detach: bool = False,
         interactive: bool = False,
@@ -426,7 +427,7 @@ class _App:
         from .runner import _run_app  # Defer import of runner.py, which imports a lot from Rich
 
         async with _run_app(
-            self, client=client, detach=detach, interactive=interactive, environment_name=environment_name
+            self, name=name, client=client, detach=detach, interactive=interactive, environment_name=environment_name
         ):
             yield self
 

{modal-1.4.3.dev10 → modal-1.4.3.dev12}/modal/app.pyi

@@ -256,6 +256,7 @@ class _App:
     def run(
         self,
         *,
+        name: typing.Optional[str] = None,
         client: typing.Optional[modal.client._Client] = None,
         detach: bool = False,
         interactive: bool = False,
@@ -864,6 +865,7 @@ class App:
             self,
             /,
             *,
+            name: typing.Optional[str] = None,
             client: typing.Optional[modal.client.Client] = None,
             detach: bool = False,
             interactive: bool = False,
@@ -913,6 +915,7 @@ class App:
             self,
             /,
             *,
+            name: typing.Optional[str] = None,
             client: typing.Optional[modal.client.Client] = None,
             detach: bool = False,
             interactive: bool = False,

{modal-1.4.3.dev10 → modal-1.4.3.dev12}/modal/cli/_help.py

@@ -5,11 +5,12 @@ from __future__ import annotations
 
 import inspect
 import os
+import shutil
 import sys
 from typing import Any, Optional
 
 import click
-from rich.console import Console
+from rich.console import Console, Group, RenderableType
 from rich.markdown import Markdown
 from rich.padding import Padding
 from rich.panel import Panel
@@ -24,6 +25,7 @@ _OPTION_METAVAR_STYLE = "dim"
 _ERROR_STYLE = "red"
 
 _MAX_HELP_WIDTH = 80
+_HELP_PADDING = 1
 
 
 def use_rich_style() -> bool:
@@ -34,25 +36,24 @@ def use_rich_style() -> bool:
     return sys.stdout.isatty()
 
 
-def _make_console(file: Optional[Any] = None) -> Console:
-    return Console(file=file, highlight=False)
+def _make_help_console() -> Console:
+    columns, _ = shutil.get_terminal_size()
+    return Console(highlight=False, width=min(_MAX_HELP_WIDTH, columns))
 
 
-def _render_usage(cmd: click.Command, ctx: click.Context, console: Console) -> None:
+def _build_usage(cmd: click.Command, ctx: click.Context) -> RenderableType:
     pieces = " ".join(cmd.collect_usage_pieces(ctx))
     usage = Text()
     usage.append("Usage: ", style=_HEADING_STYLE)
     usage.append(f"{ctx.command_path} {pieces}".rstrip())
-    console.print(usage)
-    console.print()
+    return usage
 
 
-def _render_help_text(cmd: click.Command, console: Console) -> None:
+def _build_help_text(cmd: click.Command) -> Optional[RenderableType]:
     text = cmd.help or cmd.short_help or ""
     if not text:
-        return
-    console.print(Padding(Markdown(inspect.cleandoc(text)), (0, 2)))
-    console.print()
+        return None
+    return Markdown(inspect.cleandoc(text))
 
 
 def _option_label(param: click.Parameter, ctx: click.Context) -> Text:
@@ -73,7 +74,7 @@ def _option_label(param: click.Parameter, ctx: click.Context) -> Text:
     return text
 
 
-def _render_options(cmd: click.Command, ctx: click.Context, console: Console) -> None:
+def _build_options(cmd: click.Command, ctx: click.Context) -> Optional[RenderableType]:
     rows: list[tuple[Text, str]] = []
     for param in cmd.get_params(ctx):
         rec = param.get_help_record(ctx)
@@ -81,22 +82,20 @@ def _render_options(cmd: click.Command, ctx: click.Context, console: Console) ->
             continue
         rows.append((_option_label(param, ctx), rec[1] or ""))
     if not rows:
-        return
+        return None
 
-    console.print(Text("Options", style=_HEADING_STYLE))
     table = Table(box=None, show_header=False, pad_edge=False, padding=(0, 2))
     table.add_column(no_wrap=True)  # styling lives in the Text cells
     table.add_column(overflow="fold")
     for label, help_str in rows:
         table.add_row(label, help_str)
-    console.print(table)
-    console.print()
+    return Group(Text("Options", style=_HEADING_STYLE), table)
 
 
-def _render_epilog(cmd: click.Command, console: Console) -> None:
-    if cmd.epilog:
-        console.print(cmd.epilog)
-        console.print()
+def _build_epilog(cmd: click.Command) -> Optional[RenderableType]:
+    if not cmd.epilog:
+        return None
+    return Text(cmd.epilog)
 
 
 def _group_commands_by_panel(group: click.Group) -> dict[str, list[tuple[str, click.Command]]]:
@@ -109,23 +108,25 @@ def _group_commands_by_panel(group: click.Group) -> dict[str, list[tuple[str, cl
     return panels
 
 
-def _render_commands(group: click.Group, console: Console) -> None:
+def _build_commands(group: click.Group, available_width: int) -> Optional[RenderableType]:
     panels = _group_commands_by_panel(group)
     if not panels:
-        return
+        return None
 
     # We want the name / description columns to be the same widths across groups
     name_width = max(len(name) for items in panels.values() for name, _ in items)
-    table_width = min(_MAX_HELP_WIDTH, console.width)
 
+    parts: list[RenderableType] = []
     for panel_name, items in panels.items():
-        console.print(Text(panel_name.ljust(table_width), style=f"{_HEADING_STYLE} underline"))
-        _render_command_table(console, items, name_width, table_width)
-        console.print()
+        if parts:
+            parts.append(Text(""))
+        parts.append(Text(panel_name.ljust(available_width), style=f"{_HEADING_STYLE} underline"))
+        parts.append(_build_command_table(items, name_width, available_width))
+    return Group(*parts)
 
 
 def build_command_table(name_width: int, table_width: Optional[int] = None) -> Table:
-    kwargs: dict[str, Any] = {"box": None, "show_header": False, "pad_edge": False, "padding": (0, 2)}
+    kwargs: dict[str, Any] = {"box": None, "show_header": False, "pad_edge": True, "padding": (0, 1)}
     if table_width is not None:
         kwargs["width"] = table_width
     table = Table(**kwargs)
@@ -137,16 +138,39 @@ def build_command_table(name_width: int, table_width: Optional[int] = None) -> T
     return table
 
 
-def _render_command_table(
-    console: Console,
+def _build_command_table(
     items: list[tuple[str, click.Command]],
     name_width: int,
     table_width: int,
-) -> None:
+) -> Table:
     table = build_command_table(name_width, table_width)
     for name, sub in items:
         table.add_row(name, sub.get_short_help_str(limit=80))
-    console.print(table)
+    return table
+
+
+def _available_width(console: Console) -> int:
+    return min(_MAX_HELP_WIDTH, console.width) - _HELP_PADDING * 2
+
+
+def _emit(
+    console: Console,
+    sections: list[Optional[RenderableType]],
+    formatter: click.HelpFormatter,
+) -> None:
+    parts: list[RenderableType] = []
+    for section in sections:
+        if section is None:
+            continue
+        if parts:
+            parts.append(Text(""))
+        parts.append(section)
+    if parts:
+        # Always pad with a blank line before the next prompt
+        parts.append(Text(""))
+    with console.capture() as capture:
+        console.print(Padding(Group(*parts), (0, _HELP_PADDING)))
+    formatter.write(capture.get())
 
 
 # -- Public Command / Group subclasses ---------------------------------------
@@ -162,13 +186,17 @@ class ModalCommand(click.Command):
     def format_help(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:
         if not use_rich_style():
             return super().format_help(ctx, formatter)
-        console = _make_console()
-        with console.capture() as capture:
-            _render_usage(self, ctx, console)
-            _render_help_text(self, console)
-            _render_options(self, ctx, console)
-            _render_epilog(self, console)
-        formatter.write(capture.get())
+        console = _make_help_console()
+        _emit(
+            console,
+            [
+                _build_usage(self, ctx),
+                _build_help_text(self),
+                _build_options(self, ctx),
+                _build_epilog(self),
+            ],
+            formatter,
+        )
 
 
 class ModalGroup(click.Group):
@@ -209,22 +237,25 @@ class ModalGroup(click.Group):
     def format_help(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:
         if not use_rich_style():
             return super().format_help(ctx, formatter)
-        console = _make_console()
-        with console.capture() as capture:
-            _render_usage(self, ctx, console)
-            _render_help_text(self, console)
-            _render_options(self, ctx, console)
-            _render_commands(self, console)
-            _render_epilog(self, console)
-        formatter.write(capture.get())
+        console = _make_help_console()
+        _emit(
+            console,
+            [
+                _build_usage(self, ctx),
+                _build_help_text(self),
+                _build_options(self, ctx),
+                _build_commands(self, _available_width(console)),
+                _build_epilog(self),
+            ],
+            formatter,
+        )
 
 
 # -- Error rendering ---------------------------------------------------------
 
 
 def _render_click_exception(exc: click.ClickException, file: Any) -> None:
-    console = _make_console(file if file is not None else sys.stderr)
-    title = "Error"
+    console = Console(file=file if file is not None else sys.stderr, highlight=False)
 
     if isinstance(exc, click.UsageError) and exc.ctx is not None:
         ctx = exc.ctx
@@ -236,7 +267,7 @@ def _render_click_exception(exc: click.ClickException, file: Any) -> None:
     console.print(
         Panel(
             Text(exc.format_message()),
-            title=title,
+            title="Error",
             title_align="left",
             border_style=_ERROR_STYLE,
             expand=True,

{modal-1.4.3.dev10 → modal-1.4.3.dev12}/modal/cli/run.py

@@ -235,6 +235,7 @@ def _make_click_function(app, signature: CliRunnableSignature, inner: Callable[[
         output_mgr.set_timestamps(ctx.obj["show_timestamps"])
         with run_app(
             app,
+            name=ctx.obj["name"],
             detach=ctx.obj["detach"],
             environment_name=ctx.obj["env"],
             interactive=ctx.obj["interactive"],
@@ -365,6 +366,7 @@ def _get_click_command_for_local_entrypoint(app: App, entrypoint: LocalEntrypoin
         output_mgr.set_timestamps(ctx.obj["show_timestamps"])
         with run_app(
             app,
+            name=ctx.obj["name"],
             detach=ctx.obj["detach"],
             environment_name=ctx.obj["env"],
             interactive=ctx.obj["interactive"],
@@ -448,6 +450,7 @@ class RunGroup(ModalGroup):
     cls=RunGroup,
     subcommand_metavar="FUNC_REF",
 )
+@click.option("-n", "--name", help="Name for this run of the App.")
 @click.option("-w", "--write-result", help="Write return value (which must be str or bytes) to this local path.")
 @click.option("-q", "--quiet", is_flag=True, help="Don't show Modal progress indicators.")
 @click.option("-d", "--detach", is_flag=True, help="Don't stop the app if the local process dies or disconnects.")
@@ -458,6 +461,7 @@ class RunGroup(ModalGroup):
 @click.pass_context
 def run(
     ctx: click.Context,
+    name: Optional[str],
     write_result: Optional[str],
     detach: bool,
     quiet: bool,
@@ -498,6 +502,7 @@ def run(
     ```
     """
     ctx.ensure_object(dict)
+    ctx.obj["name"] = name
     ctx.obj["result_path"] = write_result
     ctx.obj["detach"] = detach  # if subcommand would be a click command...
     ctx.obj["show_progress"] = False if quiet else True
@@ -573,6 +578,7 @@ def deploy(
 
 @click.command("serve", cls=ModalCommand, no_args_is_help=True)
 @click.argument("app_ref")
+@click.option("-n", "--name", help="Name for this run of the App.")
 @click.option("--timeout", default=None, type=float)
 @click.option("-e", "--env", default=None, help=ENV_OPTION_HELP)
 @click.option(
@@ -585,6 +591,7 @@ def deploy(
 @click.option("--timestamps", is_flag=True, default=False, help="Show timestamps for each log line.")
 def serve(
     app_ref: str,
+    name: Optional[str] = None,
     timeout: Optional[float] = None,
     env: Optional[str] = None,
     use_module_mode: bool = False,
@@ -611,7 +618,7 @@ def serve(
     app = import_app_from_ref(import_ref, base_cmd="modal serve")
     if app.description is None:
         app.set_description(_get_clean_app_description(app_ref))
-    with serve_app(app, import_ref, environment_name=env):
+    with serve_app(app, import_ref, name=name, environment_name=env):
         if timeout is None:
             timeout = config["serve_timeout"]
         if timeout is None:

{modal-1.4.3.dev10 → modal-1.4.3.dev12}/modal/cli/utils.py

@@ -162,11 +162,10 @@ def display_table(
         output.print(table)
 
 
-ENV_OPTION_HELP = """Environment to interact with.
-
-If not specified, Modal will use the default environment of your current profile, or the `MODAL_ENVIRONMENT` variable.
-Otherwise, raises an error if the workspace has multiple environments.
-"""
+ENV_OPTION_HELP = (
+    "Environment to interact with. If unspecified, defers to `MODAL_ENVIRONMENT`, "
+    "your active local profile, or your workspace default, in that order."
+)
 
 
 def env_option(func):

{modal-1.4.3.dev10 → modal-1.4.3.dev12}/modal/client.pyi

@@ -35,7 +35,7 @@ class _Client:
         server_url: str,
         client_type: int,
         credentials: typing.Optional[tuple[str, str]],
-        version: str = "1.4.3.dev10",
+        version: str = "1.4.3.dev12",
     ):
         """mdmd:hidden
         The Modal client object is not intended to be instantiated directly by users.
@@ -175,7 +175,7 @@ class Client:
         server_url: str,
         client_type: int,
         credentials: typing.Optional[tuple[str, str]],
-        version: str = "1.4.3.dev10",
+        version: str = "1.4.3.dev12",
     ):
         """mdmd:hidden
         The Modal client object is not intended to be instantiated directly by users.

{modal-1.4.3.dev10 → modal-1.4.3.dev12}/modal/functions.pyi

@@ -347,7 +347,7 @@ class Function(
 
     _call_generator: ___call_generator_spec
 
-    class __remote_spec(typing_extensions.Protocol[ReturnType_INNER, P_INNER]):
+    class __remote_spec(typing_extensions.Protocol[P_INNER, ReturnType_INNER]):
         def __call__(self, /, *args: P_INNER.args, **kwargs: P_INNER.kwargs) -> ReturnType_INNER:
             """Calls the function remotely, executing it with the given arguments and returning the execution's result."""
             ...
@@ -356,7 +356,7 @@ class Function(
             """Calls the function remotely, executing it with the given arguments and returning the execution's result."""
             ...
 
-    remote: __remote_spec[modal._functions.ReturnType, modal._functions.P]
+    remote: __remote_spec[modal._functions.P, modal._functions.ReturnType]
 
     class __remote_gen_spec(typing_extensions.Protocol):
         def __call__(self, /, *args, **kwargs) -> typing.Generator[typing.Any, None, None]:
@@ -383,7 +383,7 @@ class Function(
         """
         ...
 
-    class ___experimental_spawn_spec(typing_extensions.Protocol[ReturnType_INNER, P_INNER]):
+    class ___experimental_spawn_spec(typing_extensions.Protocol[P_INNER, ReturnType_INNER]):
         def __call__(self, /, *args: P_INNER.args, **kwargs: P_INNER.kwargs) -> FunctionCall[ReturnType_INNER]:
             """[Experimental] Calls the function with the given arguments, without waiting for the results.
 
@@ -406,7 +406,7 @@ class Function(
             """
             ...
 
-    _experimental_spawn: ___experimental_spawn_spec[modal._functions.ReturnType, modal._functions.P]
+    _experimental_spawn: ___experimental_spawn_spec[modal._functions.P, modal._functions.ReturnType]
 
     class ___spawn_map_inner_spec(typing_extensions.Protocol[P_INNER]):
         def __call__(self, /, *args: P_INNER.args, **kwargs: P_INNER.kwargs) -> None: ...
@@ -414,7 +414,7 @@ class Function(
 
     _spawn_map_inner: ___spawn_map_inner_spec[modal._functions.P]
 
-    class __spawn_spec(typing_extensions.Protocol[ReturnType_INNER, P_INNER]):
+    class __spawn_spec(typing_extensions.Protocol[P_INNER, ReturnType_INNER]):
         def __call__(self, /, *args: P_INNER.args, **kwargs: P_INNER.kwargs) -> FunctionCall[ReturnType_INNER]:
             """Calls the function with the given arguments, without waiting for the results.
 
@@ -435,7 +435,7 @@ class Function(
             """
             ...
 
-    spawn: __spawn_spec[modal._functions.ReturnType, modal._functions.P]
+    spawn: __spawn_spec[modal._functions.P, modal._functions.ReturnType]
 
     def get_raw_f(self) -> collections.abc.Callable[..., typing.Any]:
         """Return the inner Python object wrapped by this Modal Function."""

{modal-1.4.3.dev10 → modal-1.4.3.dev12}/modal/runner.py

@@ -360,6 +360,7 @@ async def _status_based_disconnect(client: _Client, app_id: str, exc_info: Optio
 async def _run_app(
     app: "modal.app._App",
     *,
+    name: Optional[str] = None,
     client: Optional[_Client] = None,
     detach: bool = False,
     environment_name: Optional[str] = None,
@@ -380,7 +381,9 @@ async def _run_app(
             "You should not use `app.run` or `run_app` within a Modal `local_entrypoint`"
         )
 
-    if app.description is None:
+    if name:
+        app.set_description(name)
+    elif app.description is None:
         import __main__
 
         if "__file__" in dir(__main__):

{modal-1.4.3.dev10 → modal-1.4.3.dev12}/modal/runner.pyi

@@ -75,6 +75,7 @@ async def _status_based_disconnect(
 def _run_app(
     app: modal.app._App,
     *,
+    name: typing.Optional[str] = None,
     client: typing.Optional[modal.client._Client] = None,
     detach: bool = False,
     environment_name: typing.Optional[str] = None,
@@ -170,6 +171,7 @@ class __run_app_spec(typing_extensions.Protocol):
         /,
         app: modal.app.App,
         *,
+        name: typing.Optional[str] = None,
         client: typing.Optional[modal.client.Client] = None,
         detach: bool = False,
         environment_name: typing.Optional[str] = None,
@@ -184,6 +186,7 @@ class __run_app_spec(typing_extensions.Protocol):
         /,
         app: modal.app.App,
         *,
+        name: typing.Optional[str] = None,
         client: typing.Optional[modal.client.Client] = None,
         detach: bool = False,
         environment_name: typing.Optional[str] = None,

{modal-1.4.3.dev10 → modal-1.4.3.dev12}/modal/sandbox_fs.py

@@ -18,11 +18,13 @@ from ._utils.sandbox_fs_utils import (
     make_make_directory_command,
     make_read_file_command,
     make_remove_command,
+    make_stat_command,
     make_write_file_command,
     raise_list_files_error,
     raise_make_directory_error,
     raise_read_file_error,
     raise_remove_error,
+    raise_stat_error,
     raise_write_file_error,
     translate_exec_errors,
     validate_absolute_remote_path,
@@ -419,6 +421,57 @@ class _SandboxFilesystem:
         if returncode != 0:
             raise_remove_error(returncode, stderr, remote_path)
 
+    async def stat(self, remote_path: str) -> FileInfo:
+        """Return metadata for a single file, directory, or symlink in the Sandbox.
+
+        `remote_path` must be an absolute path in the Sandbox. If `remote_path` is a symlink, the returned
+        `FileInfo` object describes the symlink, not the target it points to.
+
+        **Raises**
+
+        - `SandboxFilesystemNotFoundError`: the path does not exist.
+        - `SandboxFilesystemNotADirectoryError`: a non-leaf component of the path is not a directory.
+        - `SandboxFilesystemPermissionError`: a component of the path is not searchable.
+        - `SandboxFilesystemError`: the command fails for any other reason.
+
+        **Usage**
+
+        ```python fixture:sandbox
+        sandbox.filesystem.write_text("Hello, world!\\n", "/tmp/hello.txt")
+        info = sandbox.filesystem.stat("/tmp/hello.txt")
+        print(info.size, info.permissions, info.modified_time)
+        ```
+        """
+        validate_absolute_remote_path(remote_path, "stat")
+
+        t0 = time.monotonic()
+        with translate_exec_errors("stat", remote_path):
+            process = await self._sandbox.exec(_SANDBOX_FS_TOOLS_PATH, make_stat_command(remote_path))
+            stdout, stderr, returncode = await asyncio.gather(
+                process.stdout.read(), process.stderr.read(), process.wait()
+            )
+
+        if returncode != 0:
+            raise_stat_error(returncode, stderr, remote_path)
+
+        entry = json.loads(stdout)
+        result = FileInfo(
+            name=entry["name"],
+            path=entry["path"],
+            type=FileType(entry["type"]),
+            size=entry["size"],
+            mode=entry["mode"],
+            permissions=entry["permissions"],
+            owner=entry["owner"],
+            group=entry["group"],
+            modified_time=entry["modified_time"],
+            symlink_target=entry.get("symlink_target"),
+        )
+
+        dur_s = max(time.monotonic() - t0, 0.001)
+        logger.debug(f"sandbox stat {remote_path}: ({dur_s:.2f}s)")
+        return result
+
     async def write_bytes(self, data: Union[bytes, bytearray, memoryview], remote_path: str) -> None:
         """Write binary content to a file in the Sandbox.