Django channels stubs #13939

huynguyengl99 · 2025-05-04T13:59:44Z

Ref:

Stubs package for Django Channels #14020

huynguyengl99 · 2025-05-04T18:14:52Z

Hi @sobolevn,
I’ve created stubs to add type hint support for django-channels. Sorry for the tag, but if you have some time, could you please take a look and share any feedback or suggestions? I’d really appreciate your input!

sobolevn

I have some concerns about adding django-channels to typeshed. I would like to discuss them in detail here:

Since django-stubs does not support pyright and other type checkers - what will be the result of adding these types here, where pyright and pytype are also included in the CI?
What about different django versions? Does django-channels have any difference between them? We (django-stubs) only support the latest django version
Does django-channels need any extra features? Would it benefit from a custom mypy plugin?

Tatsh · 2025-05-04T20:21:03Z

There is a very good example of usage of Channels here.

I have some concerns about adding django-channels to typeshed. I would like to discuss them in detail here:

Since django-stubs does not support pyright and other type checkers - what will be the result of adding these types here, where pyright and pytype are also included in the CI?

From the way I've been using Channels, it will not pull in anything that will not work properly with Pyright such as an app's models.

What about different django versions? Does django-channels have any difference between them? We (django-stubs) only support the latest django version

They only check for Django>=4.2.

Does django-channels need any extra features? Would it benefit from a custom mypy plugin?

I do not believe so.

It is a somewhat active project so I think the typing should go in the project itself rather than here.

sobolevn

(not a full review)

stubs/channels/METADATA.toml

stubs/channels/channels/testing/http.pyi

stubs/channels/channels/testing/live.pyi

huynguyengl99 · 2025-05-05T04:59:30Z

@sobolevn

Since django-stubs does not support pyright and other type checkers — what will be the result of adding these types here, where pyright and pytype are also included in the CI?

I agree with @Tatsh, and I am creating an extension package for Channels. It looks like django-stubs partially supports Pyright, rather than having no support at all. So for the Channels stubs themselves, it should work fine because they don’t currently require the mypy plugin — meaning the other type checkers should handle it well.

What about different Django versions? Does django-channels have any differences between them? We (django-stubs) only support the latest Django version.

As I mentioned in your code feedback, I think there’s no significant difference between versions because Channels only relies on some stable Django imports. I will check and aim to support at least Django 4.2 if possible. For that, I think requiring django-stubs >=4.2 would be the best for compatibility. Is it right or should I just use the latest 5.2 for django stubs?

Does django-channels need any extra features? Would it benefit from a custom mypy plugin?

I think not. However, one useful addition to the main django-channels package could be something like ChannelScope, which defines additional keys that can be accessed. This way, if users want to extend the scope, they can extend that type and annotate it in their code.

@Tatsh, I used to think about adding type annotations directly to Channels instead of creating a stubs package, but there’s a comment from carltongibson mentioning that type hints have been rejected in Django. So, Channels will likely follow that approach — that’s the main reason for creating the stubs.

sobolevn

(not a full review)

sobolevn · 2025-05-05T10:51:44Z

stubs/channels/channels/consumer.pyi

+def get_handler_name(message: dict[str, Any]) -> str: ...
+@type_check_only


Suggested change

def get_handler_name(message: dict[str, Any]) -> str: ...

@type_check_only

def get_handler_name(message: dict[str, Any]) -> str: ...

@type_check_only

strange that ruff does not catch this.

If you're referring to the spacing between get_handler_name and @type_check_only, that has been formatted by black. Black removed the extra space between them (even though I agree with you that an extra space would be appropriate)

sobolevn · 2025-05-12T06:47:32Z

stubs/channels/channels/auth.pyi

+from .utils import _ChannelApplication
+
+@database_sync_to_async
+def get_user(scope: _ChannelScope) -> AbstractBaseUser | AnonymousUser: ...


Can we just turn this into async def? Or will it trigger an error?

It will work for the auth.pyi. However, there is one thing I have encountered in another file: stubs/channels/channels/consumer.pyi. If I migrate the dispatch function from being annotated by database_sync_to_async to async def, I face this error in the stub test:

error: channels.consumer.SyncConsumer.dispatch is not a function Stub: in file typeshed/stubs/channels/channels/consumer.pyi:55 def (self: channels.consumer.SyncConsumer, message: builtins.dict[builtins.str, Any]) -> typing.Coroutine[Any, Any, None] Runtime: at line 118 async def (self, message)

If I use database_sync_to_async here, it's ok. I don't know why there is this difference, so I chose to use database_sync_to_async. But I'm willing to migrate to async def and put dispatch in allow_list.txt if you think async def is better.

I have migrated all functions in auth.pyi to use async def but kept dispatch in consumer.pyi using database_sync_to_async. Please let me know if this approach is correct, thank you.

sobolevn · 2025-05-12T06:48:01Z

stubs/channels/channels/auth.pyi

+def login(scope: _ChannelScope, user: AbstractBaseUser, backend: BaseBackend | None = ...) -> None: ...
+@database_sync_to_async
+def logout(scope: _ChannelScope) -> None: ...
+def _get_user_session_key(session: _LazySession) -> Any: ...


Why do we need this protected member? please, add a comment. We generally don't included protected names, until they are special / required.

Got it, wasn't aware of that convention. I'll remove the protected functions that are purely internal. Thanks for pointing this out!

I also remove these protected methods from ChannelLayerManager that appear to be internal-only:

class ChannelLayerManager: # ... other methods ... def _reset_backends(self, setting: str, **kwargs: Any) -> None: ... def _make_backend(self, name: str, config: dict[str, Any]) -> BaseChannelLayer: ... ```"

stubs/channels/channels/auth.pyi

huynguyengl99 · 2025-05-13T03:16:11Z

Hi @sobolevn, I have updated the code following your suggestions and left a small question related to the dispatch function in my above comment. I hope you can have a quick look at that to see if it's okay or not.

carltongibson · 2025-05-13T08:38:31Z

stubs/channels/channels/utils.pyi

+class _MiddlewareProtocol(Protocol):
+    def __init__(self, *args: Any, **kwargs: Any) -> None: ...
+    async def __call__(self, scope: Any, receive: Any, send: Any) -> Any: ...
+


This is just the ASGI2Protocol from asgiref.typing, which is already part of ASGIApplication no?

No, the ASGI2Protocol class is missing the scope param in call:

class ASGI2Protocol(Protocol): def __init__(self, scope: Scope) -> None: ... async def __call__( self, receive: ASGIReceiveCallable, send: ASGISendCallable ) -> None: ...

Also the init of OriginValidator is a little bit different to the other middlewares (1 extra param), that's why I need to use *args and **kwargs instead:

class OriginValidator: application: _ChannelApplication allowed_origins: Iterable[str | Pattern[str]] def __init__(self, application: _ChannelApplication, allowed_origins: Iterable[str | Pattern[str]]) -> None: ... async def __call__(self, scope: _ChannelScope, receive: ASGIReceiveCallable, send: ASGISendCallable) -> Any: ...

It's quite like the ASGI3Application, but we also have the init function. I tried to match it with the middleware in sessions.pyi, security/websocket.pyi and middleware.pyi files, so I think I need to create a new protocol for that.

stubs/channels/channels/consumer.pyi

github-actions · 2025-05-13T16:07:56Z

Diff from mypy_primer, showing the effect of this PR on open source code:

strawberry (https://github.com/strawberry-graphql/strawberry)
- strawberry/channels/handlers/base.py:14: error: Cannot find implementation or library stub for module named "channels.consumer"  [import-not-found]
- strawberry/channels/handlers/base.py:15: error: Cannot find implementation or library stub for module named "channels.generic.websocket"  [import-not-found]
+ note: "__init_subclass__" of "object" defined here
+ strawberry/channels/handlers/base.py:57: error: Incompatible types in assignment (expression has type "ChannelsLayer | None", base class "AsyncConsumer" defined the type as "BaseChannelLayer")  [assignment]
+ strawberry/channels/handlers/base.py:66: error: Argument 1 of "dispatch" is incompatible with supertype "AsyncConsumer"; supertype defines the argument type as "dict[str, Any]"  [override]
+ strawberry/channels/handlers/base.py:66: note: This violates the Liskov substitution principle
+ strawberry/channels/handlers/base.py:66: note: See https://mypy.readthedocs.io/en/stable/common_issues.html#incompatible-overrides
+ strawberry/channels/handlers/base.py:77: error: Argument 1 to "dispatch" of "AsyncConsumer" has incompatible type "ChannelsMessage"; expected "dict[str, Any]"  [arg-type]
+ strawberry/channels/handlers/base.py:209: error: Definition of "channel_layer" in base class "ChannelsConsumer" is incompatible with definition in base class "AsyncWebsocketConsumer"  [misc]
- strawberry/channels/testing.py:13: error: Cannot find implementation or library stub for module named "channels.testing.websocket"  [import-not-found]
+ strawberry/channels/testing.py:101: error: Incompatible types in assignment (expression has type "dict[str, Any]", variable has type "ConnectionAckMessage")  [assignment]
+ strawberry/channels/testing.py:109: error: Incompatible types in assignment (expression has type "dict[str, Any]", variable has type "ConnectionAckMessage")  [assignment]
+ strawberry/channels/testing.py:146: error: Incompatible types in assignment (expression has type "dict[str, Any]", variable has type "ConnectionInitMessage | ConnectionAckMessage | PingMessage | PongMessage | SubscribeMessage | NextMessage | ErrorMessage | CompleteMessage")  [assignment]
+ strawberry/channels/handlers/ws_handler.py:69: error: Definition of "channel_layer" in base class "ChannelsConsumer" is incompatible with definition in base class "AsyncWebsocketConsumer"  [misc]
+ strawberry/channels/handlers/ws_handler.py:133: error: Argument 1 to "run" of "AsyncBaseHTTPView" has incompatible type "GraphQLWSConsumer[Context, RootValue]"; expected "GraphQLWSConsumer[None, None]"  [arg-type]
- strawberry/channels/handlers/http_handler.py:22: error: Cannot find implementation or library stub for module named "channels.db"  [import-not-found]
- strawberry/channels/handlers/http_handler.py:23: error: Cannot find implementation or library stub for module named "channels.generic.http"  [import-not-found]
+ strawberry/channels/handlers/http_handler.py:200: error: "BaseGraphQLHTTPConsumer" has no attribute "run"  [attr-defined]
+ strawberry/channels/handlers/http_handler.py:207: error: Argument "headers" to "send_headers" of "AsyncHttpConsumer" has incompatible type "dict[bytes, bytes]"; expected "Iterable[tuple[bytes, bytes]] | None"  [arg-type]
+ strawberry/channels/handlers/http_handler.py:360: error: Return type "Coroutine[Any, Any, ChannelsResponse | MultipartChannelsResponse]" of "run" incompatible with return type "ChannelsResponse" in supertype "SyncBaseHTTPView"  [override]
- strawberry/channels/router.py:14: error: Cannot find implementation or library stub for module named "channels.routing"  [import-not-found]

This comment has been minimized.

Sign in to view

huynguyengl99 force-pushed the feature/channels-stubs branch from 040b12e to 2edbaf3 Compare May 4, 2025 17:16

This comment has been minimized.

Sign in to view

huynguyengl99 mentioned this pull request May 4, 2025

Add asgiref to allowlist typeshed-internal/stub_uploader#173

Merged

This comment has been minimized.

Sign in to view

sobolevn reviewed May 4, 2025

View reviewed changes

stubs/channels/METADATA.toml Outdated Show resolved Hide resolved

stubs/channels/METADATA.toml Outdated Show resolved Hide resolved

stubs/channels/channels/testing/http.pyi Show resolved Hide resolved

stubs/channels/channels/testing/live.pyi Outdated Show resolved Hide resolved

This comment has been minimized.

Sign in to view

huynguyengl99 force-pushed the feature/channels-stubs branch from 24e066b to e80bd03 Compare May 5, 2025 05:44

This comment has been minimized.

Sign in to view

huynguyengl99 force-pushed the feature/channels-stubs branch from e80bd03 to 0f45154 Compare May 5, 2025 10:31

This comment has been minimized.

Sign in to view

huynguyengl99 added 6 commits May 12, 2025 11:00

Django channels stubs

f6f330b

Fix alias type for python 3.9

41cf2ba

Correct some Any type channel layer

7c38b21

Add type_check_only, TODO comment, and constrain django-stubs version

b38d9b4

Add type_check_only for channels consumer and testing http

76842c8

Add stubtest

4690c72

huynguyengl99 force-pushed the feature/channels-stubs branch from 0f45154 to 4690c72 Compare May 12, 2025 04:00

This comment has been minimized.

Sign in to view

huynguyengl99 mentioned this pull request May 12, 2025

Stubs package for Django Channels #14020

Open

sobolevn reviewed May 12, 2025

View reviewed changes

srittau linked an issue May 12, 2025 that may be closed by this pull request

Stubs package for Django Channels #14020

Open

huynguyengl99 added 2 commits May 12, 2025 22:17

Migrate database_sync_to_async to async def for auth.pyi functions

712f388

Remove internal function type definitions

9ebfab5

This comment has been minimized.

Sign in to view

collinanderson mentioned this pull request May 12, 2025

Add type hints django/channels#893

Closed

Remove internal function type definitions (more)

4c430ce

This comment has been minimized.

Sign in to view

carltongibson reviewed May 13, 2025

View reviewed changes

Correct Channels typo (plural)

f1333f8

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Django channels stubs #13939

Django channels stubs #13939

huynguyengl99 commented May 4, 2025 •

edited

Loading

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

huynguyengl99 commented May 4, 2025

This comment has been minimized.

sobolevn left a comment

Tatsh commented May 4, 2025 •

edited

Loading

sobolevn left a comment

huynguyengl99 commented May 5, 2025

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

sobolevn left a comment

sobolevn May 5, 2025

huynguyengl99 May 12, 2025

sobolevn May 12, 2025

huynguyengl99 May 12, 2025

huynguyengl99 May 12, 2025

sobolevn May 12, 2025

huynguyengl99 May 12, 2025 •

edited

Loading

This comment has been minimized.

huynguyengl99 commented May 13, 2025

This comment has been minimized.

carltongibson May 13, 2025

huynguyengl99 May 13, 2025

github-actions bot commented May 13, 2025

		def get_handler_name(message: dict[str, Any]) -> str: ...
		@type_check_only

Django channels stubs #13939

Are you sure you want to change the base?

Django channels stubs #13939

Conversation

huynguyengl99 commented May 4, 2025 • edited Loading

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

huynguyengl99 commented May 4, 2025

This comment has been minimized.

sobolevn left a comment

Choose a reason for hiding this comment

Tatsh commented May 4, 2025 • edited Loading

sobolevn left a comment

Choose a reason for hiding this comment

huynguyengl99 commented May 5, 2025

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

sobolevn left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

huynguyengl99 May 12, 2025 • edited Loading

Choose a reason for hiding this comment

This comment has been minimized.

huynguyengl99 commented May 13, 2025

This comment has been minimized.

Choose a reason for hiding this comment

Choose a reason for hiding this comment

github-actions bot commented May 13, 2025

huynguyengl99 commented May 4, 2025 •

edited

Loading

Tatsh commented May 4, 2025 •

edited

Loading

huynguyengl99 May 12, 2025 •

edited

Loading