Unpack usage where possible #10189

Soheab · 2025-05-16T22:09:37Z

Summary

https://canary.discord.com/channels/336642139381301249/1371429669395759195

Tracking

Checklist

If code changes were made then they have been tested.
- I have updated the documentation to reflect the changes.
This PR fixes an issue.
This PR adds something new (e.g. new method or parameters).
This PR is a breaking change (e.g. methods or parameters removed/renamed)
This PR is not a code change (e.g. documentation, README, ...)

discord/channel.py

Rapptz · 2025-07-27T17:20:53Z

discord/client.py

    """

-    def __init__(self, *, intents: Intents, **options: Any) -> None:
+    def __init__(self, *, intents: Intents, **options: Unpack[_ClientOptions]) -> None:


So, the reason why I didn't do this before for Client is because as part of the contract that you can inherit from Client this means that any extra args would cause type errors even though they might use the extra kwargs themselves.

I'm unsure where I really stand on this from a usability POV, and I don't know if it's that annoying.

Unsure what you mean as extra kwargs are ignored anyways and you lose the typed kwargs when subclassing and overriding the __init__ to handle the extra args anyways.

class MyClient(discord.Client): ... # Argument missing for parameter "intents" (expected) # No parameter named "hello" (expected but ignored anyways) MyClient(hello="lol") class ClientWithInit(discord.Client): # *args = tuple[Unknown, ...], **kwargs = dict[str, Unknown] def __init__(self, *args, **kwargs) -> None: # handling extra kwarg self.foo = kwargs.pop("foo") super().__init__(*args, **kwargs) ClientWithInit(foo="bar") # works fine

Suggested change

def __init__(self, *, intents: Intents, **options: Unpack[_ClientOptions]) -> None:

def __init__(self, *, intents: Intents, **options: Unpack[_ClientOptions]) -> None:

The other issue is that it doesn't allow people who inherit to have the same ability, e.g. ClientWithInit(intents=None) passes despite it not meeting the type signature. I guess it's fine just unfortunate.

Yeah, there’s unfortunately no good way to make these public. The user can, if they want, import them in a TYPE_CHECKING block, but that’s probably not good advice to give.

That's not going to be supported -- and what I'm talking about is an actual supported way of doing this. I guess it has no impact on this PR. The most annoying thing right now is the duplication of all the flags/permissions.

Rapptz · 2025-07-27T17:21:58Z

discord/ext/commands/bot.py

+            allowed_contexts: app_commands.AppCommandContext = MISSING,
+            allowed_installs: app_commands.AppInstallationType = MISSING,
+            intents: discord.Intents,
+            **kwargs: Unpack[_AutoShardedBotOptions],


Same nit as before.

Rapptz · 2025-07-27T17:22:27Z

discord/ext/commands/cog.py

    __cog_listeners__: List[Tuple[str, str]]

-    def __new__(cls, *args: Any, **kwargs: Any) -> CogMeta:
+    def __new__(cls, *args: Any, **kwargs: Unpack[_CogKwargs]) -> CogMeta:


Does this even work from a user's POV?

Unfortunately not. It does error out when the user has typed the correct name but the wrong type.

discord/ext/commands/core.py

Rapptz · 2025-07-27T17:26:38Z

discord/flags.py

    __slots__ = ()

-    def __init__(self, value: int = 0, **kwargs: bool) -> None:
+    def __init__(self, value: int = 0, **kwargs: Unpack[_IntentsFlagsKwargs]) -> None:


Another reason why I was not a fan of doing this is because now there are more places to edit when adding a single thing. This is especially egregious with permissions which need to have an added value both in its TYPE_CHECKING block and now in its Unpack dictionary.

I suppose it's unavoidable, but honestly it's just really annoying.

Fair point, it's a bit annoying to update things in more than one place. But for users, it's kinda nice to have. Also, most people don’t know you can use kwargs to construct flags like this, so showing them helps with that too.

Rapptz · 2025-07-27T17:27:09Z

discord/shard.py

        _connection: AutoShardedConnectionState

-    def __init__(self, *args: Any, intents: Intents, **kwargs: Any) -> None:
+    def __init__(self, *args: Any, intents: Intents, **kwargs: Unpack[_AutoShardedClientOptions]) -> None:


Same nit as Client and AutoShardedBot.

Rapptz · 2025-08-14T16:05:37Z

discord/permissions.py

                raise TypeError(f'{key!r} is not a valid permission name.') from None
            else:
-                self._set_flag(flag, value)
+                self._set_flag(flag, kwvalue)  # type: ignore


Why does this need a type ignore?

all values are object when iterating over a TypedDict, so it throws the following:

Argument of type "object" cannot be assigned to parameter "toggle" of type "bool" in function "_set_flag" "object" is not assignable to "bool"PylancereportArgumentType

AFAIK this is a not-fixable TypedDict annoyance.

That's pretty goofy. Add it in the comments.

Soheab added 2 commits May 17, 2025 00:03

Client & Bot

6dbe118

fix: intents should actually be required

b4a10c5

Soheab changed the title ~~[WIP] Unpack usage where possible~~ Unpack usage where possible May 16, 2025

Soheab added 18 commits May 17, 2025 00:22

Remove unused imports

38b72da

flags: Intents

79e426f

ext.commands: cog, core

3ff6628

Remove unneeded total=False

13848f0

Run "black discord"

edb32b6

ext.commands: hybrid

7e8a254

Remove unusued imports

89a210b

flags: MemberCacheFlags

f2700a9

Permission[s](Overwrite)

624ce4d

AutoSharded(Client/Bot)

2353a82

Remove unnecessary comments

574235c

permissions

0145ecb

ext.commands: help

62a59ba

ext.commands: core

21b07a2

ext.commands: bot

62e6b8e

ext.commands: checks

b2173bf

abc

a4aeab9

app_commands: commands

a79a693

Soheab marked this pull request as ready for review May 17, 2025 20:12

Soheab added 4 commits May 18, 2025 17:10

Add missing kwargs for (AutoSharded)Bot

621af5f

Use total=False over NotRequired everything

b52ded6

Cleanup types for Permission(s)(Overwrite)

6224fb5

Category.create_text/voice/stage/forum(_channel)

63e799d

Rapptz reviewed Jul 27, 2025

View reviewed changes

Soheab added 3 commits August 14, 2025 15:37

Remove unused classes

33dae2e

Remove from Command.__new__

8a004a1

Merge remote-tracking branch 'upstream/master' into feat/typed-kwargs

999b619

Rapptz reviewed Aug 14, 2025

View reviewed changes

Add comment to type-ignore

332f1ae

Rapptz merged commit 983a9b8 into Rapptz:master Aug 15, 2025
8 checks passed

	def __init__(self, , intents: Intents, *options: Unpack[_ClientOptions]) -> None:
	def __init__(self, , intents: Intents, *options: Unpack[_ClientOptions]) -> None:

Uh oh!

Unpack usage where possible #10189

Unpack usage where possible #10189

Conversation

Soheab commented May 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Tracking

Checklist

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Soheab Aug 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Soheab commented May 16, 2025 •

edited

Loading

Soheab Aug 14, 2025 •

edited

Loading