[core] Fix ActorClass.remote return typing and expose Actor class methods to static analysis (#53986)

<!-- Thank you for your contribution! Please review
https://github.com/ray-project/ray/blob/master/CONTRIBUTING.rst before
opening a pull request. -->

<!-- Please add a reviewer to the assignee section when you create a PR.
If you don't have the access to it, we will shortly find a reviewer and
assign them to your PR. -->

## Why are these changes needed?
Changes in this PR are inspired by https://github.com/zen-xu/sunray

Calling `remote()` on an Actor class incorrectly returns an
`ObjectRef[...]` type. Also, the Actor class's methods are not available
to IDEs, as the type is incorrect.

This PR makes `ActorHandle` a generic type `ActorHandle[T]` and also
creates an type alias:
`ActorProxy = Union["ActorHandle[T]", type[T]]` to expose the method
signatures from the Actor class.

Here are some other possible candidates for the type name instead of
`ActorProxy` from claude:

ActorInterface
TypedActorHandle
RemoteActorType
ActorProxy
ActorT

cc @richardliaw @pcmoritz

We'll add better type hints for actor methods in a follow up PR.

The following are screenshots demonstrating the type hints in Cursor
before and after this PR:

**Before this PR**

![image](https://github.com/user-attachments/assets/681a6572-b27d-46fb-aa7e-f2d4fddc55a0)

![image](https://github.com/user-attachments/assets/3e0f2a3f-33dd-41e9-bd05-657efd1e6f59)

![image](https://github.com/user-attachments/assets/da45eb6e-479e-4114-b4cc-cefd4cefafb2)

---

**After this PR**

![image](https://github.com/user-attachments/assets/c60943a8-7e9e-4baa-88aa-57122e617889)

![image](https://github.com/user-attachments/assets/55afe9bf-282f-45cf-b615-4facde9e1623)

![image](https://github.com/user-attachments/assets/73b65613-800a-4c24-968c-7062b3956410)

## Related issue number

<!-- For example: "Closes #1234" -->

## Checks

- [x] I've signed off every commit(by using the -s flag, i.e., `git
commit -s`) in this PR.
- [x] I've run `scripts/format.sh` to lint the changes in this PR.
- [ ] I've included any doc changes needed for
https://docs.ray.io/en/master/.
- [ ] I've added any new APIs to the API Reference. For example, if I
added a
method in Tune, I've added it in `doc/source/tune/api/` under the
           corresponding `.rst` file.
- [ ] I've made sure the tests are passing. Note that there might be a
few flaky tests, see the recent failures at https://flakey-tests.ray.io/
- Testing Strategy
   - [ ] Unit tests
   - [ ] Release tests
   - [ ] This PR is not tested :(

---------

Signed-off-by: will.lin <will.lin@anyscale.com>
Signed-off-by: Philipp Moritz <pcmoritz@gmail.com>
Co-authored-by: Philipp Moritz <pcmoritz@gmail.com>
Signed-off-by: elliot-barn <elliot.barnwell@anyscale.com>

Author: 2 people

doc/source/conf.py

@@ -129,6 +129,7 @@
 # for additional context.
 nitpicky = True
 nitpick_ignore_regex = [
+    ("py:obj", "ray.actor.T"),
     ("py:class", ".*"),
     # Workaround for https://github.com/sphinx-doc/sphinx/issues/10974
     ("py:obj", "ray\\.data\\.datasource\\.datasink\\.WriteReturnType"),

python/ray/_private/worker.py

@@ -30,6 +30,7 @@
     Protocol,
     Sequence,
     Tuple,
+    Type,
     TypeVar,
     Union,
     overload,
@@ -79,6 +80,7 @@
     TaskID,
     raise_sys_exit_with_custom_error_message,
 )
+from ray.actor import ActorClass
 from ray.exceptions import ObjectStoreFullError, RayError, RaySystemError, RayTaskError
 from ray.experimental import tqdm_ray
 from ray.experimental.compiled_dag_ref import CompiledDAGRef
@@ -3332,6 +3334,11 @@ def __call__(self, __t: type) -> Any:
         ...
 
 
+@overload
+def remote(__t: Type[T]) -> ActorClass[T]:
+    ...
+
+
 @overload
 def remote(__function: Callable[[], R]) -> RemoteFunctionNoArgs[R]:
     ...
@@ -3401,13 +3408,6 @@ def remote(
     ...
 
 
-# Pass on typing actors for now. The following makes it so no type errors
-# are generated for actors.
-@overload
-def remote(__t: type) -> Any:
-    ...
-
-
 # Passing options
 @overload
 def remote(

python/ray/actor.py

@@ -1,6 +1,17 @@
 import inspect
 import logging
-from typing import Any, Dict, List, Literal, Optional, Tuple, Union, TYPE_CHECKING
+from typing import (
+    Any,
+    Dict,
+    List,
+    Literal,
+    Optional,
+    Tuple,
+    Union,
+    TYPE_CHECKING,
+    TypeVar,
+    Generic,
+)
 
 import ray._private.ray_constants as ray_constants
 import ray._private.signature as signature
@@ -51,6 +62,12 @@
 # Hook to call with (actor, resources, strategy) on each local actor creation.
 _actor_launch_hook = None
 
+# TypeVar for generic ActorHandle
+T = TypeVar("T")
+
+# return type of ActorClass[T].remote()
+ActorProxy = Union["ActorHandle[T]", type[T]]
+
 
 @PublicAPI
 @client_mode_hook
@@ -761,7 +778,7 @@ def _process_option_dict(actor_options):
 
 
 @PublicAPI
-class ActorClass:
+class ActorClass(Generic[T]):
     """An actor class.
 
     This is a decorated class. It can be used to create actors.
@@ -901,7 +918,7 @@ def _ray_from_function_descriptor(
             self._default_options["runtime_env"] = self.__ray_metadata__.runtime_env
         return self
 
-    def remote(self, *args, **kwargs):
+    def remote(self, *args, **kwargs) -> ActorProxy[T]:
         """Create an actor.
 
         Args:
@@ -1052,7 +1069,7 @@ class or functions.
 
     @wrap_auto_init
     @_tracing_actor_creation
-    def _remote(self, args=None, kwargs=None, **actor_options):
+    def _remote(self, args=None, kwargs=None, **actor_options) -> ActorProxy[T]:
         """Create an actor.
 
         This method allows more flexibility than the remote method because
@@ -1434,7 +1451,7 @@ class or functions.
 
 
 @PublicAPI
-class ActorHandle:
+class ActorHandle(Generic[T]):
     """A handle to an actor.
 
     The fields in this class are prefixed with _ray_ to hide them from the user