Run black on all examples and require it for CI

.github/workflows/lint.yml

@@ -48,4 +48,4 @@ jobs:
       - name: Run black
         if: ${{ always() && steps.install-deps.outcome == 'success' }}
         run: |
-          black --check --verbose discord
+          black --check --verbose discord examples

examples/background_task.py

@@ -2,6 +2,7 @@ from discord.ext import tasks
 
 import discord
 
+
 class MyClient(discord.Client):
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
@@ -17,15 +18,16 @@ class MyClient(discord.Client):
         print(f'Logged in as {self.user} (ID: {self.user.id})')
         print('------')
 
-    @tasks.loop(seconds=60) # task runs every 60 seconds
+    @tasks.loop(seconds=60)  # task runs every 60 seconds
     async def my_background_task(self):
-        channel = self.get_channel(1234567) # channel ID goes here
+        channel = self.get_channel(1234567)  # channel ID goes here
         self.counter += 1
         await channel.send(self.counter)
 
     @my_background_task.before_loop
     async def before_my_task(self):
-        await self.wait_until_ready() # wait until the bot logs in
+        await self.wait_until_ready()  # wait until the bot logs in
+
 
 client = MyClient()
 client.run('token')

examples/background_task_asyncio.py

@@ -1,6 +1,7 @@
 import discord
 import asyncio
 
+
 class MyClient(discord.Client):
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
@@ -16,11 +17,11 @@ class MyClient(discord.Client):
     async def my_background_task(self):
         await self.wait_until_ready()
         counter = 0
-        channel = self.get_channel(1234567) # channel ID goes here
+        channel = self.get_channel(1234567)  # channel ID goes here
         while not self.is_closed():
             counter += 1
             await channel.send(counter)
-            await asyncio.sleep(60) # task runs every 60 seconds
+            await asyncio.sleep(60)  # task runs every 60 seconds
 
 
 client = MyClient()

examples/basic_bot.py

@@ -15,16 +15,19 @@ intents.message_content = True
 
 bot = commands.Bot(command_prefix='?', description=description, intents=intents)
 
+
 @bot.event
 async def on_ready():
     print(f'Logged in as {bot.user} (ID: {bot.user.id})')
     print('------')
 
+
 @bot.command()
 async def add(ctx, left: int, right: int):
     """Adds two numbers together."""
     await ctx.send(left + right)
 
+
 @bot.command()
 async def roll(ctx, dice: str):
     """Rolls a dice in NdN format."""
@@ -37,22 +40,26 @@ async def roll(ctx, dice: str):
     result = ', '.join(str(random.randint(1, limit)) for r in range(rolls))
     await ctx.send(result)
 
+
 @bot.command(description='For when you wanna settle the score some other way')
 async def choose(ctx, *choices: str):
     """Chooses between multiple choices."""
     await ctx.send(random.choice(choices))
 
+
 @bot.command()
 async def repeat(ctx, times: int, content='repeating...'):
     """Repeats a message multiple times."""
     for i in range(times):
         await ctx.send(content)
 
+
 @bot.command()
 async def joined(ctx, member: discord.Member):
     """Says when a member joined."""
     await ctx.send(f'{member.name} joined in {member.joined_at}')
 
+
 @bot.group()
 async def cool(ctx):
     """Says if a user is cool.
@@ -62,9 +69,11 @@ async def cool(ctx):
     if ctx.invoked_subcommand is None:
         await ctx.send(f'No, {ctx.subcommand_passed} is not cool')
 
+
 @cool.command(name='bot')
 async def _bot(ctx):
     """Is the bot cool?"""
     await ctx.send('Yes, the bot is cool.')
 
+
 bot.run('token')

examples/basic_voice.py

@@ -22,11 +22,11 @@ ytdl_format_options = {
     'quiet': True,
     'no_warnings': True,
     'default_search': 'auto',
-    'source_address': '0.0.0.0' # bind to ipv4 since ipv6 addresses cause issues sometimes
+    'source_address': '0.0.0.0',  # bind to ipv4 since ipv6 addresses cause issues sometimes
 }
 
 ffmpeg_options = {
-    'options': '-vn'
+    'options': '-vn',
 }
 
 ytdl = youtube_dl.YoutubeDL(ytdl_format_options)
@@ -125,21 +125,27 @@ class Music(commands.Cog):
         elif ctx.voice_client.is_playing():
             ctx.voice_client.stop()
 
+
 intents = discord.Intents.default()
 intents.message_content = True
 
-bot = commands.Bot(command_prefix=commands.when_mentioned_or("!"),
-                   description='Relatively simple music bot example',
-                   intents=intents)
+bot = commands.Bot(
+    command_prefix=commands.when_mentioned_or("!"),
+    description='Relatively simple music bot example',
+    intents=intents,
+)
+
 
 @bot.event
 async def on_ready():
     print(f'Logged in as {bot.user} (ID: {bot.user.id})')
     print('------')
 
+
 async def main():
     async with bot:
         await bot.add_cog(Music(bot))
         await bot.start('token')
 
+
 asyncio.run(main())

examples/converters.py

@@ -33,6 +33,7 @@ async def userinfo(ctx: commands.Context, user: discord.User):
     avatar = user.display_avatar.url
     await ctx.send(f'User found: {user_id} -- {username}\n{avatar}')
 
+
 @userinfo.error
 async def userinfo_error(ctx: commands.Context, error: commands.CommandError):
     # if the conversion above fails for any reason, it will raise `commands.BadArgument`
@@ -40,6 +41,7 @@ async def userinfo_error(ctx: commands.Context, error: commands.CommandError):
     if isinstance(error, commands.BadArgument):
         return await ctx.send('Couldn\'t find that user.')
 
+
 # Custom Converter here
 class ChannelOrMemberConverter(commands.Converter):
     async def convert(self, ctx: commands.Context, argument: str):
@@ -75,16 +77,16 @@ class ChannelOrMemberConverter(commands.Converter):
         raise commands.BadArgument(f'No Member or TextChannel could be converted from "{argument}"')
 
 
-
 @bot.command()
 async def notify(ctx: commands.Context, target: ChannelOrMemberConverter):
     # This command signature utilises the custom converter written above
     # What will happen during command invocation is that the `target` above will be passed to
-    # the `argument` parameter of the `ChannelOrMemberConverter.convert` method and 
+    # the `argument` parameter of the `ChannelOrMemberConverter.convert` method and
     # the conversion will go through the process defined there.
 
     await target.send(f'Hello, {target.name}!')
 
+
 @bot.command()
 async def ignore(ctx: commands.Context, target: typing.Union[discord.Member, discord.TextChannel]):
     # This command signature utilises the `typing.Union` typehint.
@@ -98,9 +100,10 @@ async def ignore(ctx: commands.Context, target: typing.Union[discord.Member, dis
     # To check the resulting type, `isinstance` is used
     if isinstance(target, discord.Member):
         await ctx.send(f'Member found: {target.mention}, adding them to the ignore list.')
-    elif isinstance(target, discord.TextChannel): # this could be an `else` but for completeness' sake.
+    elif isinstance(target, discord.TextChannel):  # this could be an `else` but for completeness' sake.
         await ctx.send(f'Channel found: {target.mention}, adding it to the ignore list.')
 
+
 # Built-in type converters.
 @bot.command()
 async def multiply(ctx: commands.Context, number: int, maybe: bool):
@@ -112,4 +115,5 @@ async def multiply(ctx: commands.Context, number: int, maybe: bool):
         return await ctx.send(number * 2)
     await ctx.send(number * 5)
 
+
 bot.run('token')

examples/custom_context.py

@@ -30,15 +30,17 @@ class MyBot(commands.Bot):
         # subclass to the super() method, which tells the bot to
         # use the new MyContext class
         return await super().get_context(message, cls=cls)
-        
+
+
 intents = discord.Intents.default()
 intents.message_content = True
 
 bot = MyBot(command_prefix='!', intents=intents)
 
+
 @bot.command()
 async def guess(ctx, number: int):
-    """ Guess a random number from 1 to 6. """
+    """Guess a random number from 1 to 6."""
     # explained in a previous example, this gives you
     # a random number from 1-6
     value = random.randint(1, 6)
@@ -47,8 +49,9 @@ async def guess(ctx, number: int):
     # or a red cross mark if it wasn't
     await ctx.tick(number == value)
 
+
 # IMPORTANT: You shouldn't hard code your token
-# these are very important, and leaking them can 
+# these are very important, and leaking them can
 # let people do very malicious things with your
 # bot. Try to use a file or something to keep
 # them private, and don't commit it to GitHub

examples/deleted.py

@@ -2,6 +2,7 @@
 
 import discord
 
+
 class MyClient(discord.Client):
     async def on_ready(self):
         print(f'Logged in as {self.user} (ID: {self.user.id})')
@@ -19,6 +20,7 @@ class MyClient(discord.Client):
         msg = f'{message.author} has deleted the message: {message.content}'
         await message.channel.send(msg)
 
+
 intents = discord.Intents.default()
 intents.message_content = True
 

examples/edits.py

@@ -3,6 +3,7 @@
 import discord
 import asyncio
 
+
 class MyClient(discord.Client):
     async def on_ready(self):
         print(f'Logged in as {self.user} (ID: {self.user.id})')
@@ -18,6 +19,7 @@ class MyClient(discord.Client):
         msg = f'**{before.author}** edited their message:\n{before.content} -> {after.content}'
         await before.channel.send(msg)
 
+
 intents = discord.Intents.default()
 intents.message_content = True
 

examples/guessing_game.py

@@ -4,6 +4,7 @@ import discord
 import random
 import asyncio
 
+
 class MyClient(discord.Client):
     async def on_ready(self):
         print(f'Logged in as {self.user} (ID: {self.user.id})')
@@ -32,6 +33,7 @@ class MyClient(discord.Client):
             else:
                 await message.channel.send(f'Oops. It is actually {answer}.')
 
+
 intents = discord.Intents.default()
 intents.message_content = True
 

examples/modal.py

@@ -9,7 +9,7 @@ import traceback
 intents = discord.Intents.default()
 client = discord.Client(intents=intents)
 
-# We need an `discord.app_commands.CommandTree` instance 
+# We need an `discord.app_commands.CommandTree` instance
 # to register application commands (slash commands in this case)
 tree = app_commands.CommandTree(client)
 
@@ -18,6 +18,7 @@ tree = app_commands.CommandTree(client)
 # to test it in a guild.
 TEST_GUILD = discord.Object(ID)
 
+
 @client.event
 async def on_ready():
     print(f'Logged in as {client.user} (ID: {client.user.id})')
@@ -26,6 +27,7 @@ async def on_ready():
     # Sync the application command with Discord.
     await tree.sync(guild=TEST_GUILD)
 
+
 class Feedback(discord.ui.Modal, title='Feedback'):
     # Our modal classes MUST subclass `discord.ui.Modal`,
     # but the title can be whatever you want.
@@ -35,7 +37,7 @@ class Feedback(discord.ui.Modal, title='Feedback'):
     # By default, it is required and is a short-style input which is exactly
     # what we want.
     name = discord.ui.TextInput(
-        label='Name', 
+        label='Name',
         placeholder='Your name here...',
     )
 
@@ -55,7 +57,7 @@ class Feedback(discord.ui.Modal, title='Feedback'):
         await interaction.response.send_message(f'Thanks for your feedback, {self.name.value}!', ephemeral=True)
 
     async def on_error(self, error: Exception, interaction: discord.Interaction) -> None:
-        await interaction.response.send_message('Oops! Something went wrong.', ephemeral=True) 
+        await interaction.response.send_message('Oops! Something went wrong.', ephemeral=True)
 
         # Make sure we know what the error actually is
         traceback.print_tb(error.__traceback__)
@@ -66,4 +68,5 @@ async def feedback(interaction: discord.Interaction):
     # Send the modal with an instance of our `Feedback` class
     await interaction.response.send_modal(Feedback())
 
+
 client.run('token')

examples/new_member.py

@@ -2,6 +2,7 @@
 
 import discord
 
+
 class MyClient(discord.Client):
     async def on_ready(self):
         print(f'Logged in as {self.user} (ID: {self.user.id})')

examples/reaction_roles.py

@@ -2,15 +2,16 @@
 
 import discord
 
+
 class MyClient(discord.Client):
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
 
-        self.role_message_id = 0 # ID of the message that can be reacted to to add/remove a role.
+        self.role_message_id = 0  # ID of the message that can be reacted to to add/remove a role.
         self.emoji_to_role = {
-            discord.PartialEmoji(name='🔴'): 0, # ID of the role associated with unicode emoji '🔴'.
-            discord.PartialEmoji(name='🟡'): 0, # ID of the role associated with unicode emoji '🟡'.
-            discord.PartialEmoji(name='green', id=0): 0, # ID of the role associated with a partial emoji's ID.
+            discord.PartialEmoji(name='🔴'): 0,  # ID of the role associated with unicode emoji '🔴'.
+            discord.PartialEmoji(name='🟡'): 0,  # ID of the role associated with unicode emoji '🟡'.
+            discord.PartialEmoji(name='green', id=0): 0,  # ID of the role associated with a partial emoji's ID.
         }
 
     async def on_raw_reaction_add(self, payload: discord.RawReactionActionEvent):
@@ -78,6 +79,7 @@ class MyClient(discord.Client):
             # If we want to do something in case of errors we'd do it here.
             pass
 
+
 intents = discord.Intents.default()
 intents.members = True
 

examples/reply.py

@@ -2,6 +2,7 @@
 
 import discord
 
+
 class MyClient(discord.Client):
     async def on_ready(self):
         print(f'Logged in as {self.user} (ID: {self.user.id})')
@@ -15,6 +16,7 @@ class MyClient(discord.Client):
         if message.content.startswith('!hello'):
             await message.reply('Hello!', mention_author=True)
 
+
 intents = discord.Intents.default()
 intents.message_content = True
 

examples/secret.py

@@ -10,15 +10,16 @@ intents.message_content = True
 
 bot = commands.Bot(command_prefix=commands.when_mentioned, description="Nothing to see here!", intents=intents)
 
-# the `hidden` keyword argument hides it from the help command. 
+# the `hidden` keyword argument hides it from the help command.
 @bot.group(hidden=True)
 async def secret(ctx: commands.Context):
     """What is this "secret" you speak of?"""
     if ctx.invoked_subcommand is None:
         await ctx.send('Shh!', delete_after=5)
 
+
 def create_overwrites(ctx, *objects):
-    """This is just a helper function that creates the overwrites for the 
+    """This is just a helper function that creates the overwrites for the
     voice/text channels.
 
     A `discord.PermissionOverwrite` allows you to determine the permissions
@@ -31,10 +32,7 @@ def create_overwrites(ctx, *objects):
 
     # a dict comprehension is being utilised here to set the same permission overwrites
     # for each `discord.Role` or `discord.Member`.
-    overwrites = {
-        obj: discord.PermissionOverwrite(view_channel=True)
-        for obj in objects
-    }
+    overwrites = {obj: discord.PermissionOverwrite(view_channel=True) for obj in objects}
 
     # prevents the default role (@everyone) from viewing the channel
     # if it isn't already allowed to view the channel.
@@ -45,15 +43,16 @@ def create_overwrites(ctx, *objects):
 
     return overwrites
 
+
 # since these commands rely on guild related features,
 # it is best to lock it to be guild-only.
 @secret.command()
 @commands.guild_only()
 async def text(ctx: commands.Context, name: str, *objects: typing.Union[discord.Role, discord.Member]):
-    """This makes a text channel with a specified name 
+    """This makes a text channel with a specified name
     that is only visible to roles or members that are specified.
     """
-    
+
     overwrites = create_overwrites(ctx, *objects)
 
     await ctx.guild.create_text_channel(
@@ -63,6 +62,7 @@ async def text(ctx: commands.Context, name: str, *objects: typing.Union[discord.
         reason='Very secret business.',
     )
 
+
 @secret.command()
 @commands.guild_only()
 async def voice(ctx: commands.Context, name: str, *objects: typing.Union[discord.Role, discord.Member]):
@@ -75,9 +75,10 @@ async def voice(ctx: commands.Context, name: str, *objects: typing.Union[discord
     await ctx.guild.create_voice_channel(
         name,
         overwrites=overwrites,
-        reason='Very secret business.'
+        reason='Very secret business.',
     )
 
+
 @secret.command()
 @commands.guild_only()
 async def emoji(ctx: commands.Context, emoji: discord.PartialEmoji, *roles: discord.Role):
@@ -94,7 +95,7 @@ async def emoji(ctx: commands.Context, emoji: discord.PartialEmoji, *roles: disc
         name=emoji.name,
         image=emoji_bytes,
         roles=roles,
-        reason='Very secret business.'
+        reason='Very secret business.',
     )
 
 

examples/views/confirm.py

@@ -9,7 +9,7 @@ class Bot(commands.Bot):
     def __init__(self):
         intents = discord.Intents.default()
         intents.message_content = True
-        
+
         super().__init__(command_prefix=commands.when_mentioned_or('$'), intents=intents)
 
     async def on_ready(self):

examples/views/counter.py

@@ -9,7 +9,7 @@ class CounterBot(commands.Bot):
     def __init__(self):
         intents = discord.Intents.default()
         intents.message_content = True
-        
+
         super().__init__(command_prefix=commands.when_mentioned_or('$'), intents=intents)
 
     async def on_ready(self):

examples/views/dropdown.py

@@ -15,7 +15,7 @@ class Dropdown(discord.ui.Select):
         options = [
             discord.SelectOption(label='Red', description='Your favourite colour is red', emoji='🟥'),
             discord.SelectOption(label='Green', description='Your favourite colour is green', emoji='🟩'),
-            discord.SelectOption(label='Blue', description='Your favourite colour is blue', emoji='🟦')
+            discord.SelectOption(label='Blue', description='Your favourite colour is blue', emoji='🟦'),
         ]
 
         # The placeholder is what will be shown when no option is chosen
@@ -26,7 +26,7 @@ class Dropdown(discord.ui.Select):
     async def callback(self, interaction: discord.Interaction):
         # Use the interaction object to send a response message containing
         # the user's favourite colour or choice. The self object refers to the
-        # Select object, and the values attribute gets a list of the user's 
+        # Select object, and the values attribute gets a list of the user's
         # selected options. We only want the first one.
         await interaction.response.send_message(f'Your favourite colour is {self.values[0]}')
 
@@ -43,14 +43,14 @@ class Bot(commands.Bot):
     def __init__(self):
         intents = discord.Intents.default()
         intents.message_content = True
-        
+
         super().__init__(command_prefix=commands.when_mentioned_or('$'), intents=intents)
 
     async def on_ready(self):
         print(f'Logged in as {self.user} (ID: {self.user.id})')
         print('------')
-    
-    
+
+
 bot = Bot()
 
 

examples/views/ephemeral.py

@@ -4,17 +4,19 @@ from discord.ext import commands
 
 import discord
 
+
 class EphemeralCounterBot(commands.Bot):
     def __init__(self):
         intents = discord.Intents.default()
         intents.message_content = True
-        
+
         super().__init__(command_prefix=commands.when_mentioned_or('$'), intents=intents)
 
     async def on_ready(self):
         print(f'Logged in as {self.user} (ID: {self.user.id})')
         print('------')
 
+
 # Define a simple View that gives us a counter button
 class Counter(discord.ui.View):
 
@@ -33,6 +35,7 @@ class Counter(discord.ui.View):
         # Make sure to update the message with our updated selves
         await interaction.response.edit_message(view=self)
 
+
 # Define a View that will give us our own personal counter button
 class EphemeralCounter(discord.ui.View):
     # When this button is pressed, it will respond with a Counter view that will
@@ -42,11 +45,14 @@ class EphemeralCounter(discord.ui.View):
         # ephemeral=True makes the message hidden from everyone except the button presser
         await interaction.response.send_message('Enjoy!', view=Counter(), ephemeral=True)
 
+
 bot = EphemeralCounterBot()
 
+
 @bot.command()
 async def counter(ctx: commands.Context):
     """Starts a counter for pressing."""
     await ctx.send('Press!', view=EphemeralCounter())
 
+
 bot.run('token')

examples/views/link.py

@@ -5,11 +5,12 @@ from discord.ext import commands
 import discord
 from urllib.parse import quote_plus
 
+
 class GoogleBot(commands.Bot):
     def __init__(self):
         intents = discord.Intents.default()
         intents.message_content = True
-        
+
         super().__init__(command_prefix=commands.when_mentioned_or('$'), intents=intents)
 
     async def on_ready(self):

examples/views/tic_tac_toe.py

@@ -124,7 +124,7 @@ class TicTacToeBot(commands.Bot):
     def __init__(self):
         intents = discord.Intents.default()
         intents.message_content = True
-        
+
         super().__init__(command_prefix=commands.when_mentioned_or('$'), intents=intents)
 
     async def on_ready(self):