modal 1.0.3.dev10__py3-none-any.whl → 1.2.3.dev7__py3-none-any.whl

modal/network_file_system.py

@@ -6,12 +6,12 @@ from collections.abc import AsyncIterator
 from pathlib import Path, PurePosixPath
 from typing import Any, BinaryIO, Callable, Optional, Union
 
-from grpclib import GRPCError, Status
 from synchronicity.async_wrap import asynccontextmanager
 
 import modal
 from modal_proto import api_pb2
 
+from ._load_context import LoadContext
 from ._object import (
     EPHEMERAL_OBJECT_HEARTBEAT_SLEEP,
     _get_environment_name,
@@ -22,8 +22,7 @@ from ._object import (
 from ._resolver import Resolver
 from ._utils.async_utils import TaskContext, aclosing, async_map, sync_or_async_iter, synchronize_api
 from ._utils.blob_utils import LARGE_FILE_LIMIT, blob_iter, blob_upload_file
-from ._utils.deprecation import deprecation_warning
-from ._utils.grpc_utils import retry_transient_errors
+from ._utils.deprecation import warn_if_passing_namespace
 from ._utils.hash_utils import get_sha256_hex
 from ._utils.name_utils import check_object_name
 from .client import _Client
@@ -56,6 +55,8 @@ class _NetworkFileSystem(_Object, type_prefix="sv"):
     By attaching this file system as a mount to one or more functions, they can
     share and persist data with each other.
 
+    **Note: `NetworkFileSystem` has been deprecated and will be removed.**
+
     **Usage**
 
     ```python
@@ -92,15 +93,16 @@ class _NetworkFileSystem(_Object, type_prefix="sv"):
     def from_name(
         name: str,
         *,
-        namespace=api_pb2.DEPLOYMENT_NAMESPACE_WORKSPACE,
+        namespace=None,  # mdmd:line-hidden
         environment_name: Optional[str] = None,
         create_if_missing: bool = False,
+        client: Optional[_Client] = None,
     ) -> "_NetworkFileSystem":
         """Reference a NetworkFileSystem by its name, creating if necessary.
 
-        In contrast to `modal.NetworkFileSystem.lookup`, this is a lazy method
-        that defers hydrating the local object with metadata from Modal servers
-        until the first time it is actually used.
+        This is a lazy method that defers hydrating the local object with
+        metadata from Modal servers until the first time it is actually
+        used.
 
         ```python notest
         nfs = NetworkFileSystem.from_name("my-nfs", create_if_missing=True)
@@ -111,25 +113,32 @@ class _NetworkFileSystem(_Object, type_prefix="sv"):
         ```
         """
         check_object_name(name, "NetworkFileSystem")
+        warn_if_passing_namespace(namespace, "modal.NetworkFileSystem.from_name")
 
-        async def _load(self: _NetworkFileSystem, resolver: Resolver, existing_object_id: Optional[str]):
+        async def _load(
+            self: _NetworkFileSystem, resolver: Resolver, load_context: LoadContext, existing_object_id: Optional[str]
+        ):
             req = api_pb2.SharedVolumeGetOrCreateRequest(
                 deployment_name=name,
-                namespace=namespace,
-                environment_name=_get_environment_name(environment_name, resolver),
+                environment_name=load_context.environment_name,
                 object_creation_type=(api_pb2.OBJECT_CREATION_TYPE_CREATE_IF_MISSING if create_if_missing else None),
             )
             try:
-                response = await resolver.client.stub.SharedVolumeGetOrCreate(req)
-                self._hydrate(response.shared_volume_id, resolver.client, None)
-            except GRPCError as exc:
-                if exc.status == Status.NOT_FOUND and exc.message == "App has wrong entity vo":
+                response = await load_context.client.stub.SharedVolumeGetOrCreate(req)
+                self._hydrate(response.shared_volume_id, load_context.client, None)
+            except modal.exception.NotFoundError as exc:
+                if exc.args[0] == "App has wrong entity vo":
                     raise InvalidError(
                         f"Attempted to mount: `{name}` as a NetworkFileSystem " + "which already exists as a Volume"
                     )
                 raise
 
-        return _NetworkFileSystem._from_loader(_load, "NetworkFileSystem()", hydrate_lazily=True)
+        return _NetworkFileSystem._from_loader(
+            _load,
+            "NetworkFileSystem()",
+            hydrate_lazily=True,
+            load_context_overrides=LoadContext(environment_name=environment_name, client=client),
+        )
 
     @classmethod
     @asynccontextmanager
@@ -137,7 +146,7 @@ class _NetworkFileSystem(_Object, type_prefix="sv"):
         cls: type["_NetworkFileSystem"],
         client: Optional[_Client] = None,
         environment_name: Optional[str] = None,
-        _heartbeat_sleep: float = EPHEMERAL_OBJECT_HEARTBEAT_SLEEP,
+        _heartbeat_sleep: float = EPHEMERAL_OBJECT_HEARTBEAT_SLEEP,  # mdmd:line-hidden
     ) -> AsyncIterator["_NetworkFileSystem"]:
         """Creates a new ephemeral network filesystem within a context manager:
 
@@ -162,69 +171,39 @@ class _NetworkFileSystem(_Object, type_prefix="sv"):
         async with TaskContext() as tc:
             request = api_pb2.SharedVolumeHeartbeatRequest(shared_volume_id=response.shared_volume_id)
             tc.infinite_loop(lambda: client.stub.SharedVolumeHeartbeat(request), sleep=_heartbeat_sleep)
-            yield cls._new_hydrated(response.shared_volume_id, client, None, is_another_app=True)
-
-    @staticmethod
-    async def lookup(
-        name: str,
-        namespace=api_pb2.DEPLOYMENT_NAMESPACE_WORKSPACE,
-        client: Optional[_Client] = None,
-        environment_name: Optional[str] = None,
-        create_if_missing: bool = False,
-    ) -> "_NetworkFileSystem":
-        """mdmd:hidden
-        Lookup a named NetworkFileSystem.
-
-        DEPRECATED: This method is deprecated in favor of `modal.NetworkFileSystem.from_name`.
-
-        In contrast to `modal.NetworkFileSystem.from_name`, this is an eager method
-        that will hydrate the local object with metadata from Modal servers.
-
-        ```python notest
-        nfs = modal.NetworkFileSystem.lookup("my-nfs")
-        print(nfs.listdir("/"))
-        ```
-        """
-        deprecation_warning(
-            (2025, 1, 27),
-            "`modal.NetworkFileSystem.lookup` is deprecated and will be removed in a future release."
-            " It can be replaced with `modal.NetworkFileSystem.from_name`."
-            "\n\nSee https://modal.com/docs/guide/modal-1-0-migration for more information.",
-        )
-        obj = _NetworkFileSystem.from_name(
-            name, namespace=namespace, environment_name=environment_name, create_if_missing=create_if_missing
-        )
-        if client is None:
-            client = await _Client.from_env()
-        resolver = Resolver(client=client)
-        await resolver.load(obj)
-        return obj
+            yield cls._new_hydrated(
+                response.shared_volume_id,
+                client,
+                None,
+                is_another_app=True,
+                rep="modal.NetworkFileSystem.ephemeral()",
+            )
 
     @staticmethod
     async def create_deployed(
         deployment_name: str,
-        namespace=api_pb2.DEPLOYMENT_NAMESPACE_WORKSPACE,
+        namespace=None,  # mdmd:line-hidden
         client: Optional[_Client] = None,
         environment_name: Optional[str] = None,
     ) -> str:
         """mdmd:hidden"""
         check_object_name(deployment_name, "NetworkFileSystem")
+        warn_if_passing_namespace(namespace, "modal.NetworkFileSystem.create_deployed")
         if client is None:
             client = await _Client.from_env()
         request = api_pb2.SharedVolumeGetOrCreateRequest(
             deployment_name=deployment_name,
-            namespace=namespace,
             environment_name=_get_environment_name(environment_name),
             object_creation_type=api_pb2.OBJECT_CREATION_TYPE_CREATE_FAIL_IF_EXISTS,
         )
-        resp = await retry_transient_errors(client.stub.SharedVolumeGetOrCreate, request)
+        resp = await client.stub.SharedVolumeGetOrCreate(request)
         return resp.shared_volume_id
 
     @staticmethod
     async def delete(name: str, client: Optional[_Client] = None, environment_name: Optional[str] = None):
         obj = await _NetworkFileSystem.from_name(name, environment_name=environment_name).hydrate(client)
         req = api_pb2.SharedVolumeDeleteRequest(shared_volume_id=obj.object_id)
-        await retry_transient_errors(obj._client.stub.SharedVolumeDelete, req)
+        await obj._client.stub.SharedVolumeDelete(req)
 
     @live_method
     async def write_file(self, remote_path: str, fp: BinaryIO, progress_cb: Optional[Callable[..., Any]] = None) -> int:
@@ -264,7 +243,7 @@ class _NetworkFileSystem(_Object, type_prefix="sv"):
 
         t0 = time.monotonic()
         while time.monotonic() - t0 < NETWORK_FILE_SYSTEM_PUT_FILE_CLIENT_TIMEOUT:
-            response = await retry_transient_errors(self._client.stub.SharedVolumePutFile, req)
+            response = await self._client.stub.SharedVolumePutFile(req)
             if response.exists:
                 break
         else:
@@ -277,9 +256,10 @@ class _NetworkFileSystem(_Object, type_prefix="sv"):
         """Read a file from the network file system"""
         req = api_pb2.SharedVolumeGetFileRequest(shared_volume_id=self.object_id, path=path)
         try:
-            response = await retry_transient_errors(self._client.stub.SharedVolumeGetFile, req)
-        except GRPCError as exc:
-            raise FileNotFoundError(exc.message) if exc.status == Status.NOT_FOUND else exc
+            response = await self._client.stub.SharedVolumeGetFile(req)
+        except modal.exception.NotFoundError as exc:
+            raise FileNotFoundError(exc.args[0])
+
         if response.WhichOneof("data_oneof") == "data":
             yield response.data
         else:
@@ -360,7 +340,10 @@ class _NetworkFileSystem(_Object, type_prefix="sv"):
     async def remove_file(self, path: str, recursive=False):
         """Remove a file in a network file system."""
         req = api_pb2.SharedVolumeRemoveFileRequest(shared_volume_id=self.object_id, path=path, recursive=recursive)
-        await retry_transient_errors(self._client.stub.SharedVolumeRemoveFile, req)
+        try:
+            await self._client.stub.SharedVolumeRemoveFile(req)
+        except modal.exception.NotFoundError as exc:
+            raise FileNotFoundError(exc.args[0])
 
 
 NetworkFileSystem = synchronize_api(_NetworkFileSystem)

modal/network_file_system.pyi

@@ -14,32 +14,101 @@ def network_file_system_mount_protos(
 ) -> list[modal_proto.api_pb2.SharedVolumeMount]: ...
 
 class _NetworkFileSystem(modal._object._Object):
+    """A shared, writable file system accessible by one or more Modal functions.
+
+    By attaching this file system as a mount to one or more functions, they can
+    share and persist data with each other.
+
+    **Note: `NetworkFileSystem` has been deprecated and will be removed.**
+
+    **Usage**
+
+    ```python
+    import modal
+
+    nfs = modal.NetworkFileSystem.from_name("my-nfs", create_if_missing=True)
+    app = modal.App()
+
+    @app.function(network_file_systems={"/root/foo": nfs})
+    def f():
+        pass
+
+    @app.function(network_file_systems={"/root/goo": nfs})
+    def g():
+        pass
+    ```
+
+    Also see the CLI methods for accessing network file systems:
+
+    ```
+    modal nfs --help
+    ```
+
+    A `NetworkFileSystem` can also be useful for some local scripting scenarios, e.g.:
+
+    ```python notest
+    nfs = modal.NetworkFileSystem.from_name("my-network-file-system")
+    for chunk in nfs.read_file("my_db_dump.csv"):
+        ...
+    ```
+    """
     @staticmethod
     def from_name(
-        name: str, *, namespace=1, environment_name: typing.Optional[str] = None, create_if_missing: bool = False
-    ) -> _NetworkFileSystem: ...
+        name: str,
+        *,
+        namespace=None,
+        environment_name: typing.Optional[str] = None,
+        create_if_missing: bool = False,
+        client: typing.Optional[modal.client._Client] = None,
+    ) -> _NetworkFileSystem:
+        """Reference a NetworkFileSystem by its name, creating if necessary.
+
+        This is a lazy method that defers hydrating the local object with
+        metadata from Modal servers until the first time it is actually
+        used.
+
+        ```python notest
+        nfs = NetworkFileSystem.from_name("my-nfs", create_if_missing=True)
+
+        @app.function(network_file_systems={"/data": nfs})
+        def f():
+            pass
+        ```
+        """
+        ...
+
     @classmethod
     def ephemeral(
         cls: type[_NetworkFileSystem],
         client: typing.Optional[modal.client._Client] = None,
         environment_name: typing.Optional[str] = None,
         _heartbeat_sleep: float = 300,
-    ) -> typing.AsyncContextManager[_NetworkFileSystem]: ...
-    @staticmethod
-    async def lookup(
-        name: str,
-        namespace=1,
-        client: typing.Optional[modal.client._Client] = None,
-        environment_name: typing.Optional[str] = None,
-        create_if_missing: bool = False,
-    ) -> _NetworkFileSystem: ...
+    ) -> typing.AsyncContextManager[_NetworkFileSystem]:
+        """Creates a new ephemeral network filesystem within a context manager:
+
+        Usage:
+        ```python
+        with modal.NetworkFileSystem.ephemeral() as nfs:
+            assert nfs.listdir("/") == []
+        ```
+
+        ```python notest
+        async with modal.NetworkFileSystem.ephemeral() as nfs:
+            assert await nfs.listdir("/") == []
+        ```
+        """
+        ...
+
     @staticmethod
     async def create_deployed(
         deployment_name: str,
-        namespace=1,
+        namespace=None,
         client: typing.Optional[modal.client._Client] = None,
         environment_name: typing.Optional[str] = None,
-    ) -> str: ...
+    ) -> str:
+        """mdmd:hidden"""
+        ...
+
     @staticmethod
     async def delete(
         name: str, client: typing.Optional[modal.client._Client] = None, environment_name: typing.Optional[str] = None
@@ -49,9 +118,30 @@ class _NetworkFileSystem(modal._object._Object):
         remote_path: str,
         fp: typing.BinaryIO,
         progress_cb: typing.Optional[collections.abc.Callable[..., typing.Any]] = None,
-    ) -> int: ...
-    def read_file(self, path: str) -> collections.abc.AsyncIterator[bytes]: ...
-    def iterdir(self, path: str) -> collections.abc.AsyncIterator[modal.volume.FileEntry]: ...
+    ) -> int:
+        """Write from a file object to a path on the network file system, atomically.
+
+        Will create any needed parent directories automatically.
+
+        If remote_path ends with `/` it's assumed to be a directory and the
+        file will be uploaded with its current name to that directory.
+        """
+        ...
+
+    def read_file(self, path: str) -> collections.abc.AsyncIterator[bytes]:
+        """Read a file from the network file system"""
+        ...
+
+    def iterdir(self, path: str) -> collections.abc.AsyncIterator[modal.volume.FileEntry]:
+        """Iterate over all files in a directory in the network file system.
+
+        * Passing a directory path lists all files in the directory (names are relative to the directory)
+        * Passing a file path returns a list containing only that file's listing description
+        * Passing a glob path (including at least one * or ** sequence) returns all files matching
+        that glob path (using absolute paths)
+        """
+        ...
+
     async def add_local_file(
         self,
         local_path: typing.Union[pathlib.Path, str],
@@ -64,64 +154,134 @@ class _NetworkFileSystem(modal._object._Object):
         remote_path: typing.Union[str, pathlib.PurePosixPath, None] = None,
         progress_cb: typing.Optional[collections.abc.Callable[..., typing.Any]] = None,
     ): ...
-    async def listdir(self, path: str) -> list[modal.volume.FileEntry]: ...
-    async def remove_file(self, path: str, recursive=False): ...
+    async def listdir(self, path: str) -> list[modal.volume.FileEntry]:
+        """List all files in a directory in the network file system.
+
+        * Passing a directory path lists all files in the directory (names are relative to the directory)
+        * Passing a file path returns a list containing only that file's listing description
+        * Passing a glob path (including at least one * or ** sequence) returns all files matching
+        that glob path (using absolute paths)
+        """
+        ...
+
+    async def remove_file(self, path: str, recursive=False):
+        """Remove a file in a network file system."""
+        ...
 
 SUPERSELF = typing.TypeVar("SUPERSELF", covariant=True)
 
 class NetworkFileSystem(modal.object.Object):
-    def __init__(self, *args, **kwargs): ...
+    """A shared, writable file system accessible by one or more Modal functions.
+
+    By attaching this file system as a mount to one or more functions, they can
+    share and persist data with each other.
+
+    **Note: `NetworkFileSystem` has been deprecated and will be removed.**
+
+    **Usage**
+
+    ```python
+    import modal
+
+    nfs = modal.NetworkFileSystem.from_name("my-nfs", create_if_missing=True)
+    app = modal.App()
+
+    @app.function(network_file_systems={"/root/foo": nfs})
+    def f():
+        pass
+
+    @app.function(network_file_systems={"/root/goo": nfs})
+    def g():
+        pass
+    ```
+
+    Also see the CLI methods for accessing network file systems:
+
+    ```
+    modal nfs --help
+    ```
+
+    A `NetworkFileSystem` can also be useful for some local scripting scenarios, e.g.:
+
+    ```python notest
+    nfs = modal.NetworkFileSystem.from_name("my-network-file-system")
+    for chunk in nfs.read_file("my_db_dump.csv"):
+        ...
+    ```
+    """
+    def __init__(self, *args, **kwargs):
+        """mdmd:hidden"""
+        ...
+
     @staticmethod
     def from_name(
-        name: str, *, namespace=1, environment_name: typing.Optional[str] = None, create_if_missing: bool = False
-    ) -> NetworkFileSystem: ...
+        name: str,
+        *,
+        namespace=None,
+        environment_name: typing.Optional[str] = None,
+        create_if_missing: bool = False,
+        client: typing.Optional[modal.client.Client] = None,
+    ) -> NetworkFileSystem:
+        """Reference a NetworkFileSystem by its name, creating if necessary.
+
+        This is a lazy method that defers hydrating the local object with
+        metadata from Modal servers until the first time it is actually
+        used.
+
+        ```python notest
+        nfs = NetworkFileSystem.from_name("my-nfs", create_if_missing=True)
+
+        @app.function(network_file_systems={"/data": nfs})
+        def f():
+            pass
+        ```
+        """
+        ...
+
     @classmethod
     def ephemeral(
         cls: type[NetworkFileSystem],
         client: typing.Optional[modal.client.Client] = None,
         environment_name: typing.Optional[str] = None,
         _heartbeat_sleep: float = 300,
-    ) -> synchronicity.combined_types.AsyncAndBlockingContextManager[NetworkFileSystem]: ...
+    ) -> synchronicity.combined_types.AsyncAndBlockingContextManager[NetworkFileSystem]:
+        """Creates a new ephemeral network filesystem within a context manager:
 
-    class __lookup_spec(typing_extensions.Protocol):
-        def __call__(
-            self,
-            /,
-            name: str,
-            namespace=1,
-            client: typing.Optional[modal.client.Client] = None,
-            environment_name: typing.Optional[str] = None,
-            create_if_missing: bool = False,
-        ) -> NetworkFileSystem: ...
-        async def aio(
-            self,
-            /,
-            name: str,
-            namespace=1,
-            client: typing.Optional[modal.client.Client] = None,
-            environment_name: typing.Optional[str] = None,
-            create_if_missing: bool = False,
-        ) -> NetworkFileSystem: ...
+        Usage:
+        ```python
+        with modal.NetworkFileSystem.ephemeral() as nfs:
+            assert nfs.listdir("/") == []
+        ```
 
-    lookup: __lookup_spec
+        ```python notest
+        async with modal.NetworkFileSystem.ephemeral() as nfs:
+            assert await nfs.listdir("/") == []
+        ```
+        """
+        ...
 
     class __create_deployed_spec(typing_extensions.Protocol):
         def __call__(
             self,
             /,
             deployment_name: str,
-            namespace=1,
+            namespace=None,
             client: typing.Optional[modal.client.Client] = None,
             environment_name: typing.Optional[str] = None,
-        ) -> str: ...
+        ) -> str:
+            """mdmd:hidden"""
+            ...
+
         async def aio(
             self,
             /,
             deployment_name: str,
-            namespace=1,
+            namespace=None,
             client: typing.Optional[modal.client.Client] = None,
             environment_name: typing.Optional[str] = None,
-        ) -> str: ...
+        ) -> str:
+            """mdmd:hidden"""
+            ...
 
     create_deployed: __create_deployed_spec
 
@@ -150,26 +310,65 @@ class NetworkFileSystem(modal.object.Object):
             remote_path: str,
             fp: typing.BinaryIO,
             progress_cb: typing.Optional[collections.abc.Callable[..., typing.Any]] = None,
-        ) -> int: ...
+        ) -> int:
+            """Write from a file object to a path on the network file system, atomically.
+
+            Will create any needed parent directories automatically.
+
+            If remote_path ends with `/` it's assumed to be a directory and the
+            file will be uploaded with its current name to that directory.
+            """
+            ...
+
         async def aio(
             self,
             /,
             remote_path: str,
             fp: typing.BinaryIO,
             progress_cb: typing.Optional[collections.abc.Callable[..., typing.Any]] = None,
-        ) -> int: ...
+        ) -> int:
+            """Write from a file object to a path on the network file system, atomically.
+
+            Will create any needed parent directories automatically.
+
+            If remote_path ends with `/` it's assumed to be a directory and the
+            file will be uploaded with its current name to that directory.
+            """
+            ...
 
     write_file: __write_file_spec[typing_extensions.Self]
 
     class __read_file_spec(typing_extensions.Protocol[SUPERSELF]):
-        def __call__(self, /, path: str) -> typing.Iterator[bytes]: ...
-        def aio(self, /, path: str) -> collections.abc.AsyncIterator[bytes]: ...
+        def __call__(self, /, path: str) -> typing.Iterator[bytes]:
+            """Read a file from the network file system"""
+            ...
+
+        def aio(self, /, path: str) -> collections.abc.AsyncIterator[bytes]:
+            """Read a file from the network file system"""
+            ...
 
     read_file: __read_file_spec[typing_extensions.Self]
 
     class __iterdir_spec(typing_extensions.Protocol[SUPERSELF]):
-        def __call__(self, /, path: str) -> typing.Iterator[modal.volume.FileEntry]: ...
-        def aio(self, /, path: str) -> collections.abc.AsyncIterator[modal.volume.FileEntry]: ...
+        def __call__(self, /, path: str) -> typing.Iterator[modal.volume.FileEntry]:
+            """Iterate over all files in a directory in the network file system.
+
+            * Passing a directory path lists all files in the directory (names are relative to the directory)
+            * Passing a file path returns a list containing only that file's listing description
+            * Passing a glob path (including at least one * or ** sequence) returns all files matching
+            that glob path (using absolute paths)
+            """
+            ...
+
+        def aio(self, /, path: str) -> collections.abc.AsyncIterator[modal.volume.FileEntry]:
+            """Iterate over all files in a directory in the network file system.
+
+            * Passing a directory path lists all files in the directory (names are relative to the directory)
+            * Passing a file path returns a list containing only that file's listing description
+            * Passing a glob path (including at least one * or ** sequence) returns all files matching
+            that glob path (using absolute paths)
+            """
+            ...
 
     iterdir: __iterdir_spec[typing_extensions.Self]
 
@@ -210,13 +409,35 @@ class NetworkFileSystem(modal.object.Object):
     add_local_dir: __add_local_dir_spec[typing_extensions.Self]
 
     class __listdir_spec(typing_extensions.Protocol[SUPERSELF]):
-        def __call__(self, /, path: str) -> list[modal.volume.FileEntry]: ...
-        async def aio(self, /, path: str) -> list[modal.volume.FileEntry]: ...
+        def __call__(self, /, path: str) -> list[modal.volume.FileEntry]:
+            """List all files in a directory in the network file system.
+
+            * Passing a directory path lists all files in the directory (names are relative to the directory)
+            * Passing a file path returns a list containing only that file's listing description
+            * Passing a glob path (including at least one * or ** sequence) returns all files matching
+            that glob path (using absolute paths)
+            """
+            ...
+
+        async def aio(self, /, path: str) -> list[modal.volume.FileEntry]:
+            """List all files in a directory in the network file system.
+
+            * Passing a directory path lists all files in the directory (names are relative to the directory)
+            * Passing a file path returns a list containing only that file's listing description
+            * Passing a glob path (including at least one * or ** sequence) returns all files matching
+            that glob path (using absolute paths)
+            """
+            ...
 
     listdir: __listdir_spec[typing_extensions.Self]
 
     class __remove_file_spec(typing_extensions.Protocol[SUPERSELF]):
-        def __call__(self, /, path: str, recursive=False): ...
-        async def aio(self, /, path: str, recursive=False): ...
+        def __call__(self, /, path: str, recursive=False):
+            """Remove a file in a network file system."""
+            ...
+
+        async def aio(self, /, path: str, recursive=False):
+            """Remove a file in a network file system."""
+            ...
 
     remove_file: __remove_file_spec[typing_extensions.Self]