modAL 1.3.1.dev26__tar.gz → 1.3.1.dev27__tar.gz

{modal-1.3.1.dev26 → modal-1.3.1.dev27}/PKG-INFO

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

modal-1.3.1.dev27/modal/_server.py

@@ -0,0 +1,246 @@
+# Copyright Modal Labs 2025
+import inspect
+import typing
+from typing import Optional
+
+from ._functions import _Function
+from ._load_context import LoadContext
+from ._object import live_method
+from ._partial_function import (
+    _find_partial_methods_for_user_cls,
+    _PartialFunction,
+    _PartialFunctionFlags,
+)
+from .client import _Client
+from .cls import is_parameter
+from .exception import InvalidError
+
+if typing.TYPE_CHECKING:
+    import modal.app
+
+
+def validate_http_server_config(
+    port: int,
+    proxy_regions: list[str],  # The regions to proxy the HTTP server to.
+    startup_timeout: int,  # Maximum number of seconds to wait for the HTTP server to start.
+    exit_grace_period: Optional[int],  # The time to wait for the HTTP server to exit gracefully.
+):
+    if not isinstance(port, int) or port < 1 or port > 65535:
+        raise InvalidError("Port must be a positive integer between 1 and 65535.")
+    if startup_timeout <= 0:
+        raise InvalidError("The `startup_timeout` argument must be positive.")
+    if exit_grace_period is not None and exit_grace_period < 0:
+        raise InvalidError("The `exit_grace_period` argument must be non-negative.")
+    if not proxy_regions:
+        raise InvalidError("The `proxy_regions` argument must be non-empty.")
+
+
+class _Server:
+    """Server runs an HTTP server started in an `@modal.enter` method.
+
+    See [lifecycle hooks](https://modal.com/docs/guide/lifecycle-functions) for more information.
+
+    Generally, you will not construct a Server directly.
+    Instead, use the [`@app.server()`](https://modal.com/docs/reference/modal.App#server) decorator.
+
+    ```python notest
+    @app.server(port=8000, proxy_regions=["us-east", "us-west"])
+    class MyServer:
+        @modal.enter()
+        def start_server(self):
+            self.process = subprocess.Popen(["python3", "-m", "http.server", "8080"])
+    ```
+    """
+
+    _user_cls: Optional[type] = None  # None if remote
+    _service_function: _Function
+    _app: Optional["modal.app._App"] = None  # None if remote
+
+    def _get_user_cls(self) -> type:
+        assert self._user_cls is not None
+        return self._user_cls
+
+    def _get_app(self) -> "modal.app._App":
+        assert self._app
+        return self._app
+
+    def _get_service_function(self) -> _Function:
+        return self._service_function
+
+    @staticmethod
+    def _extract_user_cls(wrapped_user_cls: "type | _PartialFunction") -> type:
+        if isinstance(wrapped_user_cls, _PartialFunction):
+            assert wrapped_user_cls.user_cls
+            return wrapped_user_cls.user_cls
+        else:
+            return wrapped_user_cls
+
+    # ============ Live Methods ============
+
+    @live_method
+    async def get_urls(self) -> Optional[list[str]]:
+        return await self._get_service_function()._experimental_get_flash_urls()
+
+    @live_method
+    async def update_autoscaler(
+        self,
+        *,
+        min_containers: Optional[int] = None,
+        max_containers: Optional[int] = None,
+        buffer_containers: Optional[int] = None,
+        scaledown_window: Optional[int] = None,
+    ) -> None:
+        """Override the current autoscaler behavior for this Server.
+
+        Unspecified parameters will retain their current value.
+
+        Examples:
+        ```python notest
+        server = modal.Server.from_name("my-app", "Server")
+
+        # Always have at least 2 containers running, with an extra buffer of 2 containers
+        server.update_autoscaler(min_containers=2, buffer_containers=1)
+
+        # Limit this Server to avoid spinning up more than 5 containers
+        server.update_autoscaler(max_containers=5)
+        ```
+
+        """
+        return await self._get_service_function().update_autoscaler(
+            min_containers=min_containers,
+            max_containers=max_containers,
+            scaledown_window=scaledown_window,
+            buffer_containers=buffer_containers,
+        )
+
+    # ============ Hydration ============
+    async def hydrate(self, client: Optional[_Client] = None) -> "_Server":
+        # This is required since we want to support @livemethod() decorated methods
+        service_function = self._get_service_function()
+        await service_function.hydrate(client)
+        return self
+
+    # ============ Construction ============
+    @staticmethod
+    def _from_local(
+        wrapped_user_cls: "type | _PartialFunction",
+        app: "modal.app._App",
+        service_function: _Function,
+    ) -> "_Server":
+        """Create a Server from a local class definition."""
+
+        # Note: Validation should be done by the caller (app.server()) BEFORE creating the Server.
+        # Extract the underlying class if wrapped in a _PartialFunction (e.g., from @modal.clustered())
+        user_cls = _Server._extract_user_cls(wrapped_user_cls)
+
+        server = _Server()
+        server._app = app
+        server._user_cls = user_cls
+        server._service_function = service_function
+        return server
+
+    @classmethod
+    def from_name(
+        cls: type["_Server"],
+        app_name: str,
+        name: str,
+        *,
+        environment_name: Optional[str] = None,
+        client: Optional[_Client] = None,
+    ) -> "_Server":
+        """Reference a Server from a deployed App by its name.
+
+        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
+        server = modal.Server.from_name("other-app", "Server")
+        ```
+        """
+
+        load_context_overrides = LoadContext(client=client, environment_name=environment_name)
+
+        server = _Server()
+        server._service_function = _Function._from_name(
+            app_name,
+            name,
+            load_context_overrides=load_context_overrides,
+        )
+        return server
+
+    def _is_local(self) -> bool:
+        """Returns True if this Server has local source code available."""
+        return self._user_cls is not None
+
+    # ============ Validation ============
+
+    @staticmethod
+    def _validate_wrapped_user_cls_decorators(
+        wrapped_user_cls: "type | _PartialFunction", enable_memory_snapshot: bool
+    ):
+        user_cls = _Server._extract_user_cls(wrapped_user_cls)
+
+        if not inspect.isclass(user_cls):
+            raise TypeError("The @app.server() decorator must be used on a class.")
+
+        # Check for modal.parameter() - not allowed on server classes
+        params = {k: v for k, v in user_cls.__dict__.items() if is_parameter(v)}
+        if params:
+            raise InvalidError(
+                f"Server class {user_cls.__name__} cannot use modal.parameter(). "
+                "Servers do not support parameterization."
+            )
+
+        if not _find_partial_methods_for_user_cls(
+            user_cls, _PartialFunctionFlags.ENTER_PRE_SNAPSHOT
+        ) and not _find_partial_methods_for_user_cls(user_cls, _PartialFunctionFlags.ENTER_POST_SNAPSHOT):
+            raise InvalidError("Server class must have an @modal.enter() to setup the server.")
+
+        # Check for disallowed decorators
+        # @modal.method() not allowed
+        if _find_partial_methods_for_user_cls(user_cls, _PartialFunctionFlags.CALLABLE_INTERFACE).values():
+            raise InvalidError(
+                f"Server class {user_cls.__name__} cannot have `@modal.method()` decorated functions. "
+                "Servers only expose HTTP endpoints."
+            )
+        # @enter with snap=True without enable_memory_snapshot
+        if (
+            _find_partial_methods_for_user_cls(user_cls, _PartialFunctionFlags.ENTER_PRE_SNAPSHOT)
+            and not enable_memory_snapshot
+        ):
+            raise InvalidError(
+                "Server must have `enable_memory_snapshot=True` to use `snap=True` on `@modal.enter` methods."
+            )
+
+        if isinstance(wrapped_user_cls, _PartialFunction):
+            # @modal.concurrent not allowed on server classes
+            if wrapped_user_cls.flags & _PartialFunctionFlags.CONCURRENT:
+                raise InvalidError(
+                    f"Server class {user_cls.__name__} cannot be decorated with `@modal.concurrent()`. "
+                    "Please use `target_concurrency` param instead."
+                )
+            # @modal.http_server not allowed on server classes
+            if wrapped_user_cls.flags & _PartialFunctionFlags.HTTP_WEB_INTERFACE:
+                raise InvalidError(
+                    f"Server class {user_cls.__name__} cannot have @modal.experimental.http_server() decorator. "
+                    "Servers already expose HTTP endpoints."
+                )
+            # @modal.web_server not allowed on server classes
+            if wrapped_user_cls.flags & _PartialFunctionFlags.WEB_INTERFACE:
+                raise InvalidError(
+                    f"Server class {user_cls.__name__} cannot be decorated with `@modal.web_server()`. "
+                    "Servers already expose HTTP endpoints."
+                )
+
+    @staticmethod
+    def _validate_construction_mechanism(wrapped_user_cls: "type | _PartialFunction"):
+        """Validate that the server class doesn't have a custom constructor."""
+        # Extract the underlying class if wrapped in a _PartialFunction (e.g., from @modal.clustered())
+        user_cls = _Server._extract_user_cls(wrapped_user_cls)
+
+        if user_cls.__init__ != object.__init__:  # type: ignore
+            raise InvalidError(
+                f"Server class {user_cls.__name__} cannot have a custom __init__ method. "
+                "Use @modal.enter() for initialization logic instead."
+            )

{modal-1.3.1.dev26 → modal-1.3.1.dev27}/modal/client.pyi

@@ -33,7 +33,7 @@ class _Client:
         server_url: str,
         client_type: int,
         credentials: typing.Optional[tuple[str, str]],
-        version: str = "1.3.1.dev26",
+        version: str = "1.3.1.dev27",
     ):
         """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.3.1.dev26",
+        version: str = "1.3.1.dev27",
     ):
         """mdmd:hidden
         The Modal client object is not intended to be instantiated directly by users.

{modal-1.3.1.dev26 → modal-1.3.1.dev27}/modal/experimental/flash.py

@@ -15,6 +15,7 @@ from modal.cls import _Cls
 from modal.dict import _Dict
 from modal_proto import api_pb2
 
+from .._server import validate_http_server_config
 from .._tunnel import _forward as _forward_tunnel
 from .._utils.async_utils import synchronize_api, synchronizer
 from ..client import _Client
@@ -142,7 +143,6 @@ class _FlashManager:
                         )
                         self.num_failures += 1
                         await self.client.stub.FlashContainerDeregister(api_pb2.FlashContainerDeregisterRequest())
-
             except asyncio.CancelledError:
                 logger.warning("[Modal Flash] Shutting down...")
                 break
@@ -670,12 +670,7 @@ def _http_server(
         raise InvalidError(
             "Positional arguments are not allowed. Did you forget parentheses? Suggestion: `@modal.http_server()`."
         )
-    if not isinstance(port, int) or port < 1 or port > 65535:
-        raise InvalidError("First argument of `@http_server` must be a local port, such as `@http_server(8000)`.")
-    if startup_timeout <= 0:
-        raise InvalidError("The `startup_timeout` argument of `@http_server` must be positive.")
-    if exit_grace_period is not None and exit_grace_period < 0:
-        raise InvalidError("The `exit_grace_period` argument of `@http_server` must be non-negative.")
+    validate_http_server_config(port, proxy_regions, startup_timeout, exit_grace_period)
 
     from modal._partial_function import _PartialFunction, _PartialFunctionParams
 

{modal-1.3.1.dev26 → modal-1.3.1.dev27}/modal/functions.pyi

@@ -407,7 +407,7 @@ class Function(
 
     _call_generator: ___call_generator_spec
 
-    class __remote_spec(typing_extensions.Protocol[P_INNER, ReturnType_INNER]):
+    class __remote_spec(typing_extensions.Protocol[ReturnType_INNER, P_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."""
             ...
@@ -416,7 +416,7 @@ class Function(
             """Calls the function remotely, executing it with the given arguments and returning the execution's result."""
             ...
 
-    remote: __remote_spec[modal._functions.P, modal._functions.ReturnType]
+    remote: __remote_spec[modal._functions.ReturnType, modal._functions.P]
 
     class __remote_gen_spec(typing_extensions.Protocol):
         def __call__(self, /, *args, **kwargs) -> typing.Generator[typing.Any, None, None]:
@@ -443,7 +443,7 @@ class Function(
         """
         ...
 
-    class ___experimental_spawn_spec(typing_extensions.Protocol[P_INNER, ReturnType_INNER]):
+    class ___experimental_spawn_spec(typing_extensions.Protocol[ReturnType_INNER, P_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.
 
@@ -466,7 +466,7 @@ class Function(
             """
             ...
 
-    _experimental_spawn: ___experimental_spawn_spec[modal._functions.P, modal._functions.ReturnType]
+    _experimental_spawn: ___experimental_spawn_spec[modal._functions.ReturnType, modal._functions.P]
 
     class ___spawn_map_inner_spec(typing_extensions.Protocol[P_INNER]):
         def __call__(self, /, *args: P_INNER.args, **kwargs: P_INNER.kwargs) -> None: ...
@@ -474,7 +474,7 @@ class Function(
 
     _spawn_map_inner: ___spawn_map_inner_spec[modal._functions.P]
 
-    class __spawn_spec(typing_extensions.Protocol[P_INNER, ReturnType_INNER]):
+    class __spawn_spec(typing_extensions.Protocol[ReturnType_INNER, P_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.
 
@@ -495,7 +495,7 @@ class Function(
             """
             ...
 
-    spawn: __spawn_spec[modal._functions.P, modal._functions.ReturnType]
+    spawn: __spawn_spec[modal._functions.ReturnType, modal._functions.P]
 
     def get_raw_f(self) -> collections.abc.Callable[..., typing.Any]:
         """Return the inner Python object wrapped by this Modal Function."""

modal-1.3.1.dev27/modal/server.py

@@ -0,0 +1,5 @@
+# Copyright Modal Labs 2026
+from ._server import _Server
+from ._utils.async_utils import synchronize_api
+
+Server = synchronize_api(_Server, target_module=__name__)

modal-1.3.1.dev27/modal/server.pyi

@@ -0,0 +1,147 @@
+import modal.app
+import modal.client
+import modal.functions
+import modal.partial_function
+import typing
+import typing_extensions
+
+class Server:
+    """Server runs an HTTP server started in an `@modal.enter` method.
+
+    See [lifecycle hooks](https://modal.com/docs/guide/lifecycle-functions) for more information.
+
+    Generally, you will not construct a Server directly.
+    Instead, use the [`@app.server()`](https://modal.com/docs/reference/modal.App#server) decorator.
+
+    ```python notest
+    @app.server(port=8000, proxy_regions=["us-east", "us-west"])
+    class MyServer:
+        @modal.enter()
+        def start_server(self):
+            self.process = subprocess.Popen(["python3", "-m", "http.server", "8080"])
+    ```
+    """
+
+    _user_cls: typing.Optional[type]
+    _service_function: modal.functions.Function
+    _app: typing.Optional[modal.app.App]
+
+    def __init__(self, /, *args, **kwargs):
+        """Initialize self.  See help(type(self)) for accurate signature."""
+        ...
+
+    def _get_user_cls(self) -> type: ...
+    def _get_app(self) -> modal.app.App: ...
+    def _get_service_function(self) -> modal.functions.Function: ...
+    @staticmethod
+    def _extract_user_cls(wrapped_user_cls: typing.Union[type, modal.partial_function.PartialFunction]) -> type: ...
+
+    class __get_urls_spec(typing_extensions.Protocol):
+        def __call__(self, /) -> typing.Optional[list[str]]: ...
+        async def aio(self, /) -> typing.Optional[list[str]]: ...
+
+    get_urls: __get_urls_spec
+
+    class __update_autoscaler_spec(typing_extensions.Protocol):
+        def __call__(
+            self,
+            /,
+            *,
+            min_containers: typing.Optional[int] = None,
+            max_containers: typing.Optional[int] = None,
+            buffer_containers: typing.Optional[int] = None,
+            scaledown_window: typing.Optional[int] = None,
+        ) -> None:
+            """Override the current autoscaler behavior for this Server.
+
+            Unspecified parameters will retain their current value.
+
+            Examples:
+            ```python notest
+            server = modal.Server.from_name("my-app", "Server")
+
+            # Always have at least 2 containers running, with an extra buffer of 2 containers
+            server.update_autoscaler(min_containers=2, buffer_containers=1)
+
+            # Limit this Server to avoid spinning up more than 5 containers
+            server.update_autoscaler(max_containers=5)
+            ```
+            """
+            ...
+
+        async def aio(
+            self,
+            /,
+            *,
+            min_containers: typing.Optional[int] = None,
+            max_containers: typing.Optional[int] = None,
+            buffer_containers: typing.Optional[int] = None,
+            scaledown_window: typing.Optional[int] = None,
+        ) -> None:
+            """Override the current autoscaler behavior for this Server.
+
+            Unspecified parameters will retain their current value.
+
+            Examples:
+            ```python notest
+            server = modal.Server.from_name("my-app", "Server")
+
+            # Always have at least 2 containers running, with an extra buffer of 2 containers
+            server.update_autoscaler(min_containers=2, buffer_containers=1)
+
+            # Limit this Server to avoid spinning up more than 5 containers
+            server.update_autoscaler(max_containers=5)
+            ```
+            """
+            ...
+
+    update_autoscaler: __update_autoscaler_spec
+
+    class __hydrate_spec(typing_extensions.Protocol):
+        def __call__(self, /, client: typing.Optional[modal.client.Client] = None) -> Server: ...
+        async def aio(self, /, client: typing.Optional[modal.client.Client] = None) -> Server: ...
+
+    hydrate: __hydrate_spec
+
+    @staticmethod
+    def _from_local(
+        wrapped_user_cls: typing.Union[type, modal.partial_function.PartialFunction],
+        app: modal.app.App,
+        service_function: modal.functions.Function,
+    ) -> Server:
+        """Create a Server from a local class definition."""
+        ...
+
+    @classmethod
+    def from_name(
+        cls: type[Server],
+        app_name: str,
+        name: str,
+        *,
+        environment_name: typing.Optional[str] = None,
+        client: typing.Optional[modal.client.Client] = None,
+    ) -> Server:
+        """Reference a Server from a deployed App by its name.
+
+        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
+        server = modal.Server.from_name("other-app", "Server")
+        ```
+        """
+        ...
+
+    def _is_local(self) -> bool:
+        """Returns True if this Server has local source code available."""
+        ...
+
+    @staticmethod
+    def _validate_wrapped_user_cls_decorators(
+        wrapped_user_cls: typing.Union[type, modal.partial_function.PartialFunction], enable_memory_snapshot: bool
+    ): ...
+    @staticmethod
+    def _validate_construction_mechanism(wrapped_user_cls: typing.Union[type, modal.partial_function.PartialFunction]):
+        """Validate that the server class doesn't have a custom constructor."""
+        ...

{modal-1.3.1.dev26 → modal-1.3.1.dev27}/modal.egg-info/PKG-INFO

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

{modal-1.3.1.dev26 → modal-1.3.1.dev27}/modal.egg-info/SOURCES.txt

@@ -19,6 +19,7 @@ modal/_pty.py
 modal/_resolver.py
 modal/_resources.py
 modal/_serialization.py
+modal/_server.py
 modal/_traceback.py
 modal/_tunnel.py
 modal/_tunnel.pyi
@@ -78,6 +79,8 @@ modal/schedule.py
 modal/scheduler_placement.py
 modal/secret.py
 modal/secret.pyi
+modal/server.py
+modal/server.pyi
 modal/serving.py
 modal/serving.pyi
 modal/snapshot.py

{modal-1.3.1.dev26 → modal-1.3.1.dev27}/modal_version/__init__.py

@@ -1,4 +1,4 @@
 # Copyright Modal Labs 2025
 """Supplies the current version of the modal client library."""
 
-__version__ = "1.3.1.dev26"
+__version__ = "1.3.1.dev27"