[Core] Document Python type checking best practices

[rkooo567]

Description

Document Python type checking best practices. It is important for mature and stable codebases

cc @jjyao

Link

No response

[abhay-agarwal]

We would love to see some better support for typing, and some help with best practices. Are there resources we can use in the meantime?

For us, here's the state of Ray typing as of 2.3.0

1. Ray Tasks have the highest support. They support non-named, non-default parameter types.

@ray.remote
def typed_function1(p1: int, p2: str) -> dict[str | int, Any]:
    return {p1: "hello", p2: "world"}
typed_function1.remote(1,"love") # this works

# this doesn't work, default parameters unsupported
@ray.remote
def typed_function2(p1: int, p2: str = "hello") -> dict[str | int, Any]:
    return {p1: "hello", p2: "world"}
typed_function2.remote(1,"love") # this doesn't work, default parameters unsupported

@ray.remote
def typed_function3(p1: int, p2: str) -> dict[str | int, Any]:
    return {p1: "hello", p2: "world"}

typed_function3.remote(1,p2="love") # this doesn't work, named parameters not supported

2. Using other ray methods like .options() before remote breaks the remote typing.

@ray.remote
def typed_function1(p1: int, p2: str) -> dict[str | int, Any]:
    return {p1: "hello", p2: "world"}
typed_function1.options(...).remote(1,"love") # this doesn't work

4. Ray actors and Ray serve deployments seem completely unsupported

We'd love to see more first class support for Ray types. For a tool that prides itself on a great developer experience, I think type support would contribute significantly to usability and maintainability. We make extensive use of pyright linting errors to help with code refactors, etc.

[edmondop]

Has this been prioritized ?

   └╴󰌠  actors.py  2 
     ├╴E Cannot access attribute "incr" for class "ObjectRef[Counter]"
     │     Attribute "incr" is unknown Pyright (reportAttributeAccessIssue) [28, 11]
     └╴E Cannot access attribute "get" for class "ObjectRef[Counter]"
           Attribute "get" is unknown Pyright (reportAttributeAccessIssue) [31, 21]

[baughmann]

I know it may seem superficial, but when I created my first actor and saw that ignoring the Cannot access attribute "my_method" for class "ObjectRef[MyActor]" is the only way to use Ray, I couldn't believe it.

It is difficult to recommend adoption when ignoring type hint errors is the only approach to take.

Maybe I just haven't seen what the right answer is yet, though.

[observerw]

I know it may seem superficial, but when I created my first actor and saw that ignoring the Cannot access attribute "my_method" for class "ObjectRef[MyActor]" is the only way to use Ray, I couldn't believe it.

It is difficult to recommend adoption when ignoring type hint errors is the only approach to take.

Maybe I just haven't seen what the right answer is yet, though.

I made the same point in #50410 (comment) 🫤

[zen-xu]

@abhay-agarwal What you need is sunray

[richardliaw]

@SolitaryThinker could you share a bit on what you've been doing here?

[pcmoritz]

The issues @SolitaryThinker is working on are collected in #54149

Most of it is already shipped in 2.48 and significantly improves the actor typing. Not sure if the issue around .options in #28055 (comment) is solved if not let's add it @SolitaryThinker !

Also documentation is being worked on in #55013

[richardliaw]

@abhay-agarwal - I believe #53986 and #55563 should address most of these issues.

The main thing left is Serve Deployments, which we will take a closer look (as part of #54149)