Cog Watch

Automatic hot-reloading for your discord.py command files.

cogwatch is a utility that you can plug into your discord.py bot (or various supported bot libraries) that will watch your command files directory (cogs) and automatically reload them as you modify or move them around in real-time.

No more reloading your commands manually every time you edit an embed just to make sure it looks perfect!

Features

• Automatically reloads commands in real-time as you edit them (no !reload <command_name> needed).
• Optionally handles the loading of all your commands on start-up (removes boilerplate).

Supported Libraries

cogwatch should work with any library that forked from discord.py. However, these libraries have been explicitly tested to work:

• discord.py
• nextcord
• discord4py
• disnake
• pycord

Getting Started

You can install the library with pip install cogwatch.

Import the watch decorator and apply it to your on_ready method and let the magic take effect.

See the examples directory for more details.

import asyncio
from discord.ext import commands
from cogwatch import watch


class ExampleBot(commands.Bot):
    def __init__(self):
        super().__init__(command_prefix='!')

    @watch(path='commands', preload=True) # This is all you need to add.
    async def on_ready(self):
        print('Bot ready.')

    async def on_message(self, message):
        if message.author.bot:
            return

        await self.process_commands(message)


async def main():
    client = ExampleBot()
    await client.start('YOUR_TOKEN_GOES_HERE')

if __name__ == '__main__':
    asyncio.run(main())

NOTE: If you're following the example command files in the examples directory, make sure you only use async/await on your setup function if the library you're using supports it. For example, discord.py uses async setup functions, but many other libraries do not. cogwatch supports both under-the-hood.

Configuration

These options can be passed to the decorator (or the class if manually initializing):

Option	Type	Description	Default
path	str	Path of the directory where your command files exist; cogwatch will watch recursively within this directory.	commands
preload	bool	Whether to detect and load all cogs on start.	False
colors	bool	Whether to use colorized terminal outputs or not.	True
default_logger	bool	Whether to use the default logger (to sys.stdout) or not.	True
loop	AbstractEventLoop	Custom event loop.	get_event_loop()
debug	bool	Whether to run the bot only when the Python __debug__ flag is True.	True

NOTE: cogwatch will only run if the __debug__ flag is set on Python. You can read more about that here. In short, unless you run Python with the -O flag from your command line, __debug__ will be True. If you just want to bypass this feature, pass in debug=False and it won't matter if the flag is enabled or not.

Logging

By default, the utility has a logger configured so users can get output to the console. You can disable this by passing in default_logger=False. If you want to hook into the logger -- for example, to pipe your output to another terminal or tail a file -- you can set up a custom logger like so:

import logging
import sys

watch_log = logging.getLogger('cogwatch')
watch_log.setLevel(logging.INFO)
watch_handler = logging.StreamHandler(sys.stdout)
watch_handler.setFormatter(logging.Formatter('[%(name)s] %(message)s'))
watch_log.addHandler(watch_handler)

Contributing

cogwatch is open to all contributions. If you have a feature request or found a bug, please open an issue or submit a pull request. If your change is significant, please open an issue first to discuss it.

Check out the contributing guidelines for more details.

Integration Tests

In order to test cogwatch against all of the supported libraries, there is a small integration test suite built-in to this repository. These are not automatically checked tests, but rather a way to manually set up the environment for a specific library and run a bot with cogwatch to ensure it works as expected.

The available scripts are:

• poetry run discord4py
• poetry run discordpy
• poetry run disnake
• poetry run nextcord
• poetry run pycord

License

cogwatch is available under the MIT License.