Add typings

[bryanforbes]

I've added pyi files as siblings to all of the library files:

• I've tried to only type the public API. I may have missed something or provided too many methods. Feel free to indicate what should be added or removed.
• Any class that is typed as generic (iterators, Command, Group, etc.) has to inherit from typing.Generic in order to be subscriptable and not throw errors when using generic subscripts in python code.
• In the course of doing this work, I converted the entire core codebase over to typed Python and found a few bugs. I've included those bug fixes (calls.py, message.py, state.py, and user.py).
• While Python 3.5.x is still the oldest version the library uses, the typings require Python 3.6 for PEP-526.
• I've added an optional feature that will pull in mypy_extensions and typing_extensions for TypedDict and Protocol respectively. These will not be pulled in unless specified by the consumer.
• I have also tested these typings in a library I wrote that uses discord.py as well as a bot I wrote.

[Rapptz]

I understand the usage and reasons for .pyi files existing.

However, I do not think they apply to this right? Shouldn't the goal be to apply these typings to the main functions inside the library instead of using stubs?

[bryanforbes]

There are a few advantages to using .pyi files alongside modules:

• Keeping typings out of the main library gives a small startup performance gain.
• Typing the function signatures in the library will cause mypy to type check the function body when it is run on the library code base.
• Only exposing the public API of the library.

As I said, I initially started out typing the entire library (including the function bodies), but after discussing with you in PM on Discord you mentioned that you didn't feel strongly about having the library code typed. I thought this was a good compromise.

[Hornwitser]

The bugfixes should probably be split up into their own commit (or maybe pull request). They don't really have anything to do with adding typings to the lib.

[bryanforbes]

The bugfixes should probably be split up into their own commit (or maybe pull request).

Good call. I'll separate them out.

[bryanforbes]

I've separated the fixes out into their own PRs and removed them from this one as well as rebasing on rewrite

[Werseter]

BotBase type hints could use the Dict[str, Any] for cogs, extra_events and extensions.

Also, any call to discord.ext.commands going through such syntax complains about ext not being in the __init__.pyi.

[bryanforbes]

BotBase type hints could use the Dict[str, Any] for cogs, extra_events and extensions.

Added

Also, any call to discord.ext.commands going through such syntax complains about ext not being in the __init__.pyi.

As long as you import discord.ext.commands, you can use discord.ext.commands.Bot(). Even without typings, this is the case. You cannot access discord.ext.commands by simply using import discord.

[Werseter]

If you do from discord.ext import commands and call discord.ext.commands for some reason instead of just commands it will prompt up as not setup up for typing (also implicitly assuming discord has been imported as well)

I never implied it is a proper way to use it, but it exists, and typings should cover for it too, instead of pulling up a warn.

[bryanforbes]

I just tried the following:

import discord
from discord.ext import commands

Bot = discord.ext.commands.Bot
reveal_type(Bot)

I don't get a warning from mypy and it correctly reveals that it's a function that will return discord.ext.commands.bot.Bot[CT]. This seems to be the scenario you're describing and it seems to work.

[Werseter]

Could it be it is the PyCharm's linter issue?

That would be silly tho, but if it's fine with mypy, then I guess it's fine, it's a niche case anyway.

[Werseter]

It's been a while, as I still am in middle of transitioning my project to Type Hints, but I caught that abc.GuildChannel, abc.Messageable, abc.PrivateChannel and abc.User, could use Snowflake hints, as per "This ABC must also implement :class:abc.Snowflake."

[bryanforbes]

Since Snowflake is a Protocol, any object that has the same properties as it has will match it, which is what the actual Snowflake class does. The classes which subclass the ABCs you listed all implement the Snowflake protocol. The documentation string should probably be updated to say “Subclasses of this ABC must also implement the Snowflake protocol”.

[Werseter]

Well, given that any object typed as GuildChannel - i.e list returned by ctx.guild.channels, will be said to not have an id property, as it must be implemented by a subclass, but not by the abstract itself. Since the assumption of this implementation is declared as imperative, shouldn't the typings have those two properties included?

[Werseter]

Or, perhaps the other way around, possibly the channels field of Guild could be typed as List[Union[TextChannel, VoiceChannel, CategoryChannel]] instead of List[GuildChannel].

This would merely be escaping from the single-case issue here. It raises a question of whether anything should be typed with an abstract, and not with the actual functional classes.

[Werseter]

Just a note about the fact recent library update might require this getting a lil update.

[nihaals]

Is this going to be merged or should someone change it to be in code (like using Sphinx doc strings allowing it to be explicit on the docs too)? I've wanted typing for the last year so would love a solution

[Werseter]

I myself have been using this on my own for a while, and I have to say it has been of great assist, but given that using the type hints in python, at least now, afaik isn't really _too mainstream_, and can be confusing as to the usecase. I'd nevertheless welcome the addition of this at least as an optional extension.

[nihaals]

I think most of the attributes missing types have a doc string anyway, so although it seems a bit long, the be might be using Returns as if it was a function, and maybe in the future convert some of it to another solution.

[ghost]

Any news on when this will be added to discord.py? Typing is very useful.

[Jackenmen]

I don't have a news on that, but now there's a discord.py-stubs package from the author of this PR, which you could use if you need d.py to be typed.

[bryanforbes]

After a few months of inactivity here, I've decided that it will be easier for me to maintain the stubs in their own package on pypi named discord.py-stubs. This does add some complexity in using discord.py with mypy, namely using generics from the stubs when they aren't generic at runtime. For instance, to create a Cog that could be type checked you would have to do the following:

from typing import TYPE_CHECKING
from discord.ext import commands

if TYPE_CHECKING:
    Cog = commands.Cog[commands.Context]
else:
    Cog = commands.Cog

class MyCog(Cog):
    ...

To alleviate this issue, I have also created discord-ext-typed-commands which mirrors the commands module, but adds the ability to subscript for generics:

from discord.ext import typed_commands

class MyCog(typed_commands.Cog[commands.Context]):
    ...

Thanks to @Rapptz for the help here as well as everyone who reviewed this PR (especially @NCPlayz and @Werseter )!