Fix @datastar_response typing for Django async views by MarcusL11 · Pull Request #42 · starfederation/datastar-python

MarcusL11 · 2026-05-03T06:55:45Z

Summary

Add @overload signatures to the Django datastar_response decorator so mypy can narrow the return type based on sync vs async input
Use Coroutine[Any, Any, ...] instead of Awaitable[...] for the async overload, matching what django-stubs path() expects

Problem

The decorator currently has a single signature that returns a union type:

Callable[P, Awaitable[DatastarResponse] |DatastarResponse]

Mypy can't narrow this, so passing a decorated view to path() fails:

error: Argument 2 to "path" has incompatible type
"Callable[[HttpRequest], Awaitable[DatastarResponse] | DatastarResponse]";
expected "Callable[..., HttpResponseBase]"

This forces users to wrap every decorated view in cast():

path("my-view/", cast(ViewCallable, my_view))

Why `Coroutine` and not `Awaitable`

django-stubs accepts async views as Callable[..., Coroutine[Any, Any, HttpResponseBase]]. Since Coroutine is a subtype of Awaitable, using the broader Awaitable doesn't satisfy the narrower Coroutine expectation.

Test plan

mypy passes for all 4 decorator variants (async/sync × value/generator) in path()
Existing test_decorator_matrix.py Django tests pass (4/4)

gazpachoking · 2026-05-03T16:57:36Z


+@overload
+def datastar_response(
+ func: Callable[P, Coroutine[Any, Any, DatastarEvents]],


Is the Coroutine here correct? Doesn't that eliminate async generators, which should be valid?
@datastar_responseasyncdefasync_gen(): yieldSSE.patch_elements('<div id="aoeu"></div>')

@overload

…wing The decorator's single union return type prevents mypy from narrowing sync vs async views, forcing users to cast() when passing to path(). Add @overload signatures using Coroutine (not Awaitable) to match what django-stubs expects for async view callables.

The async overload used Coroutine, which excluded async generator views (async def + yield). Those matched the sync DatastarEvents overload and were mistyped as returning a plain DatastarResponse instead of a coroutine. Add a dedicated overload for Callable[P, AsyncIterable[DatastarEvent]] -> Callable[P, Coroutine[Any, Any, DatastarResponse]], placed before the sync overload so async generators resolve correctly. Verified with mypy (django-stubs) via assert_type and the existing decorator matrix tests (all 4 sync/async x value/generator variants pass).

MarcusL11 · 2026-05-03T06:55:45Z

Summary

Add @overload signatures to the Django datastar_response decorator so mypy can narrow the return type based on sync vs async input
Use Coroutine[Any, Any, ...] instead of Awaitable[...] for the async overload, matching what django-stubs path() expects

Problem

The decorator currently has a single signature that returns a union type:

Callable[P, Awaitable[DatastarResponse] |DatastarResponse]

Mypy can't narrow this, so passing a decorated view to path() fails:

error: Argument 2 to "path" has incompatible type
"Callable[[HttpRequest], Awaitable[DatastarResponse] | DatastarResponse]";
expected "Callable[..., HttpResponseBase]"

This forces users to wrap every decorated view in cast():

path("my-view/", cast(ViewCallable, my_view))

Why `Coroutine` and not `Awaitable`

django-stubs accepts async views as Callable[..., Coroutine[Any, Any, HttpResponseBase]]. Since Coroutine is a subtype of Awaitable, using the broader Awaitable doesn't satisfy the narrower Coroutine expectation.

Test plan

mypy passes for all 4 decorator variants (async/sync × value/generator) in path()
Existing test_decorator_matrix.py Django tests pass (4/4)

gazpachoking · 2026-05-03T16:57:36Z


+@overload
+def datastar_response(
+ func: Callable[P, Coroutine[Any, Any, DatastarEvents]],


Is the Coroutine here correct? Doesn't that eliminate async generators, which should be valid?
@datastar_responseasyncdefasync_gen(): yieldSSE.patch_elements('<div id="aoeu"></div>')

@overload

…wing The decorator's single union return type prevents mypy from narrowing sync vs async views, forcing users to cast() when passing to path(). Add @overload signatures using Coroutine (not Awaitable) to match what django-stubs expects for async view callables.

The async overload used Coroutine, which excluded async generator views (async def + yield). Those matched the sync DatastarEvents overload and were mistyped as returning a plain DatastarResponse instead of a coroutine. Add a dedicated overload for Callable[P, AsyncIterable[DatastarEvent]] -> Callable[P, Coroutine[Any, Any, DatastarResponse]], placed before the sync overload so async generators resolve correctly. Verified with mypy (django-stubs) via assert_type and the existing decorator matrix tests (all 4 sync/async x value/generator variants pass).

MarcusL11 · 2026-05-03T06:55:45Z

Summary

Add @overload signatures to the Django datastar_response decorator so mypy can narrow the return type based on sync vs async input
Use Coroutine[Any, Any, ...] instead of Awaitable[...] for the async overload, matching what django-stubs path() expects

Problem

The decorator currently has a single signature that returns a union type:

Callable[P, Awaitable[DatastarResponse] |DatastarResponse]

Mypy can't narrow this, so passing a decorated view to path() fails:

error: Argument 2 to "path" has incompatible type
"Callable[[HttpRequest], Awaitable[DatastarResponse] | DatastarResponse]";
expected "Callable[..., HttpResponseBase]"

This forces users to wrap every decorated view in cast():

path("my-view/", cast(ViewCallable, my_view))

Why `Coroutine` and not `Awaitable`

django-stubs accepts async views as Callable[..., Coroutine[Any, Any, HttpResponseBase]]. Since Coroutine is a subtype of Awaitable, using the broader Awaitable doesn't satisfy the narrower Coroutine expectation.

Test plan

mypy passes for all 4 decorator variants (async/sync × value/generator) in path()
Existing test_decorator_matrix.py Django tests pass (4/4)

gazpachoking · 2026-05-03T16:57:36Z


+@overload
+def datastar_response(
+ func: Callable[P, Coroutine[Any, Any, DatastarEvents]],


Is the Coroutine here correct? Doesn't that eliminate async generators, which should be valid?
@datastar_responseasyncdefasync_gen(): yieldSSE.patch_elements('<div id="aoeu"></div>')

@overload

…wing The decorator's single union return type prevents mypy from narrowing sync vs async views, forcing users to cast() when passing to path(). Add @overload signatures using Coroutine (not Awaitable) to match what django-stubs expects for async view callables.

The async overload used Coroutine, which excluded async generator views (async def + yield). Those matched the sync DatastarEvents overload and were mistyped as returning a plain DatastarResponse instead of a coroutine. Add a dedicated overload for Callable[P, AsyncIterable[DatastarEvent]] -> Callable[P, Coroutine[Any, Any, DatastarResponse]], placed before the sync overload so async generators resolve correctly. Verified with mypy (django-stubs) via assert_type and the existing decorator matrix tests (all 4 sync/async x value/generator variants pass).

MarcusL11 · 2026-05-03T06:55:45Z

Summary

Add @overload signatures to the Django datastar_response decorator so mypy can narrow the return type based on sync vs async input
Use Coroutine[Any, Any, ...] instead of Awaitable[...] for the async overload, matching what django-stubs path() expects

Problem

The decorator currently has a single signature that returns a union type:

Callable[P, Awaitable[DatastarResponse] |DatastarResponse]

Mypy can't narrow this, so passing a decorated view to path() fails:

error: Argument 2 to "path" has incompatible type
"Callable[[HttpRequest], Awaitable[DatastarResponse] | DatastarResponse]";
expected "Callable[..., HttpResponseBase]"

This forces users to wrap every decorated view in cast():

path("my-view/", cast(ViewCallable, my_view))

Why `Coroutine` and not `Awaitable`

django-stubs accepts async views as Callable[..., Coroutine[Any, Any, HttpResponseBase]]. Since Coroutine is a subtype of Awaitable, using the broader Awaitable doesn't satisfy the narrower Coroutine expectation.

Test plan

mypy passes for all 4 decorator variants (async/sync × value/generator) in path()
Existing test_decorator_matrix.py Django tests pass (4/4)

gazpachoking · 2026-05-03T16:57:36Z


+@overload
+def datastar_response(
+ func: Callable[P, Coroutine[Any, Any, DatastarEvents]],


Is the Coroutine here correct? Doesn't that eliminate async generators, which should be valid?
@datastar_responseasyncdefasync_gen(): yieldSSE.patch_elements('<div id="aoeu"></div>')

@overload

…wing The decorator's single union return type prevents mypy from narrowing sync vs async views, forcing users to cast() when passing to path(). Add @overload signatures using Coroutine (not Awaitable) to match what django-stubs expects for async view callables.

The async overload used Coroutine, which excluded async generator views (async def + yield). Those matched the sync DatastarEvents overload and were mistyped as returning a plain DatastarResponse instead of a coroutine. Add a dedicated overload for Callable[P, AsyncIterable[DatastarEvent]] -> Callable[P, Coroutine[Any, Any, DatastarResponse]], placed before the sync overload so async generators resolve correctly. Verified with mypy (django-stubs) via assert_type and the existing decorator matrix tests (all 4 sync/async x value/generator variants pass).

MarcusL11 · 2026-05-03T06:55:45Z

Summary

Add @overload signatures to the Django datastar_response decorator so mypy can narrow the return type based on sync vs async input
Use Coroutine[Any, Any, ...] instead of Awaitable[...] for the async overload, matching what django-stubs path() expects

Problem

The decorator currently has a single signature that returns a union type:

Callable[P, Awaitable[DatastarResponse] |DatastarResponse]

Mypy can't narrow this, so passing a decorated view to path() fails:

error: Argument 2 to "path" has incompatible type
"Callable[[HttpRequest], Awaitable[DatastarResponse] | DatastarResponse]";
expected "Callable[..., HttpResponseBase]"

This forces users to wrap every decorated view in cast():

path("my-view/", cast(ViewCallable, my_view))

Why `Coroutine` and not `Awaitable`

django-stubs accepts async views as Callable[..., Coroutine[Any, Any, HttpResponseBase]]. Since Coroutine is a subtype of Awaitable, using the broader Awaitable doesn't satisfy the narrower Coroutine expectation.

Test plan

mypy passes for all 4 decorator variants (async/sync × value/generator) in path()
Existing test_decorator_matrix.py Django tests pass (4/4)

gazpachoking · 2026-05-03T16:57:36Z


+@overload
+def datastar_response(
+ func: Callable[P, Coroutine[Any, Any, DatastarEvents]],


Is the Coroutine here correct? Doesn't that eliminate async generators, which should be valid?
@datastar_responseasyncdefasync_gen(): yieldSSE.patch_elements('<div id="aoeu"></div>')

@overload

…wing The decorator's single union return type prevents mypy from narrowing sync vs async views, forcing users to cast() when passing to path(). Add @overload signatures using Coroutine (not Awaitable) to match what django-stubs expects for async view callables.

The async overload used Coroutine, which excluded async generator views (async def + yield). Those matched the sync DatastarEvents overload and were mistyped as returning a plain DatastarResponse instead of a coroutine. Add a dedicated overload for Callable[P, AsyncIterable[DatastarEvent]] -> Callable[P, Coroutine[Any, Any, DatastarResponse]], placed before the sync overload so async generators resolve correctly. Verified with mypy (django-stubs) via assert_type and the existing decorator matrix tests (all 4 sync/async x value/generator variants pass).

MarcusL11 · 2026-05-03T06:55:45Z

Summary

Add @overload signatures to the Django datastar_response decorator so mypy can narrow the return type based on sync vs async input
Use Coroutine[Any, Any, ...] instead of Awaitable[...] for the async overload, matching what django-stubs path() expects

Problem

The decorator currently has a single signature that returns a union type:

Callable[P, Awaitable[DatastarResponse] |DatastarResponse]

Mypy can't narrow this, so passing a decorated view to path() fails:

error: Argument 2 to "path" has incompatible type
"Callable[[HttpRequest], Awaitable[DatastarResponse] | DatastarResponse]";
expected "Callable[..., HttpResponseBase]"

This forces users to wrap every decorated view in cast():

path("my-view/", cast(ViewCallable, my_view))

Why `Coroutine` and not `Awaitable`

django-stubs accepts async views as Callable[..., Coroutine[Any, Any, HttpResponseBase]]. Since Coroutine is a subtype of Awaitable, using the broader Awaitable doesn't satisfy the narrower Coroutine expectation.

Test plan

mypy passes for all 4 decorator variants (async/sync × value/generator) in path()
Existing test_decorator_matrix.py Django tests pass (4/4)

gazpachoking · 2026-05-03T16:57:36Z


+@overload
+def datastar_response(
+ func: Callable[P, Coroutine[Any, Any, DatastarEvents]],


Is the Coroutine here correct? Doesn't that eliminate async generators, which should be valid?
@datastar_responseasyncdefasync_gen(): yieldSSE.patch_elements('<div id="aoeu"></div>')

@overload

…wing The decorator's single union return type prevents mypy from narrowing sync vs async views, forcing users to cast() when passing to path(). Add @overload signatures using Coroutine (not Awaitable) to match what django-stubs expects for async view callables.

The async overload used Coroutine, which excluded async generator views (async def + yield). Those matched the sync DatastarEvents overload and were mistyped as returning a plain DatastarResponse instead of a coroutine. Add a dedicated overload for Callable[P, AsyncIterable[DatastarEvent]] -> Callable[P, Coroutine[Any, Any, DatastarResponse]], placed before the sync overload so async generators resolve correctly. Verified with mypy (django-stubs) via assert_type and the existing decorator matrix tests (all 4 sync/async x value/generator variants pass).

MarcusL11 · 2026-05-03T06:55:45Z

Summary

Add @overload signatures to the Django datastar_response decorator so mypy can narrow the return type based on sync vs async input
Use Coroutine[Any, Any, ...] instead of Awaitable[...] for the async overload, matching what django-stubs path() expects

Problem

The decorator currently has a single signature that returns a union type:

Callable[P, Awaitable[DatastarResponse] |DatastarResponse]

Mypy can't narrow this, so passing a decorated view to path() fails:

error: Argument 2 to "path" has incompatible type
"Callable[[HttpRequest], Awaitable[DatastarResponse] | DatastarResponse]";
expected "Callable[..., HttpResponseBase]"

This forces users to wrap every decorated view in cast():

path("my-view/", cast(ViewCallable, my_view))

Why `Coroutine` and not `Awaitable`

django-stubs accepts async views as Callable[..., Coroutine[Any, Any, HttpResponseBase]]. Since Coroutine is a subtype of Awaitable, using the broader Awaitable doesn't satisfy the narrower Coroutine expectation.

Test plan

mypy passes for all 4 decorator variants (async/sync × value/generator) in path()
Existing test_decorator_matrix.py Django tests pass (4/4)

gazpachoking · 2026-05-03T16:57:36Z


+@overload
+def datastar_response(
+ func: Callable[P, Coroutine[Any, Any, DatastarEvents]],


Is the Coroutine here correct? Doesn't that eliminate async generators, which should be valid?
@datastar_responseasyncdefasync_gen(): yieldSSE.patch_elements('<div id="aoeu"></div>')

@overload

…wing The decorator's single union return type prevents mypy from narrowing sync vs async views, forcing users to cast() when passing to path(). Add @overload signatures using Coroutine (not Awaitable) to match what django-stubs expects for async view callables.

The async overload used Coroutine, which excluded async generator views (async def + yield). Those matched the sync DatastarEvents overload and were mistyped as returning a plain DatastarResponse instead of a coroutine. Add a dedicated overload for Callable[P, AsyncIterable[DatastarEvent]] -> Callable[P, Coroutine[Any, Any, DatastarResponse]], placed before the sync overload so async generators resolve correctly. Verified with mypy (django-stubs) via assert_type and the existing decorator matrix tests (all 4 sync/async x value/generator variants pass).

MarcusL11 · 2026-05-03T06:55:45Z

Summary

Add @overload signatures to the Django datastar_response decorator so mypy can narrow the return type based on sync vs async input
Use Coroutine[Any, Any, ...] instead of Awaitable[...] for the async overload, matching what django-stubs path() expects

Problem

The decorator currently has a single signature that returns a union type:

Callable[P, Awaitable[DatastarResponse] |DatastarResponse]

Mypy can't narrow this, so passing a decorated view to path() fails:

error: Argument 2 to "path" has incompatible type
"Callable[[HttpRequest], Awaitable[DatastarResponse] | DatastarResponse]";
expected "Callable[..., HttpResponseBase]"

This forces users to wrap every decorated view in cast():

path("my-view/", cast(ViewCallable, my_view))

Why `Coroutine` and not `Awaitable`

django-stubs accepts async views as Callable[..., Coroutine[Any, Any, HttpResponseBase]]. Since Coroutine is a subtype of Awaitable, using the broader Awaitable doesn't satisfy the narrower Coroutine expectation.

Test plan

mypy passes for all 4 decorator variants (async/sync × value/generator) in path()
Existing test_decorator_matrix.py Django tests pass (4/4)

gazpachoking · 2026-05-03T16:57:36Z


+@overload
+def datastar_response(
+ func: Callable[P, Coroutine[Any, Any, DatastarEvents]],


Is the Coroutine here correct? Doesn't that eliminate async generators, which should be valid?
@datastar_responseasyncdefasync_gen(): yieldSSE.patch_elements('<div id="aoeu"></div>')

@overload

…wing The decorator's single union return type prevents mypy from narrowing sync vs async views, forcing users to cast() when passing to path(). Add @overload signatures using Coroutine (not Awaitable) to match what django-stubs expects for async view callables.

The async overload used Coroutine, which excluded async generator views (async def + yield). Those matched the sync DatastarEvents overload and were mistyped as returning a plain DatastarResponse instead of a coroutine. Add a dedicated overload for Callable[P, AsyncIterable[DatastarEvent]] -> Callable[P, Coroutine[Any, Any, DatastarResponse]], placed before the sync overload so async generators resolve correctly. Verified with mypy (django-stubs) via assert_type and the existing decorator matrix tests (all 4 sync/async x value/generator variants pass).

gazpachoking reviewed May 3, 2026
View reviewed changes

MarcusL11and others added 3 commits July 24, 2026 04:08

fix: split datastar event aliases for django typing
fea020e

MarcusL11 force-pushed the fix/django-decorator-overload-typing branch from 1f1768e to fea020eCompare July 24, 2026 11:13

gazpachoking reviewed May 3, 2026
View reviewed changes

MarcusL11and others added 3 commits July 24, 2026 04:08

fix: split datastar event aliases for django typing
fea020e

MarcusL11 force-pushed the fix/django-decorator-overload-typing branch from 1f1768e to fea020eCompare July 24, 2026 11:13

gazpachoking reviewed May 3, 2026
View reviewed changes

MarcusL11and others added 3 commits July 24, 2026 04:08

fix: split datastar event aliases for django typing
fea020e

MarcusL11 force-pushed the fix/django-decorator-overload-typing branch from 1f1768e to fea020eCompare July 24, 2026 11:13

gazpachoking reviewed May 3, 2026
View reviewed changes

MarcusL11and others added 3 commits July 24, 2026 04:08

fix: split datastar event aliases for django typing
fea020e

MarcusL11 force-pushed the fix/django-decorator-overload-typing branch from 1f1768e to fea020eCompare July 24, 2026 11:13

gazpachoking reviewed May 3, 2026
View reviewed changes

MarcusL11and others added 3 commits July 24, 2026 04:08

fix: split datastar event aliases for django typing
fea020e

MarcusL11 force-pushed the fix/django-decorator-overload-typing branch from 1f1768e to fea020eCompare July 24, 2026 11:13

gazpachoking reviewed May 3, 2026
View reviewed changes

MarcusL11and others added 3 commits July 24, 2026 04:08

fix: split datastar event aliases for django typing
fea020e

MarcusL11 force-pushed the fix/django-decorator-overload-typing branch from 1f1768e to fea020eCompare July 24, 2026 11:13

gazpachoking reviewed May 3, 2026
View reviewed changes

MarcusL11and others added 3 commits July 24, 2026 04:08

fix: split datastar event aliases for django typing
fea020e

MarcusL11 force-pushed the fix/django-decorator-overload-typing branch from 1f1768e to fea020eCompare July 24, 2026 11:13

gazpachoking reviewed May 3, 2026
View reviewed changes

MarcusL11and others added 3 commits July 24, 2026 04:08

fix: split datastar event aliases for django typing
fea020e

MarcusL11 force-pushed the fix/django-decorator-overload-typing branch from 1f1768e to fea020eCompare July 24, 2026 11:13

Uh oh!

Conversation

MarcusL11 commented May 3, 2026

Summary

Problem

Why Coroutine and not Awaitable

Test plan

Uh oh!

gazpachokingMay 3, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

MarcusL11 commented May 3, 2026

Summary

Problem

Why Coroutine and not Awaitable

Test plan

Uh oh!

gazpachokingMay 3, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

MarcusL11 commented May 3, 2026

Summary

Problem

Why Coroutine and not Awaitable

Test plan

Uh oh!

gazpachokingMay 3, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

MarcusL11 commented May 3, 2026

Summary

Problem

Why Coroutine and not Awaitable

Test plan

Uh oh!

gazpachokingMay 3, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

MarcusL11 commented May 3, 2026

Summary

Why `Coroutine` and not `Awaitable`

Why `Coroutine` and not `Awaitable`

Why `Coroutine` and not `Awaitable`

Why `Coroutine` and not `Awaitable`

Why `Coroutine` and not `Awaitable`

Why `Coroutine` and not `Awaitable`