feat: Polls

[NeloBlivion]

Summary

Implements polls and related features. WIP while the original PR becomes more stable over the experimental phase.
References:

• Document polls. discord/discord-api-docs#6746

Notes:

• While the API for PollMedia denotes both text and emoji as optional, text must be non-null for both questions and answers; as such, it's required here.
• For Poll and PollAnswer, PollMedia is abstracted to its attributes (e.g. Poll.PollMedia.text is assigned to Poll.question). An undocumented attribute _media still remains. After reconsidering, this wasn't great. For __init__s you can just pass the strings, but otherwise you'd access through Poll.question.text, for example.
• Will work on a new AsyncIterator for answer.users Complete

Information

• 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, typehinting,
  examples, ...).

Checklist

• I have searched the open pull requests for duplicates.
• If code changes were made then they have been tested.
  • I have updated the documentation to reflect the changes.
• If type: ignore comments were used, a comment is also left explaining why.
• I have updated the changelog to include these changes.

[jab416171]

• doesn't work with ctx.respond(poll=poll)
• getting this error with this code:

@commands.slash_command(name="poll")
async def poll(self, ctx, question: Option(str), option1: Option(str), option2: Option(str)):
    """Start a poll"""
    poll = Poll(question=question, answers=[option1, option2], duration=300, allow_multiselect=False)
    await ctx.send(poll=poll)

exception in command poll:
Traceback (most recent call last):
  File "/usr/local/lib/python3.8/site-packages/discord/commands/core.py", line 131, in wrapped
    ret = await coro(arg)
  File "/usr/local/lib/python3.8/site-packages/discord/commands/core.py", line 1009, in _invoke
    await self.callback(self.cog, ctx, **kwargs)
  File "/mybot/cogs/mycog.py", line 483, in poll
    await ctx.send(poll=poll)
  File "/usr/local/lib/python3.8/site-packages/discord/abc.py", line 1609, in send
    poll = poll.to_dict()
  File "/usr/local/lib/python3.8/site-packages/discord/poll.py", line 304, in to_dict
    "question": self.question.to_dict(),
AttributeError: 'str' object has no attribute 'to_dict'

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/usr/local/lib/python3.8/site-packages/discord/bot.py", line 1130, in invoke_application_command
    await ctx.command.invoke(ctx)
  File "/usr/local/lib/python3.8/site-packages/discord/commands/core.py", line 376, in invoke
    await injected(ctx)
  File "/usr/local/lib/python3.8/site-packages/discord/commands/core.py", line 139, in wrapped
    raise ApplicationCommandInvokeError(exc) from exc
discord.errors.ApplicationCommandInvokeError: Application Command raised an exception: AttributeError: 'str' object has no attribute 'to_dict'
Ignoring exception in on_application_command_error
Traceback (most recent call last):
  File "/usr/local/lib/python3.8/site-packages/discord/commands/core.py", line 131, in wrapped
    ret = await coro(arg)
  File "/usr/local/lib/python3.8/site-packages/discord/commands/core.py", line 1009, in _invoke
    await self.callback(self.cog, ctx, **kwargs)
  File "/mybot/cogs/mycog.py", line 483, in poll
    await ctx.send(poll=poll)
  File "/usr/local/lib/python3.8/site-packages/discord/abc.py", line 1609, in send
    poll = poll.to_dict()
  File "/usr/local/lib/python3.8/site-packages/discord/poll.py", line 304, in to_dict
    "question": self.question.to_dict(),
AttributeError: 'str' object has no attribute 'to_dict'

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/usr/local/lib/python3.8/site-packages/discord/client.py", line 400, in _run_event
    await coro(*args, **kwargs)
  File "/mybot/cogs/help.py", line 81, in on_application_command_error
    raise error
  File "/usr/local/lib/python3.8/site-packages/discord/bot.py", line 1130, in invoke_application_command
    await ctx.command.invoke(ctx)
  File "/usr/local/lib/python3.8/site-packages/discord/commands/core.py", line 376, in invoke
    await injected(ctx)
  File "/usr/local/lib/python3.8/site-packages/discord/commands/core.py", line 139, in wrapped
    raise ApplicationCommandInvokeError(exc) from exc
discord.errors.ApplicationCommandInvokeError: Application Command raised an exception: AttributeError: 'str' object has no attribute 'to_dict'```

[NeloBlivion]

• doesn't work with ctx.respond(poll=poll)
• getting this error with this code:

these are fixed in the latest version. Note that question should be a full PollMedia object (e.g. PollMedia("my question")), but STC

[jab416171]

I still have both of these errors on 9423a8a, and I did change it to use PollMedia

[NeloBlivion]

I still have both of these errors on 9423a8a, and I did change it to use PollMedia

Try now? Also if this back and forth goes longer, may be better to tag me on discord

[plun1331]

intent docs should be updated:
https://docs.pycord.dev/en/stable/api/data_classes.html#discord.Intents.guild_messages
https://docs.pycord.dev/en/stable/api/data_classes.html#discord.Intents.message_content

[NeloBlivion]

As the main PR is merged, this is effectively ready

• poll can be sent with content and embed(s), but not file(s) due to clashes with upcoming poll features that are undocumented (unless i should implement these early?)
• poll cannot be edited after being sent, but content and embeds on the same message can.
• New Intents.polls and Permissions.send_polls
• While polls rely on message_content intent, they are cached separately through Client.polls and Client.get_poll. Polls will be cached through the following:
  • Message sends
  • ANY message edit
  • Any form of message fetch - e.g. channel.fetch_message for individual messages, or channel.history will get several polls
• on_message_edit will fire when a poll ends (naturally, or Message.end_poll(), or poll.end() AND the votes have been finalized.
• Intents.polls is a default intent that is required for tracking poll votes through on_poll_vote_add and on_poll_vote_remove, both using the args poll, user, answer

Now for the creation of polls, I wasn't entirely sure on the best approach. question only supports text, so it can be initialized as follows:

• Poll(some_question)
• Poll(question=PollMedia(some_question))

But answers are more complicated, due to supporting text, emoji and soon attachment. So you can either pass answers as a list of PollAnswer, or use Poll.add_answer chaining like you would with embeds:

• Poll(question=some_question, answers=[PollAnswer(some_answer), PollAnswer(another_answer, emoji=...)])
• Poll(some_question).add_answer(some_answer)

Due to the extensiveness of the polls API, I feel this is one of those instances where it's beneficial to add extra convenience for the user instead of sticking to it religiously.
The other args are completely optional, using the defaults present on Discord's UI when creating polls (allow_multiselect=False, duration=24, no other layout_type yet.)
Due to results being nullable for some reason at random, a few conveniences have been added:

• poll.results.is_finalized -> poll.has_ended()
• poll.results.total_votes() -> poll.total_votes()
• Answer counts are typically stored in poll.results.answer_counts, but each PollAnswer has the count attribute; returning None if results is also None, 0 if the answer isn't in answer_counts, otherwise the relevant count.

If you are able to, please stress test this PR and see if the internally cached vote counts are able to keep up with realtime counts on Discord, especially when bouncing between 1-0 votes on specific answers; this part involves manual deletion and creation of PollAnswerCount objects, so it may be possible for something to go wrong that I couldn't catch in solo tests.

[Lulalaby]

Changelog

[JustaSqu1d]

documentation suggestions

• fix minor mistakes
• more formal writing
• formatting

[JustaSqu1d]

The docs follows standard US English conventions.

AMERICA!! 🦅

[Dorukyum]

Will test personally, but your testing would still be appreciated (you haven't checked the box in the checklist).

[Icebluewolf]

I have thoroughly tested the PR as of 1 month ago. All of the core functionality works. It does not look like any major changes to functionality were made recently.

[JustaSqu1d]

minor grammar/spelling