modal 0.73.146__py3-none-any.whl → 0.73.148__py3-none-any.whl

modal/_partial_function.py

@@ -3,6 +3,7 @@ import enum
 import inspect
 import typing
 from collections.abc import Coroutine, Iterable
+from dataclasses import asdict, dataclass
 from typing import (
     Any,
     Callable,
@@ -29,80 +30,180 @@ if typing.TYPE_CHECKING:
 
 
 class _PartialFunctionFlags(enum.IntFlag):
-    FUNCTION = 1
-    BUILD = 2
-    ENTER_PRE_SNAPSHOT = 4
-    ENTER_POST_SNAPSHOT = 8
-    EXIT = 16
-    BATCHED = 32
-    CLUSTERED = 64  # Experimental: Clustered functions
+    # Lifecycle method flags
+    BUILD = 1  # Deprecated, will be removed
+    ENTER_PRE_SNAPSHOT = 2
+    ENTER_POST_SNAPSHOT = 4
+    EXIT = 8
+    # Interface flags
+    CALLABLE_INTERFACE = 16
+    WEB_INTERFACE = 32
+    # Service decorator flags
+    # It's, unclear if we need these, as we can also generally infer based on some params being set
+    # In the current state where @modal.batched is used _instead_ of `@modal.method`, we need to give
+    # `@modal.batched` two roles (exposing the callable interface, adding batching semantics).
+    # But it's probably better to make `@modal.batched` and `@modal.method` stackable, or to move
+    # `@modal.batched` to be a class-level decorator since it primarily governs service behavior.
+    BATCHED = 64
+    CONCURRENT = 128
+    CLUSTERED = 256  # Experimental: Clustered functions
 
     @staticmethod
     def all() -> int:
         return ~_PartialFunctionFlags(0)
 
+    @staticmethod
+    def lifecycle_flags() -> int:
+        return (
+            _PartialFunctionFlags.BUILD  # Deprecated, will be removed
+            | _PartialFunctionFlags.ENTER_PRE_SNAPSHOT
+            | _PartialFunctionFlags.ENTER_POST_SNAPSHOT
+            | _PartialFunctionFlags.EXIT
+        )
+
+    @staticmethod
+    def interface_flags() -> int:
+        return _PartialFunctionFlags.CALLABLE_INTERFACE | _PartialFunctionFlags.WEB_INTERFACE
+
+
+@dataclass
+class _PartialFunctionParams:
+    webhook_config: Optional[api_pb2.WebhookConfig] = None
+    is_generator: Optional[bool] = None
+    force_build: Optional[bool] = None
+    batch_max_size: Optional[int] = None
+    batch_wait_ms: Optional[int] = None
+    cluster_size: Optional[int] = None
+    max_concurrent_inputs: Optional[int] = None
+    target_concurrent_inputs: Optional[int] = None
+    build_timeout: Optional[int] = None
+
+    def update(self, other: "_PartialFunctionParams") -> None:
+        """Update self with params set in other."""
+        for key, val in asdict(other).items():
+            if val is not None:
+                if getattr(self, key, None) is not None:
+                    raise InvalidError(f"Cannot set `{key}` twice.")
+                setattr(self, key, val)
+
 
 P = typing_extensions.ParamSpec("P")
 ReturnType = typing_extensions.TypeVar("ReturnType", covariant=True)
 OriginalReturnType = typing_extensions.TypeVar("OriginalReturnType", covariant=True)
+NullaryFuncOrMethod = Union[Callable[[], Any], Callable[[Any], Any]]
+NullaryMethod = Callable[[Any], Any]
 
 
 class _PartialFunction(typing.Generic[P, ReturnType, OriginalReturnType]):
-    """Intermediate function, produced by @enter, @build, @method, @web_endpoint, or @batched"""
+    """Object produced by a decorator in the `modal` namespace
+
+    The object will eventually by consumed by an App decorator.
+    """
 
-    raw_f: Callable[P, ReturnType]
+    raw_f: Optional[Callable[P, ReturnType]]  # function or method
+    user_cls: Optional[type] = None  # class
     flags: _PartialFunctionFlags
-    webhook_config: Optional[api_pb2.WebhookConfig]
-    is_generator: bool
-    batch_max_size: Optional[int]
-    batch_wait_ms: Optional[int]
-    force_build: bool
-    cluster_size: Optional[int]  # Experimental: Clustered functions
-    build_timeout: Optional[int]
-    max_concurrent_inputs: Optional[int]
-    target_concurrent_inputs: Optional[int]
+    params: _PartialFunctionParams
+    registered: bool
 
     def __init__(
         self,
-        raw_f: Callable[P, ReturnType],
+        obj: Union[Callable[P, ReturnType], type],
         flags: _PartialFunctionFlags,
-        *,
-        webhook_config: Optional[api_pb2.WebhookConfig] = None,
-        is_generator: Optional[bool] = None,
-        batch_max_size: Optional[int] = None,
-        batch_wait_ms: Optional[int] = None,
-        cluster_size: Optional[int] = None,  # Experimental: Clustered functions
-        force_build: bool = False,
-        build_timeout: Optional[int] = None,
-        max_concurrent_inputs: Optional[int] = None,
-        target_concurrent_inputs: Optional[int] = None,
+        params: _PartialFunctionParams,
     ):
-        self.raw_f = raw_f
-        self.flags = flags
-        self.webhook_config = webhook_config
-        if is_generator is None:
-            # auto detect - doesn't work if the function *returns* a generator
-            final_is_generator = inspect.isgeneratorfunction(raw_f) or inspect.isasyncgenfunction(raw_f)
+        if isinstance(obj, type):
+            self.user_cls = obj
+            self.raw_f = None
         else:
-            final_is_generator = is_generator
-
-        self.is_generator = final_is_generator
-        self.wrapped = False  # Make sure that this was converted into a FunctionHandle
-        self.batch_max_size = batch_max_size
-        self.batch_wait_ms = batch_wait_ms
-        self.cluster_size = cluster_size  # Experimental: Clustered functions
-        self.force_build = force_build
-        self.build_timeout = build_timeout
-        self.max_concurrent_inputs = max_concurrent_inputs
-        self.target_concurrent_inputs = target_concurrent_inputs
+            self.raw_f = obj
+            self.user_cls = None
+        self.flags = flags
+        self.params = params
+        self.registered = False
+        self.validate_flag_composition()
+
+    def stack(self, flags: _PartialFunctionFlags, params: _PartialFunctionParams) -> typing_extensions.Self:
+        """Implement decorator composition by combining the flags and params."""
+        self.flags |= flags
+        self.params.update(params)
+        self.validate_flag_composition()
+        return self
+
+    def validate_flag_composition(self) -> None:
+        """Validate decorator composition based on PartialFunctionFlags."""
+        uses_interface_flags = self.flags & _PartialFunctionFlags.interface_flags()
+        uses_lifecycle_flags = self.flags & _PartialFunctionFlags.lifecycle_flags()
+        if uses_interface_flags and uses_lifecycle_flags:
+            self.registered = True  # Hacky, avoid false-positive warning
+            raise InvalidError("Interface decorators cannot be combined with lifecycle decorators.")
+
+        has_web_interface = self.flags & _PartialFunctionFlags.WEB_INTERFACE
+        has_callable_interface = self.flags & _PartialFunctionFlags.CALLABLE_INTERFACE
+        if has_web_interface and has_callable_interface:
+            self.registered = True  # Hacky, avoid false-positive warning
+            raise InvalidError("Callable decorators cannot be combined with web interface decorators.")
+
+    def validate_obj_compatibility(
+        self, decorator_name: str, require_sync: bool = False, require_nullary: bool = False
+    ) -> None:
+        """Enforce compatibility with the wrapped object; called from individual decorator functions."""
+        from .cls import _Cls  # Avoid circular import
+
+        uses_lifecycle_flags = self.flags & _PartialFunctionFlags.lifecycle_flags()
+        uses_interface_flags = self.flags & _PartialFunctionFlags.interface_flags()
+        if self.user_cls is not None and (uses_lifecycle_flags or uses_interface_flags):
+            self.registered = True  # Hacky, avoid false-positive warning
+            raise InvalidError(
+                f"Cannot apply `@modal.{decorator_name}` to a class. Hint: consider applying to a method instead."
+            )
+
+        wrapped_object = self.raw_f or self.user_cls
+        if isinstance(wrapped_object, _Function):
+            self.registered = True  # Hacky, avoid false-positive warning
+            raise InvalidError(
+                f"Cannot stack `@modal.{decorator_name}` on top of `@app.function`."
+                " Hint: swap the order of the decorators."
+            )
+        elif isinstance(wrapped_object, _Cls):
+            self.registered = True  # Hacky, avoid false-positive warning
+            raise InvalidError(
+                f"Cannot stack `@modal.{decorator_name}` on top of `@app.cls()`."
+                " Hint: swap the order of the decorators."
+            )
+
+        # Run some assertions about a callable wrappee defined by the specific decorator used
+        if self.raw_f is not None:
+            if not callable(self.raw_f):
+                self.registered = True  # Hacky, avoid false-positive warning
+                raise InvalidError(f"The object wrapped by `@modal.{decorator_name}` must be callable.")
+
+            if require_sync and inspect.iscoroutinefunction(self.raw_f):
+                self.registered = True  # Hacky, avoid false-positive warning
+                raise InvalidError(f"`@modal.{decorator_name}` can't be applied to an async function.")
+
+            if require_nullary and callable_has_non_self_params(self.raw_f):
+                self.registered = True  # Hacky, avoid false-positive warning
+                if callable_has_non_self_non_default_params(self.raw_f):
+                    raise InvalidError(f"Functions obj by `@modal.{decorator_name}` can't have parameters.")
+                else:
+                    # TODO(michael): probably fine to just make this an error at this point
+                    # but best to do it in a separate PR
+                    deprecation_warning(
+                        (2024, 9, 4),
+                        f"The function obj by `@modal.{decorator_name}` has default parameters, "
+                        "but shouldn't have any parameters - Modal will drop support for "
+                        "default parameters in a future release.",
+                    )
 
     def _get_raw_f(self) -> Callable[P, ReturnType]:
+        assert self.raw_f is not None
         return self.raw_f
 
     def _is_web_endpoint(self) -> bool:
-        if self.webhook_config is None:
+        if self.params.webhook_config is None:
             return False
-        return self.webhook_config.type != api_pb2.WEBHOOK_TYPE_UNSPECIFIED
+        return self.params.webhook_config.type != api_pb2.WEBHOOK_TYPE_UNSPECIFIED
 
     def __get__(self, obj, objtype=None) -> _Function[P, ReturnType, OriginalReturnType]:
         # to type checkers, any @method or similar function on a modal class, would appear to be
@@ -111,6 +212,7 @@ class _PartialFunction(typing.Generic[P, ReturnType, OriginalReturnType]):
         # However, modal classes are *actually* Cls instances (which isn't reflected in type checkers
         # due to Python's lack of type chekcing intersection types), so at runtime the Cls instance would
         # use its __getattr__ rather than this descriptor.
+        assert self.raw_f is not None  # Should only be relevant in a method context
         k = self.raw_f.__name__
         if obj:  # accessing the method on an instance of a class, e.g. `MyClass().fun``
             if hasattr(obj, "_modal_functions"):
@@ -126,37 +228,26 @@ class _PartialFunction(typing.Generic[P, ReturnType, OriginalReturnType]):
                 return self.raw_f.__get__(obj, objtype)
 
         else:  # accessing a method directly on the class, e.g. `MyClass.fun`
-            # This happens mainly during serialization of the wrapped underlying class of a Cls
+            # This happens mainly during serialization of the obj underlying class of a Cls
             # since we don't have the instance info here we just return the PartialFunction itself
             # to let it be bound to a variable and become a Function later on
             return self  # type: ignore  # this returns a PartialFunction in a special internal case
 
     def __del__(self):
-        if (self.flags & _PartialFunctionFlags.FUNCTION) and self.wrapped is False:
+        if self.registered is False:
+            if self.raw_f is not None:
+                name, object_type, suggestion = self.raw_f.__name__, "function", "@app.function or @app.cls"
+            elif self.user_cls is not None:
+                name, object_type, suggestion = self.user_cls.__name__, "class", "@app.cls"
             logger.warning(
-                f"Method or web function {self.raw_f} was never turned into a function."
-                " Did you forget a @app.function or @app.cls decorator?"
+                f"The `{name}` {object_type} was never registered with the App."
+                f" Did you forget an {suggestion} decorator?"
             )
 
-    def add_flags(self, flags) -> "_PartialFunction":
-        # Helper method used internally when stacking decorators
-        self.wrapped = True
-        return _PartialFunction(
-            raw_f=self.raw_f,
-            flags=(self.flags | flags),
-            webhook_config=self.webhook_config,
-            batch_max_size=self.batch_max_size,
-            batch_wait_ms=self.batch_wait_ms,
-            force_build=self.force_build,
-            build_timeout=self.build_timeout,
-            max_concurrent_inputs=self.max_concurrent_inputs,
-            target_concurrent_inputs=self.target_concurrent_inputs,
-        )
-
 
 def _find_partial_methods_for_user_cls(user_cls: type[Any], flags: int) -> dict[str, _PartialFunction]:
     """Grabs all method on a user class, and returns partials. Includes legacy methods."""
-    from .partial_function import PartialFunction  # wrapped type
+    from .partial_function import PartialFunction  # obj type
 
     partial_functions: dict[str, _PartialFunction] = {}
     for parent_cls in reversed(user_cls.mro()):
@@ -173,7 +264,11 @@ def _find_partial_methods_for_user_cls(user_cls: type[Any], flags: int) -> dict[
 def _find_callables_for_obj(user_obj: Any, flags: int) -> dict[str, Callable[..., Any]]:
     """Grabs all methods for an object, and binds them to the class"""
     user_cls: type = type(user_obj)
-    return {k: pf.raw_f.__get__(user_obj) for k, pf in _find_partial_methods_for_user_cls(user_cls, flags).items()}
+    return {
+        k: pf.raw_f.__get__(user_obj)
+        for k, pf in _find_partial_methods_for_user_cls(user_cls, flags).items()
+        if pf.raw_f is not None  # Should be true for output of _find_partial_methods_for_user_cls, but hard to annotate
+    }
 
 
 class _MethodDecoratorType:
@@ -222,23 +317,24 @@ def _method(
             "Positional arguments are not allowed. Did you forget parentheses? Suggestion: `@modal.method()`."
         )
 
-    def wrapper(raw_f: Callable[..., Any]) -> _PartialFunction:
-        nonlocal is_generator
-        if isinstance(raw_f, _PartialFunction) and raw_f.webhook_config:
-            raw_f.wrapped = True  # suppress later warning
-            raise InvalidError(
-                "Web endpoints on classes should not be wrapped by `@method`. "
-                "Suggestion: remove the `@method` decorator."
-            )
-        if isinstance(raw_f, _PartialFunction) and raw_f.batch_max_size is not None:
-            raw_f.wrapped = True  # suppress later warning
-            raise InvalidError(
-                "Batched function on classes should not be wrapped by `@method`. "
-                "Suggestion: remove the `@method` decorator."
-            )
-        return _PartialFunction(raw_f, _PartialFunctionFlags.FUNCTION, is_generator=is_generator)
+    def wrapper(obj: Union[Callable[..., Any], _PartialFunction]) -> _PartialFunction:
+        flags = _PartialFunctionFlags.CALLABLE_INTERFACE
 
-    return wrapper  # type: ignore   # synchronicity issue with wrapped vs unwrapped types and protocols
+        nonlocal is_generator  # TODO(michael): we are likely to deprecate the explicit is_generator param
+        if is_generator is None:
+            callable = obj.raw_f if isinstance(obj, _PartialFunction) else obj
+            is_generator = inspect.isgeneratorfunction(callable) or inspect.isasyncgenfunction(callable)
+        params = _PartialFunctionParams(is_generator=is_generator)
+
+        if isinstance(obj, _PartialFunction):
+            pf = obj.stack(flags, params)
+        else:
+            pf = _PartialFunction(obj, flags, params)
+        pf.validate_obj_compatibility("method")
+        return pf
+
+    # TODO(michael) verify that we still need the type: ignore
+    return wrapper  # type: ignore  # synchronicity issue with obj vs unwrapped types and protocols
 
 
 def _parse_custom_domains(custom_domains: Optional[Iterable[str]] = None) -> list[api_pb2.CustomDomainConfig]:
@@ -259,7 +355,10 @@ def _fastapi_endpoint(
     custom_domains: Optional[Iterable[str]] = None,  # Custom fully-qualified domain name (FQDN) for the endpoint.
     docs: bool = False,  # Whether to enable interactive documentation for this endpoint at /docs.
     requires_proxy_auth: bool = False,  # Require Modal-Key and Modal-Secret HTTP Headers on requests.
-) -> Callable[[Callable[P, ReturnType]], _PartialFunction[P, ReturnType, ReturnType]]:
+) -> Callable[
+    [Union[_PartialFunction[P, ReturnType, ReturnType], Callable[P, ReturnType]]],
+    _PartialFunction[P, ReturnType, ReturnType],
+]:
     """Convert a function into a basic web endpoint by wrapping it with a FastAPI App.
 
     Modal will internally use [FastAPI](https://fastapi.tiangolo.com/) to expose a
@@ -285,27 +384,28 @@ def _fastapi_endpoint(
             "Positional arguments are not allowed. Did you forget parentheses? Suggestion: `@modal.fastapi_endpoint()`."
         )
 
-    def wrapper(raw_f: Callable[..., Any]) -> _PartialFunction:
-        if isinstance(raw_f, _Function):
-            raw_f = raw_f.get_raw_f()
-            raise InvalidError(
-                f"Applying decorators for {raw_f} in the wrong order!\nUsage:\n\n"
-                "@app.function()\n@app.fastapi_endpoint()\ndef my_webhook():\n    ..."
-            )
+    webhook_config = api_pb2.WebhookConfig(
+        type=api_pb2.WEBHOOK_TYPE_FUNCTION,
+        method=method,
+        web_endpoint_docs=docs,
+        requested_suffix=label or "",
+        async_mode=api_pb2.WEBHOOK_ASYNC_MODE_AUTO,
+        custom_domains=_parse_custom_domains(custom_domains),
+        requires_proxy_auth=requires_proxy_auth,
+    )
 
-        return _PartialFunction(
-            raw_f,
-            _PartialFunctionFlags.FUNCTION,
-            webhook_config=api_pb2.WebhookConfig(
-                type=api_pb2.WEBHOOK_TYPE_FUNCTION,
-                method=method,
-                web_endpoint_docs=docs,
-                requested_suffix=label or "",
-                async_mode=api_pb2.WEBHOOK_ASYNC_MODE_AUTO,
-                custom_domains=_parse_custom_domains(custom_domains),
-                requires_proxy_auth=requires_proxy_auth,
-            ),
-        )
+    flags = _PartialFunctionFlags.WEB_INTERFACE
+    params = _PartialFunctionParams(webhook_config=webhook_config)
+
+    def wrapper(
+        obj: Union[_PartialFunction[P, ReturnType, ReturnType], Callable[P, ReturnType]],
+    ) -> _PartialFunction[P, ReturnType, ReturnType]:
+        if isinstance(obj, _PartialFunction):
+            pf = obj.stack(flags, params)
+        else:
+            pf = _PartialFunction(obj, flags, params)
+        pf.validate_obj_compatibility("fastapi_endpoint")
+        return pf
 
     return wrapper
 
@@ -320,7 +420,10 @@ def _web_endpoint(
         Iterable[str]
     ] = None,  # Create an endpoint using a custom domain fully-qualified domain name (FQDN).
     requires_proxy_auth: bool = False,  # Require Modal-Key and Modal-Secret HTTP Headers on requests.
-) -> Callable[[Callable[P, ReturnType]], _PartialFunction[P, ReturnType, ReturnType]]:
+) -> Callable[
+    [Union[_PartialFunction[P, ReturnType, ReturnType], Callable[P, ReturnType]]],
+    _PartialFunction[P, ReturnType, ReturnType],
+]:
     """Register a basic web endpoint with this application.
 
     DEPRECATED: This decorator has been renamed to `@modal.fastapi_endpoint`.
@@ -349,27 +452,28 @@ def _web_endpoint(
         (2025, 3, 5), "The `@modal.web_endpoint` decorator has been renamed to `@modal.fastapi_endpoint`."
     )
 
-    def wrapper(raw_f: Callable[..., Any]) -> _PartialFunction:
-        if isinstance(raw_f, _Function):
-            raw_f = raw_f.get_raw_f()
-            raise InvalidError(
-                f"Applying decorators for {raw_f} in the wrong order!\nUsage:\n\n"
-                "@app.function()\n@modal.web_endpoint()\ndef my_webhook():\n    ..."
-            )
+    webhook_config = api_pb2.WebhookConfig(
+        type=api_pb2.WEBHOOK_TYPE_FUNCTION,
+        method=method,
+        web_endpoint_docs=docs,
+        requested_suffix=label or "",
+        async_mode=api_pb2.WEBHOOK_ASYNC_MODE_AUTO,
+        custom_domains=_parse_custom_domains(custom_domains),
+        requires_proxy_auth=requires_proxy_auth,
+    )
 
-        return _PartialFunction(
-            raw_f,
-            _PartialFunctionFlags.FUNCTION,
-            webhook_config=api_pb2.WebhookConfig(
-                type=api_pb2.WEBHOOK_TYPE_FUNCTION,
-                method=method,
-                web_endpoint_docs=docs,
-                requested_suffix=label,
-                async_mode=api_pb2.WEBHOOK_ASYNC_MODE_AUTO,
-                custom_domains=_parse_custom_domains(custom_domains),
-                requires_proxy_auth=requires_proxy_auth,
-            ),
-        )
+    flags = _PartialFunctionFlags.WEB_INTERFACE
+    params = _PartialFunctionParams(webhook_config=webhook_config)
+
+    def wrapper(
+        obj: Union[_PartialFunction[P, ReturnType, ReturnType], Callable[P, ReturnType]],
+    ) -> _PartialFunction[P, ReturnType, ReturnType]:
+        if isinstance(obj, _PartialFunction):
+            pf = obj.stack(flags, params)
+        else:
+            pf = _PartialFunction(obj, flags, params)
+        pf.validate_obj_compatibility("web_endpoint")
+        return pf
 
     return wrapper
 
@@ -380,7 +484,7 @@ def _asgi_app(
     label: Optional[str] = None,  # Label for created endpoint. Final subdomain will be <workspace>--<label>.modal.run.
     custom_domains: Optional[Iterable[str]] = None,  # Deploy this endpoint on a custom domain.
     requires_proxy_auth: bool = False,  # Require Modal-Key and Modal-Secret HTTP Headers on requests.
-) -> Callable[[Callable[..., Any]], _PartialFunction]:
+) -> Callable[[Union[_PartialFunction, NullaryFuncOrMethod]], _PartialFunction]:
     """Decorator for registering an ASGI app with a Modal function.
 
     Asynchronous Server Gateway Interface (ASGI) is a standard for Python
@@ -409,35 +513,24 @@ def _asgi_app(
             "Positional arguments are not allowed. Did you forget parentheses? Suggestion: `@modal.asgi_app()`."
         )
 
-    def wrapper(raw_f: Callable[..., Any]) -> _PartialFunction:
-        if callable_has_non_self_params(raw_f):
-            if callable_has_non_self_non_default_params(raw_f):
-                raise InvalidError(
-                    f"ASGI app function {raw_f.__name__} can't have parameters. See https://modal.com/docs/guide/webhooks#asgi."
-                )
-            else:
-                deprecation_warning(
-                    (2024, 9, 4),
-                    f"ASGI app function {raw_f.__name__} has default parameters, but shouldn't have any parameters - "
-                    f"Modal will drop support for default parameters in a future release.",
-                )
+    webhook_config = api_pb2.WebhookConfig(
+        type=api_pb2.WEBHOOK_TYPE_ASGI_APP,
+        requested_suffix=label or "",
+        async_mode=api_pb2.WEBHOOK_ASYNC_MODE_AUTO,
+        custom_domains=_parse_custom_domains(custom_domains),
+        requires_proxy_auth=requires_proxy_auth,
+    )
 
-        if inspect.iscoroutinefunction(raw_f):
-            raise InvalidError(
-                f"ASGI app function {raw_f.__name__} is an async function. Only sync Python functions are supported."
-            )
+    flags = _PartialFunctionFlags.WEB_INTERFACE
+    params = _PartialFunctionParams(webhook_config=webhook_config)
 
-        return _PartialFunction(
-            raw_f,
-            _PartialFunctionFlags.FUNCTION,
-            webhook_config=api_pb2.WebhookConfig(
-                type=api_pb2.WEBHOOK_TYPE_ASGI_APP,
-                requested_suffix=label,
-                async_mode=api_pb2.WEBHOOK_ASYNC_MODE_AUTO,
-                custom_domains=_parse_custom_domains(custom_domains),
-                requires_proxy_auth=requires_proxy_auth,
-            ),
-        )
+    def wrapper(obj: Union[_PartialFunction, NullaryFuncOrMethod]) -> _PartialFunction:
+        if isinstance(obj, _PartialFunction):
+            pf = obj.stack(flags, params)
+        else:
+            pf = _PartialFunction(obj, flags, params)
+        pf.validate_obj_compatibility("asgi_app", require_sync=True, require_nullary=True)
+        return pf
 
     return wrapper
 
@@ -448,7 +541,7 @@ def _wsgi_app(
     label: Optional[str] = None,  # Label for created endpoint. Final subdomain will be <workspace>--<label>.modal.run.
     custom_domains: Optional[Iterable[str]] = None,  # Deploy this endpoint on a custom domain.
     requires_proxy_auth: bool = False,  # Require Modal-Key and Modal-Secret HTTP Headers on requests.
-) -> Callable[[Callable[..., Any]], _PartialFunction]:
+) -> Callable[[Union[_PartialFunction, NullaryFuncOrMethod]], _PartialFunction]:
     """Decorator for registering a WSGI app with a Modal function.
 
     Web Server Gateway Interface (WSGI) is a standard for synchronous Python web apps.
@@ -477,35 +570,24 @@ def _wsgi_app(
             "Positional arguments are not allowed. Did you forget parentheses? Suggestion: `@modal.wsgi_app()`."
         )
 
-    def wrapper(raw_f: Callable[..., Any]) -> _PartialFunction:
-        if callable_has_non_self_params(raw_f):
-            if callable_has_non_self_non_default_params(raw_f):
-                raise InvalidError(
-                    f"WSGI app function {raw_f.__name__} can't have parameters. See https://modal.com/docs/guide/webhooks#wsgi."
-                )
-            else:
-                deprecation_warning(
-                    (2024, 9, 4),
-                    f"WSGI app function {raw_f.__name__} has default parameters, but shouldn't have any parameters - "
-                    f"Modal will drop support for default parameters in a future release.",
-                )
+    webhook_config = api_pb2.WebhookConfig(
+        type=api_pb2.WEBHOOK_TYPE_WSGI_APP,
+        requested_suffix=label or "",
+        async_mode=api_pb2.WEBHOOK_ASYNC_MODE_AUTO,
+        custom_domains=_parse_custom_domains(custom_domains),
+        requires_proxy_auth=requires_proxy_auth,
+    )
 
-        if inspect.iscoroutinefunction(raw_f):
-            raise InvalidError(
-                f"WSGI app function {raw_f.__name__} is an async function. Only sync Python functions are supported."
-            )
+    flags = _PartialFunctionFlags.WEB_INTERFACE
+    params = _PartialFunctionParams(webhook_config=webhook_config)
 
-        return _PartialFunction(
-            raw_f,
-            _PartialFunctionFlags.FUNCTION,
-            webhook_config=api_pb2.WebhookConfig(
-                type=api_pb2.WEBHOOK_TYPE_WSGI_APP,
-                requested_suffix=label,
-                async_mode=api_pb2.WEBHOOK_ASYNC_MODE_AUTO,
-                custom_domains=_parse_custom_domains(custom_domains),
-                requires_proxy_auth=requires_proxy_auth,
-            ),
-        )
+    def wrapper(obj: Union[_PartialFunction, NullaryFuncOrMethod]) -> _PartialFunction:
+        if isinstance(obj, _PartialFunction):
+            pf = obj.stack(flags, params)
+        else:
+            pf = _PartialFunction(obj, flags, params)
+        pf.validate_obj_compatibility("wsgi_app", require_sync=True, require_nullary=True)
+        return pf
 
     return wrapper
 
@@ -517,7 +599,7 @@ def _web_server(
     label: Optional[str] = None,  # Label for created endpoint. Final subdomain will be <workspace>--<label>.modal.run.
     custom_domains: Optional[Iterable[str]] = None,  # Deploy this endpoint on a custom domain.
     requires_proxy_auth: bool = False,  # Require Modal-Key and Modal-Secret HTTP Headers on requests.
-) -> Callable[[Callable[..., Any]], _PartialFunction]:
+) -> Callable[[Union[_PartialFunction, NullaryFuncOrMethod]], _PartialFunction]:
     """Decorator that registers an HTTP web server inside the container.
 
     This is similar to `@asgi_app` and `@wsgi_app`, but it allows you to expose a full HTTP server
@@ -549,33 +631,33 @@ def _web_server(
     if startup_timeout <= 0:
         raise InvalidError("The `startup_timeout` argument of `@web_server` must be positive.")
 
-    def wrapper(raw_f: Callable[..., Any]) -> _PartialFunction:
-        return _PartialFunction(
-            raw_f,
-            _PartialFunctionFlags.FUNCTION,
-            webhook_config=api_pb2.WebhookConfig(
-                type=api_pb2.WEBHOOK_TYPE_WEB_SERVER,
-                requested_suffix=label,
-                async_mode=api_pb2.WEBHOOK_ASYNC_MODE_AUTO,
-                custom_domains=_parse_custom_domains(custom_domains),
-                web_server_port=port,
-                web_server_startup_timeout=startup_timeout,
-                requires_proxy_auth=requires_proxy_auth,
-            ),
-        )
+    webhook_config = api_pb2.WebhookConfig(
+        type=api_pb2.WEBHOOK_TYPE_WEB_SERVER,
+        requested_suffix=label or "",
+        async_mode=api_pb2.WEBHOOK_ASYNC_MODE_AUTO,
+        custom_domains=_parse_custom_domains(custom_domains),
+        web_server_port=port,
+        web_server_startup_timeout=startup_timeout,
+        requires_proxy_auth=requires_proxy_auth,
+    )
 
-    return wrapper
+    flags = _PartialFunctionFlags.WEB_INTERFACE
+    params = _PartialFunctionParams(webhook_config=webhook_config)
 
+    def wrapper(obj: Union[_PartialFunction, NullaryFuncOrMethod]) -> _PartialFunction:
+        if isinstance(obj, _PartialFunction):
+            pf = obj.stack(flags, params)
+        else:
+            pf = _PartialFunction(obj, flags, params)
+        pf.validate_obj_compatibility("web_server", require_sync=True, require_nullary=True)
+        return pf
 
-def _disallow_wrapping_method(f: _PartialFunction, wrapper: str) -> None:
-    if f.flags & _PartialFunctionFlags.FUNCTION:
-        f.wrapped = True  # Hack to avoid warning about not using @app.cls()
-        raise InvalidError(f"Cannot use `@{wrapper}` decorator with `@method`.")
+    return wrapper
 
 
 def _build(
     _warn_parentheses_missing=None, *, force: bool = False, timeout: int = 86400
-) -> Callable[[Union[Callable[[Any], Any], _PartialFunction]], _PartialFunction]:
+) -> Callable[[Union[_PartialFunction, NullaryMethod]], _PartialFunction]:
     """
     Decorator for methods that execute at _build time_ to create a new Image layer.
 
@@ -612,14 +694,16 @@ def _build(
         "\n\nSee https://modal.com/docs/guide/modal-1-0-migration for more information.",
     )
 
-    def wrapper(f: Union[Callable[[Any], Any], _PartialFunction]) -> _PartialFunction:
-        if isinstance(f, _PartialFunction):
-            _disallow_wrapping_method(f, "build")
-            f.force_build = force
-            f.build_timeout = timeout
-            return f.add_flags(_PartialFunctionFlags.BUILD)
+    flags = _PartialFunctionFlags.BUILD
+    params = _PartialFunctionParams(force_build=force, build_timeout=timeout)
+
+    def wrapper(obj: Union[_PartialFunction, NullaryMethod]) -> _PartialFunction:
+        if isinstance(obj, _PartialFunction):
+            pf = obj.stack(flags, params)
         else:
-            return _PartialFunction(f, _PartialFunctionFlags.BUILD, force_build=force, build_timeout=timeout)
+            pf = _PartialFunction(obj, flags, params)
+        pf.validate_obj_compatibility("build")
+        return pf
 
     return wrapper
 
@@ -628,7 +712,7 @@ def _enter(
     _warn_parentheses_missing=None,
     *,
     snap: bool = False,
-) -> Callable[[Union[Callable[[Any], Any], _PartialFunction]], _PartialFunction]:
+) -> Callable[[Union[_PartialFunction, NullaryMethod]], _PartialFunction]:
     """Decorator for methods which should be executed when a new container is started.
 
     See the [lifeycle function guide](https://modal.com/docs/guide/lifecycle-functions#enter) for more information."""
@@ -637,32 +721,22 @@ def _enter(
             "Positional arguments are not allowed. Did you forget parentheses? Suggestion: `@modal.enter()`."
         )
 
-    if snap:
-        flag = _PartialFunctionFlags.ENTER_PRE_SNAPSHOT
-    else:
-        flag = _PartialFunctionFlags.ENTER_POST_SNAPSHOT
+    flags = _PartialFunctionFlags.ENTER_PRE_SNAPSHOT if snap else _PartialFunctionFlags.ENTER_POST_SNAPSHOT
+    params = _PartialFunctionParams()
 
-    def wrapper(f: Union[Callable[[Any], Any], _PartialFunction]) -> _PartialFunction:
-        if isinstance(f, _PartialFunction):
-            _disallow_wrapping_method(f, "enter")
-            return f.add_flags(flag)
+    def wrapper(obj: Union[_PartialFunction, NullaryMethod]) -> _PartialFunction:
+        # TODO: reject stacking once depreceate @modal.build
+        if isinstance(obj, _PartialFunction):
+            pf = obj.stack(flags, params)
         else:
-            return _PartialFunction(f, flag)
+            pf = _PartialFunction(obj, flags, params)
+        pf.validate_obj_compatibility("enter")  # TODO require_nullary?
+        return pf
 
     return wrapper
 
 
-ExitHandlerType = Union[
-    # NOTE: return types of these callables should be `Union[None, Awaitable[None]]` but
-    #       synchronicity type stubs would strip Awaitable so we use Any for now
-    # Original, __exit__ style method signature (now deprecated)
-    Callable[[Any, Optional[type[BaseException]], Optional[BaseException], Any], Any],
-    # Forward-looking unparametrized method
-    Callable[[Any], Any],
-]
-
-
-def _exit(_warn_parentheses_missing=None) -> Callable[[ExitHandlerType], _PartialFunction]:
+def _exit(_warn_parentheses_missing=None) -> Callable[[NullaryMethod], _PartialFunction]:
     """Decorator for methods which should be executed when a container is about to exit.
 
     See the [lifeycle function guide](https://modal.com/docs/guide/lifecycle-functions#exit) for more information."""
@@ -671,11 +745,16 @@ def _exit(_warn_parentheses_missing=None) -> Callable[[ExitHandlerType], _Partia
             "Positional arguments are not allowed. Did you forget parentheses? Suggestion: `@modal.exit()`."
         )
 
-    def wrapper(f: ExitHandlerType) -> _PartialFunction:
-        if isinstance(f, _PartialFunction):
-            _disallow_wrapping_method(f, "exit")
+    flags = _PartialFunctionFlags.EXIT
+    params = _PartialFunctionParams()
 
-        return _PartialFunction(f, _PartialFunctionFlags.EXIT)
+    def wrapper(obj: Union[_PartialFunction, NullaryMethod]) -> _PartialFunction:
+        if isinstance(obj, _PartialFunction):
+            pf = obj.stack(flags, params)
+        else:
+            pf = _PartialFunction(obj, flags, params)
+        pf.validate_obj_compatibility("exit")  # TODO require_nullary?
+        return pf
 
     return wrapper
 
@@ -685,19 +764,30 @@ def _batched(
     *,
     max_batch_size: int,
     wait_ms: int,
-) -> Callable[[Callable[..., Any]], _PartialFunction]:
+) -> Callable[
+    [Union[_PartialFunction[P, ReturnType, ReturnType], Callable[P, ReturnType]]],
+    _PartialFunction[P, ReturnType, ReturnType],
+]:
     """Decorator for functions or class methods that should be batched.
 
     **Usage**
 
-    ```python notest
+    ```python
+    # Stack the decorator under `@app.function()` to enable dynamic batching
     @app.function()
     @modal.batched(max_batch_size=4, wait_ms=1000)
     async def batched_multiply(xs: list[int], ys: list[int]) -> list[int]:
         return [x * y for x, y in zip(xs, xs)]
 
     # call batched_multiply with individual inputs
-    batched_multiply.remote.aio(2, 100)
+    # batched_multiply.remote.aio(2, 100)
+
+    # With `@app.cls()`, apply the decorator to a method (this may change in the future)
+    @app.cls()
+    class BatchedClass:
+        @modal.batched(max_batch_size=4, wait_ms=1000)
+        def batched_multiply(self, xs: list[int], ys: list[int]) -> list[int]:
+            return [x * y for x, y in zip(xs, xs)]
     ```
 
     See the [dynamic batching guide](https://modal.com/docs/guide/dynamic-batching) for more information.
@@ -715,19 +805,18 @@ def _batched(
     if wait_ms >= MAX_BATCH_WAIT_MS:
         raise InvalidError(f"wait_ms must be less than {MAX_BATCH_WAIT_MS}.")
 
-    def wrapper(raw_f: Callable[..., Any]) -> _PartialFunction:
-        if isinstance(raw_f, _Function):
-            raw_f = raw_f.get_raw_f()
-            raise InvalidError(
-                f"Applying decorators for {raw_f} in the wrong order!\nUsage:\n\n"
-                "@app.function()\n@modal.batched()\ndef batched_function():\n    ..."
-            )
-        return _PartialFunction(
-            raw_f,
-            _PartialFunctionFlags.FUNCTION | _PartialFunctionFlags.BATCHED,
-            batch_max_size=max_batch_size,
-            batch_wait_ms=wait_ms,
-        )
+    flags = _PartialFunctionFlags.CALLABLE_INTERFACE | _PartialFunctionFlags.BATCHED
+    params = _PartialFunctionParams(batch_max_size=max_batch_size, batch_wait_ms=wait_ms)
+
+    def wrapper(
+        obj: Union[_PartialFunction[P, ReturnType, ReturnType], Callable[P, ReturnType]],
+    ) -> _PartialFunction[P, ReturnType, ReturnType]:
+        if isinstance(obj, _PartialFunction):
+            pf = obj.stack(flags, params)
+        else:
+            pf = _PartialFunction(obj, flags, params)
+        pf.validate_obj_compatibility("batched")
+        return pf
 
     return wrapper
 
@@ -737,7 +826,10 @@ def _concurrent(
     *,
     max_inputs: int,  # Hard limit on each container's input concurrency
     target_inputs: Optional[int] = None,  # Input concurrency that Modal's autoscaler should target
-) -> Callable[[Union[Callable[..., Any], _PartialFunction]], _PartialFunction]:
+) -> Callable[
+    [Union[Callable[P, ReturnType], _PartialFunction[P, ReturnType, ReturnType]]],
+    _PartialFunction[P, ReturnType, ReturnType],
+]:
     """Decorator that allows individual containers to handle multiple inputs concurrently.
 
     The concurrency mechanism depends on whether the function is async or not:
@@ -784,19 +876,55 @@ def _concurrent(
     if target_inputs and target_inputs > max_inputs:
         raise InvalidError("`target_inputs` parameter cannot be greater than `max_inputs`.")
 
-    def wrapper(obj: Union[Callable[..., Any], _PartialFunction]) -> _PartialFunction:
+    flags = _PartialFunctionFlags.CONCURRENT
+    params = _PartialFunctionParams(max_concurrent_inputs=max_inputs, target_concurrent_inputs=target_inputs)
+
+    # Note: ideally we would have some way of declaring that this decorator cannot be used on an individual method.
+    # I don't think there's any clear way for the wrapper function to know it's been passed "a method" rather than
+    # a normal function. So we need to run that check in the `@app.cls` decorator, which is a little far removed.
+
+    def wrapper(
+        obj: Union[_PartialFunction[P, ReturnType, ReturnType], Callable[P, ReturnType]],
+    ) -> _PartialFunction[P, ReturnType, ReturnType]:
         if isinstance(obj, _PartialFunction):
-            # Risky that we need to mutate the parameters here; should make this safer
-            obj.max_concurrent_inputs = max_inputs
-            obj.target_concurrent_inputs = target_inputs
-            obj.add_flags(_PartialFunctionFlags.FUNCTION)
-            return obj
-
-        return _PartialFunction(
-            obj,
-            _PartialFunctionFlags.FUNCTION,
-            max_concurrent_inputs=max_inputs,
-            target_concurrent_inputs=target_inputs,
-        )
+            pf = obj.stack(flags, params)
+        else:
+            pf = _PartialFunction(obj, flags, params)
+        pf.validate_obj_compatibility("concurrent")
+        return pf
+
+    return wrapper
+
+
+# NOTE: clustered is currently exposed through modal.experimental, not the top-level namespace
+def _clustered(size: int, broadcast: bool = True):
+    """Provision clusters of colocated and networked containers for the Function.
+
+    Parameters:
+    size: int
+        Number of containers spun up to handle each input.
+    broadcast: bool = True
+        If True, inputs will be sent simultaneously to each container. Otherwise,
+        inputs will be sent only to the rank-0 container, which is responsible for
+        delegating to the workers.
+    """
+
+    assert broadcast, "broadcast=False has not been implemented yet!"
+
+    if size <= 0:
+        raise ValueError("cluster size must be greater than 0")
+
+    flags = _PartialFunctionFlags.CLUSTERED
+    params = _PartialFunctionParams(cluster_size=size)
+
+    def wrapper(
+        obj: Union[_PartialFunction[P, ReturnType, ReturnType], Callable[P, ReturnType]],
+    ) -> _PartialFunction[P, ReturnType, ReturnType]:
+        if isinstance(obj, _PartialFunction):
+            pf = obj.stack(flags, params)
+        else:
+            pf = _PartialFunction(obj, flags, params)
+        pf.validate_obj_compatibility("clustered")
+        return pf
 
     return wrapper