[core] Add static type hints for Actor methods #54173

SolitaryThinker · 2025-06-27T10:47:15Z

Why are these changes needed?

Related Issue: #54149

Also allow for actors methods to be decorated with @ray.method (with no args)

After this PR

cc @pcmoritz @richardliaw

Related issue number

Checks

I've signed off every commit(by using the -s flag, i.e., git commit -s) in this PR.
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 :(

Copilot

Pull Request Overview

Enhance the @ray.method decorator with static type hints for actor methods and allow using it without parentheses.

Added RemoteMethod0–9 generics and RemoteMethodNoArgs for precise .remote()/.bind() typing.
Imported ParamSpec, Concatenate, and overload to support decorator overloads.
Updated @ray.method to handle no-argument usage (@ray.method) and refined validation logic.

Comments suppressed due to low confidence (2)

python/ray/actor.py:473

Consider adding unit tests to verify the new no-parentheses usage of @ray.method (@ray.method) so this branch is covered and validated.

    if len(args) == 1 and callable(args[0]) and len(kwargs) == 0:

python/ray/actor.py:478

[nitpick] The error message is a bit awkward; consider rephrasing to clearly separate the two valid usages, for example: "The @ray.method decorator must be applied as @ray.method or with one or more of the valid keyword args: ...".

    error_string = (

Copilot · 2025-06-27T10:48:19Z

python/ray/actor.py

+_T9 = TypeVar("_T9")
+
+
+class RemoteMethodNoArgs(Generic[_Ret]):


[nitpick] The series of repetitive RemoteMethod0 through RemoteMethod9 classes could be consolidated using Python 3.11’s variadic generics (PEP 646) or a helper factory to reduce duplication and improve maintainability.

pcmoritz · 2025-07-01T19:33:33Z

python/ray/actor.py

 )
+from typing_extensions import ParamSpec


Ray Core needs to work without typing_extensions. I realize these have only been added in Python 3.10, so how about we first try to import ParamSpec and Concatenate from typing, and if that doesn't succeed, import them from typing_extensions? It means this won't work for Python 3.9 unless people have typing_extensions installed but I feel like that's an acceptable tradeoff :)

(the Python 3.13 unit test is actually failing at the moment because of this)

fixed in fbfc893

pcmoritz · 2025-07-01T20:33:56Z

python/ray/actor.py

+    retry_exceptions: Optional[Union[bool, list, tuple]] = None,
+    _generator_backpressure_num_objects: Optional[int] = None,
+    enable_task_events: Optional[bool] = None,
+    tensor_transport: Optional[str] = None,


Can we make this Optional[TensorTransportEnum] instead?

fixed in becd6de

pcmoritz · 2025-07-01T20:43:00Z

One thing I noticed is that the actor constructor currently doesn't autocomplete, e.g.

import ray

@ray.remote
class Actor:
    def __init__(self, a: str):
        pass

    @ray.method
    def f(self, b: int) -> int:
        return b
    
Actor.remote(<CURSOR>)

It looks like this:

Can you have a look at the in a follow up PR? It should show the arguments of the constructor :)

pcmoritz

Thanks for adding this, it looks great to me! Left some smaller comments.

Signed-off-by: will.lin <will.lin@anyscale.com>

SolitaryThinker · 2025-07-01T21:09:15Z

Thanks! I will add the actor constructor to the list of issues to fix

@pcmoritz

## Why are these changes needed? Related Issue: #54149 Also allow for actors methods to be decorated with `@ray.method` (with no args) **After this PR** ![image](https://github.com/user-attachments/assets/822b91fa-30af-41c0-be85-d680f02ad6b4) cc @pcmoritz @richardliaw  ## Related issue number  ## Checks - [ ] I've signed off every commit(by using the -s flag, i.e., `git commit -s`) in this PR. - [ ] 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: elliot-barn <elliot.barnwell@anyscale.com>

@pcmoritz

## Why are these changes needed? Related Issue: #54149 Also allow for actors methods to be decorated with `@ray.method` (with no args) **After this PR** ![image](https://github.com/user-attachments/assets/822b91fa-30af-41c0-be85-d680f02ad6b4) cc @pcmoritz @richardliaw  ## Related issue number  ## Checks - [ ] I've signed off every commit(by using the -s flag, i.e., `git commit -s`) in this PR. - [ ] 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: elliot-barn <elliot.barnwell@anyscale.com>

Copilot AI review requested due to automatic review settings June 27, 2025 10:47

SolitaryThinker mentioned this pull request Jun 27, 2025

[core] Improving Ray Typing annotation #54149

Closed

8 tasks

Copilot AI reviewed Jun 27, 2025

View reviewed changes

SolitaryThinker force-pushed the will/remote_methods branch 3 times, most recently from 8d34d4e to 9bc77dd Compare June 30, 2025 22:57

richardliaw added the go add ONLY when ready to merge, run all tests label Jul 1, 2025

pcmoritz reviewed Jul 1, 2025

View reviewed changes

pcmoritz approved these changes Jul 1, 2025

View reviewed changes

SolitaryThinker added 5 commits July 1, 2025 21:06

fix types

8e1ad88

Signed-off-by: will.lin <will.lin@anyscale.com>

union

1dc7396

Signed-off-by: will.lin <will.lin@anyscale.com>

fix api lint

0c34dd0

Signed-off-by: will.lin <will.lin@anyscale.com>

try to import from typing

fbfc893

Signed-off-by: will.lin <will.lin@anyscale.com>

address comments

becd6de

Signed-off-by: will.lin <will.lin@anyscale.com>

SolitaryThinker force-pushed the will/remote_methods branch from 9bc77dd to becd6de Compare July 1, 2025 21:08

pcmoritz merged commit 5bcb4a1 into ray-project:master Jul 1, 2025
5 checks passed

SolitaryThinker deleted the will/remote_methods branch July 2, 2025 02:51

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[core] Add static type hints for Actor methods #54173

[core] Add static type hints for Actor methods #54173

SolitaryThinker commented Jun 27, 2025

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Jun 27, 2025

Uh oh!

pcmoritz Jul 1, 2025

Uh oh!

SolitaryThinker Jul 1, 2025

Uh oh!

pcmoritz Jul 1, 2025

Uh oh!

SolitaryThinker Jul 1, 2025

Uh oh!

pcmoritz commented Jul 1, 2025

Uh oh!

pcmoritz left a comment

Uh oh!

SolitaryThinker commented Jul 1, 2025

Uh oh!

Uh oh!

Uh oh!

		_T9 = TypeVar("_T9")


		class RemoteMethodNoArgs(Generic[_Ret]):

[core] Add static type hints for Actor methods #54173

[core] Add static type hints for Actor methods #54173

Conversation

SolitaryThinker commented Jun 27, 2025

Why are these changes needed?

Related issue number

Checks

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Copilot AI Jun 27, 2025

Choose a reason for hiding this comment

Uh oh!

pcmoritz Jul 1, 2025

Choose a reason for hiding this comment

Uh oh!

SolitaryThinker Jul 1, 2025

Choose a reason for hiding this comment

Uh oh!

pcmoritz Jul 1, 2025

Choose a reason for hiding this comment

Uh oh!

SolitaryThinker Jul 1, 2025

Choose a reason for hiding this comment

Uh oh!

pcmoritz commented Jul 1, 2025

Uh oh!

pcmoritz left a comment

Choose a reason for hiding this comment

Uh oh!

SolitaryThinker commented Jul 1, 2025

Uh oh!

Uh oh!

Uh oh!