3.1.6+: Mypy 1.14.1 incorrectly infers Coroutine return type for @sync_compatible and @async_dispatch decorators

[neurolabs]

Bug summary

Starting from Prefect version 3.1.6, functions decorated with @sync_compatible and @async_dispatch are inferred by mypy as returning Coroutine[Any, Any, R?], despite the expectation that they should be inferred as synchronous as described in the docstring. This behavior was not present in version 3.1.5.

MyPy version: 1.14.1

Reproduction (for prefect 3.1.13):

from prefect import flow
from prefect.blocks.notifications import CustomWebhookNotificationBlock
from prefect.variables import Variable

@flow
def example_flow():
    # Example of a function using @async_dispatch
    value: StrictVariableValue = Variable.get("example_variable")
    
    # Example of a function using @sync_compatible
    webhook_block: CustomWebhookNotificationBlock = CustomWebhookNotificationBlock.load("my_webhook")

Expected Behavior:
Mypy should infer the return type of these functions as synchronous, in line with the Prefect documentation.

Actual Behavior:
Mypy infers the return type as "R | Coroutine[Any, Any, R]".

$ mypy test.py 
test.py:10: error: Incompatible types in assignment (expression has type "str | int | float | dict[str, Any] | list[Any] | Coroutine[Any, Any, str | int | float | dict[str, Any] | list[Any] | None] | None", variable has type "str | int | bool | float | dict[str, Any] | list[Any] | None")  [assignment]
test.py:13: error: Incompatible types in assignment (expression has type "Any | Coroutine[Any, Any, Any]", variable has type "CustomWebhookNotificationBlock")  [assignment]
Found 2 errors in 1 file (checked 1 source file)

Version info

Version:             3.1.13
API version:         0.8.4
Python version:      3.12.8
Git commit:          16e85ce3
Built:               Fri, Jan 17, 2025 8:46 AM
OS/Arch:             linux/x86_64
Profile:             ephemeral
Server type:         server
Pydantic version:    2.10.3
Integrations:
  prefect-gcp:       0.6.2

and also with

Version:             3.1.6
API version:         0.8.4
Python version:      3.12.8
Git commit:          6bfce9e8
Built:               Wed, Dec 11, 2024 10:46 AM
OS/Arch:             linux/x86_64
Profile:             ephemeral
Server type:         server
Pydantic version:    2.10.3
Integrations:
  prefect-gcp:       0.6.2

Additional context

No response

[neurolabs]

related to #16819

[zzstoatzz]

hi @neurolabs - I think this is covered by #15008. As long as you agree, I'll close this issue to keep things tidy

tldr we need to rip out @sync_compatible bc it breaks typing, async_dispatch is a (similarly non-type-safe) bridge to allow us to add explicitly async methods (that are type-safe) for things without introducing breaking changes

[neurolabs]

@zzstoatzz thanks for the pointer to the ongoing efforts in refactoring sync and async compatibility. Do you have any idea how actively this ticket is worked on and how clear of a timeline the ticket has? I know that you probably don't want to commit on or even mention a specific date - please understand that until this has been resolved, our code contains non-typesafe code like casts that are making me uncomfortable. This is why some indication of priority or timeline would be highly appreciated by me (and probably others).

Having this issue closed with a reference and some indication is very fine for me. No indication would not make me happy, but I would be able to handle my negative emotions 😉.

[zzstoatzz]

Do you have any idea how actively this ticket is worked on and how clear of a timeline the ticket has?

the ticket I linked refers to widespread use of those decorators throughout prefect and all the integrations prefect-* in src/integrations, so the timeline is very much related to the domain you're asking about.

You're correct, I don't have an exact timeline but we'd appreciate any help you'd be willing to offer! We'd love to move ourselves off sync_compatible in the next couples months, then after a deprecation window, totally remove async_dispatch