Fix misleading pyright error when calling async task with wrong argument types

[zzstoatzz]

closes #19326

Summary

Fixes a confusing pyright error message when calling async tasks with incorrect argument types.

Before: Calling an async task with wrong arg types showed:

"State[CoroutineType[Any, Any, None]]" is not awaitable

After: Shows normal argument type error (or no error if types are correct)

Root Cause

When pyright couldn't match task arguments to the specific overload (e.g., passing None instead of str), it fell back to the *args: Unknown overloads. The return_state=True overload was listed first, so pyright picked it and inferred State[Coroutine[...]] instead of Coroutine[...].

Changes

1. Added explicit Task[P, Coroutine[Any, Any, R]] overloads to Task.__call__ (similar to what submit() and map() already have)
2. Reordered overloads so return_state=False comes before return_state=True - ensures pyright picks the correct default behavior when it can't match argument types

Testing

• Reproduced the original issue
• Verified the fix resolves it
• All existing tests pass (tests/test_tasks.py::TestTaskCall)

Reproduction

from prefect import task

@task
async def f(s: str) -> None:
    print(s)

async def test_wrong_arg_type():
    await f(None)  # Before: "State[Coroutine...] is not awaitable"
                    # After: Normal type error or no confusing error

🤖 Generated with Claude Code

[codspeed-hq]

CodSpeed Performance Report

Merging #19327 will not alter performance

_{Comparing fix-task-call-overload-ordering (50d1603) with main (7d86c93)}

Summary

✅ 2 untouched

[zzstoatzz]

https://bsky.app/profile/zzstoatzzdevlog.bsky.social/post/3m4qmrh7gjb2t